ConfigurationLast updated: 15 October 2024

System Settings settings are ones that primarily control how the add-on interacts with ExpressionEngine and its wider server environment.

Each of the System Settings options are described below:

On/Off Control

Enable JCOGS Image

Controls whether the add-on is in operation or not.  When this is set to off JCOGS Image tags within your templates will be disabled - i.e. the tags will be read and removed from your templates, but produce no output.

Action Link Settings

Generating Image via a manual Action Link

JCOGS Image's Action Link system let's you process ‘single’ JCOGS Image tags via an ExpressionEngine ACT link. 

Enable JCOGS Image automatic Action Links

This option sets the default option for generation of automatic Action Links.

Debugging Options

Enable Debugging Messages in Template Log

When enabled this causes JCOGS Image to add informative messages about its activities to the Template Log.

Cache controls are used to set defaults for where, and for how long JCOGS Image will keep copies of processed images. You can also:

• get information about the content of the image caches being used, 
• clear the image caches, 
• control how JCOGS Image approaches automatic management of the cache contents,
• control the location of the cached images.

Each of the elements of this panel are described below:

Image Cache Status

Here Image will report on the status of the caching system. The status report will scan across all the cache directories it is aware of on the File System selected to hold the cache - these being the default directory and any others that have been specified via  the cache_dir= parameter within a tag.

Cache status is held separately for each File System that is setup for Image, and so the statistics associated with the cache will change as you switch between File System choices.

Image Cache Controls

Image provides two kinds of control relating to the caching system:

Run an Image Cache Audit

If it is enabled, running a cache audit will remove from the cache any images that have existed there for longer than the cache duration set for them when they were saved. This action will save server disk space but will not otherwise affect Image's operations.

When there is something in the cache, you can use the button shown in this section to trigger a cache audit.

Clear the Image Cache

JCOGS Image actively manages its image cache - automatically replacing images that have reached the end of their cache life as required, and (if cache auditing is enabled) periodically validating that all cache expired images are removed. However sometimes it is useful / helpful to be able to clear the image cache - an action this button carries out.

When you clear the image cache the operation is performed for all the cache directories Image is aware of - the default directory and any others that have been specified via the cache_dir= parameter within a tag, and across all File Systems defined for the Image Cache.

Note: Manually clearing the image cache removes all the images stored within the cache regardless of cache duration setting; the next time a JCOGS Image tag is loaded it will need to regenerate the processed image.

Image Cache Settings

There are five settings available that relate to caching system operation:

Default image duration for cached images (in seconds)

The default value is the equivalent of one month (31 days - so 31 x 24 x 60 x 60): a value which maximises cache operation while still allowing JCOGS Image's auto-cache clearing process to keep the cache tidy. Set the value to -1 to have a default of a perpetual cache (i.e. cached images are never removed - similar to the caching model used in CE-Image). Set the value to 0 to have a default where the cache is disabled. Can be overridden by the cache= parameter within a tag.

Enable Cache Auto-Management

When this option is is enabled, JCOGS Image will monitor the File Manager system; when an image that has been used to generate one or more images in the JCOGS Image cache is modified those processed images will be cleared from the cache. This is to ensure that any changes made to the source image are reflected in the processed images shown on the site.

Note: If you are using EE Template Caching or some other static caching system, enabling this feature is not recommended.

Enable Image Cache Audits

When Image Cache Auditing is enabled, JCOGS Image will periodically remove from the default image cache folder (and from any other image cache folders specified via use of the cache_dir= parameter within JCOGS Image tags) any images that have existed for longer than the cache duration in force when they were saved.

Set the interval between image cache audits

When Image Cache Auditing is enabled, this setting allows you to specify the intervale between cache audits. The interval should be specified in seconds - Default value is one week - 60*60*24*7 = 604800 seconds.

Default Cache Directory

The directory JCOGS Image will use to store processed images. Can be overridden by the cache_dir= parameter within a tag.

Note: Since the image cache path needs to be one that is within your site's webroot JCOGS Image assumes that the a path entered here is relative to your webroot. If the path you specify does not exist JCOGS Image will attempt to create it. To minimise potential problems with JCOGS Image (and other add-ons) please also ensure that your EE 'default base path' is set correctly.

Cache Storage Location Options

JCOGS Image has the ability to locate its processed image cache on a variety of alternative File Systems. This section of the Cache Settings panel lets you provide information about these alternative File Systems - for Cloud based systems such as AWS S3 and Cloudflare R2 this section also enables you to enter the security information required to provide access to the cloud based services concerned. Also, unlike ExpressionEngine itself, access to cloud based File Systems is available for JCOGS Image instances running under either EE6 or EE7.

Note: JCOGS Image's access to Cloud based systems mirrors that provided for upload directories within EE7 - and indeed the settings that provide access for EE7 to a cloud service also can be used to enable JCOGS Image's access to the same cloud service; operations where EE connects to the same cloud instance for both file uploads and JCOGS Image concurrently is supported. However it is important to note that the configuration and operation of the two cloud file access systems are handled separately within EE making it is possible for the two systems to use File Connections - and so each needs to be configured separately, and access information needs to be entered separately for each system even if they are connecting to the same cloud file service.

Note: Configuring user access to cloud based file systems can be complicated due to the need to configure security access elements. The steps needed to configure the three cloud services currently supported by EE7 and JCOGS Image are well described in the EE7 Cloud Files documentation, and it is recommended that anyone looking to configure access accounts follow those instructions.

Note: Use of Cloud based systems can result in lower server traffic levels and faster page loading times for end users of a web site. However, since read / write disk operations to Cloud Services are significantly slower than the same operations to file storage attached directly to a webserver, it is not uncommon for image processing times for images stored on cloud file services to be slower than when the same operation is carried out using the Local File System adapter.

Currently there are four File System options available - more will likely be added in future. To select the File System to use, simply choose the option from the drop-down menu provided. As you choose different options, the form below the drop-down changes to reflect the information needed to configure the chosen service. Some points to note:

• File System configurations are remembered even if the option is de-selected - making it possible to setup multiple File System options and switch easily between them.
• In keeping with JCOGS Image's Unified Cache approach, only one cache file system can be used at a time - if multiple cache paths are specified, they will all be stored in the same File System.
• If you switch from one File System to another, the cache of the newly chosen File System will be consulted when building pages, and this may result in cache building activity initially, which may slow down page loads until cache building is complete.

The four systems are:

Local

The default File System. Files are stored in a disk storage location located below the web root of the web server that ExpressionEngine is running on. The only controllable option is to specify a default path from the web root to the folder within which the the cache of processed images should be stored.

AWS S3

S3 is a popular cloud based file system offered by Amazon Web Services. 

Cloudflare R2

R2 is a popular cloud based file system offered by Cloudflare based on the same underlying approach adopted by S3. It has some differences to S3 that make it easier to configure and use, but also in testing offers slightly less good performance.

DigitalOcean Spaces

Similar to S3, DO Spaces are normally linked to DigitalOcean hosting services.

Local Image Path Options

When using the Local Image adapter there are some additional options available relating to how locally cached images are rendered in HTML tags.

Use full URLs in paths to processed images

JCOGS Image normally generates HTML tags with relative paths to processed images. This choice gives the best performance on most systems. On some server systems there may be problems resolving relative paths to processed images. Where this occurrs this option allows you to instruct JCOGS Image to always use full URLs to reference the processed images.

Note: If you choose this option you will not be able to set a processed image prefix to a CDN or similar (since you will have already told Image that you want to use the local server URL instead).

Specify a default image path prefix (e.g. to an image CDN server / service)

This option is only visible when the option “Use full URLs in paths to processed images” is disabled.

To use this option, enter a default prefix for the published path to a processed image.

If entered, this value will be prefixed to the processed image path in all HTML tags generated by JCOGS Image and will also made available via the {made_with_prefix} variable.

Note: Even if specified here, the prefix will only be added to a JCOGS Image tag that has the parameter use_image_path_prefix='yes' set, otherwise this value is ignored.

The value can be overridden within a tag by setting the parameter image_path_prefix=. The default value for this setting is blank.

Image Default Settings

Image Default settings are ones that primarily affect how the add-on interacts with the images you wish it to process.

Each of the Image Defaults options are described below:

Image Format Options

Default image format

The default image format to use for processed images; can be overridden by using the save_type= parameter within a tag.
The default value is ‘Use format of source image’ which tells JCOGS Image to try and use source image's format for the default image output format. 

The other options offered in this drop down are those image formats that your server is able to write/create. 

Note: Not all image formats can be rendered by browsers. If you choose a format that a visitor's browser cannot render, JCOGS Image's dynamic image format selection feature will ensure (for that visitor only) that a substitute image format is used for that image that the visitors browser can can work with - usually JPG.

Default quality for JPG and WEBP images

Both these image formats can be saved at a range of ‘quality’ values - where 100 represents the best quality possible, 0 the worst. Choosing a lower quality will reduce the file size of the image produced, but will also reduce the image quality. The default value of 90 is good for most purposes. This default setting can be over-ruled on a tag-by-tag basis through the use of the quality= parameter.

Note: If your server is running php8.1 setting this value to 100 will cause JCOGS Image to render webp images using the webp lossless format.

Default background colour

Some operations need to create an area ‘behind’ an image (rotation, removal of transparency, adding a border). This sets the default colour to be used for this area. 

This default setting can be over-ruled on a tag by tag basis through the use of the bg_color= parameter.

Image Operational Defaults

Set default width for unsized images

Operations within JCOGS Image sometimes need to know the width of the original image: for example when Image replaces a missing image with a colour field, or when the image is an SVG. Not all SVG image files contain this information. Some do, others just an aspect ratio (but no base width) and some no information at all. If the SVG contains width information that value will be used to set the original width value for the image, otherwise this value will be used as the default width (in px). This option can be over-ridden by use of the default_img_width= parameter within a tag.

The default value of 350px mirrors the default value used for this same purpose by the SVG renderers in most web browsers.

Set default height for unsized images

Operations within JCOGS Image sometimes need to know the width of the original image: for example when Image replaces a missing image with a colour field, or when the image is an SVG. Not all SVG image files contain this information. Some do, others just an aspect ratio (but no base width) and some no information at all. If the SVG contains width information that value will be used to set the original width value for the image, otherwise this value will be used as the default width (in px). This option can be over-ridden by use of the default_img_height= parameter within a tag.

The default value of 150px mirrors the default value used for this same purpose by the SVG renderers in most web browsers.

Enable SVG Passthrough by default

By default this option is disabled; while disabled JCOGS Image rejects tags that specify svg images as the image source.

Selecting this option will enabled JCOGS Image's SVG Passthrough mode. 

When this is enabled JCOGS Image will process tags that specify SVG images as the source image. Currently the amount of processing done is limited to the retrieval of remote images, caching images and applying size adjustment changes. 

This option can be over-ridden by use of the svg_passthrough= parameter within a tag.

Enable dominance for preserving animated gif image formats

By default this option is disabled.

When enabled JCOGS Image will ignore save_type= settings when processing an image source file containing an animated gif.

Allow Scale Larger parameter default setting

When the Allow Scale Larger default is set to enabled JCOGS Image will enlarge images to fit dimensions given if the source image is smaller than the final dimensions required by the settings in a JCOGS Image tag. The initial default settings for this option is disabled. This setting is over-ridden by the value given by a allow_scale_larger= parameter within a tag.

Auto Sharpening parameter default setting

When the  Auto sharpen default is set to enabled JCOGS Image will automatically apply the auto-sharpen filter to every image. The auto-sharpen filter increases the sharpness of images that have been reduced in size during manipulations; the greater the reduction in size the greater the degree of sharpening applied. This option can be over-ridden by use of the auto_sharpen= parameter within a tag.

Lazy parameter default setting

When the Lazy parameter default is set to enabled JCOGS Image will set the <img> tags it creates to lazy-load by default. Can be overridden by using the  lazy= parameter within a tag.

Enabling this option opens up two further options:

Choose default lazy loading mode.

When lazy-loading is enabled JCOGS Image will initially load an image tag with a smaller placeholder image prior to its the "lazy" replacement by the full-quality image. Placeholder images can be either a Low Quality Image Placeholder (LQIP) or a Dominant Colour Field.

There are five options available for controlling the default setting for lazy loading:

• Low Quality Image Placeholder is a low-resolution but recognisable version of the processed image that is typically about 25% of the size of the processed image.

• Dominant Colour Field replaces the image with a colour-field the same size as the processed image with the colour set to the most-common colour found in the processed image.

• Javascript Method Low Quality Image Placeholder works similarly to the regular Low Quality Image Placeholder option, but uses a javascript based approach to replacing the lazy image with the full resolution image, and requires a small amount of javascript to be added to your template when it is sent to your browser. This option is slightly less well supported than the regular approach, but is useful if you are trying to lazy load images that include transparency.

• Javascript Method Dominant Colour Field works similarly to the regular Dominant Colour Field option, but uses a javascript based approach to replacing the lazy image with the full resolution image, and requires a small amount of javascript to be added to your template when it is sent to your browser. This option is slightly less well supported than the regular approach, but is useful if you are trying to lazy load images that include transparency.

• A final option - HTML5 - is offered that does not add the placeholder substitution but does add the HTML5 loading="lazy" parameter to the completed image tag. This option is included for compatibility purposes, but in most cases, enabling Lazy Loading will result in faster page loading.

Enable progressive enhancement mode.

When the javascript variants of Low Quality Image Placeholder or Dominant Colour Field modes are chosen for Lazy Loading, JCOGS Image adds some additional javascript code to the rendered template to ensure that the method works. On browsers where javascript support is not present or not enabled (fewer than 1% of web users) use of this approach will lead to imperfect outputs: the lazy image will never be replaced with the full resolution image. Enabling this option will cause JCOGS Image to add some further code to your template to ensure that images are correctly displayed on browsers that have javascript support not present or disabled.

Note: This option has no effect if the regular lazy loading options, or HTML5 mode is chosen, or Lazy Loading is disabled within the tag.

It is strongly recommended that you leave this option enabled. 

Set a default fallback image

If you fail to specify an image, or if the image you specify is not available, you can use this setting to control how JCOGS Image responds.

There are four options:
    • No default fallback image - JCOGS Image will abandon processing if it cannot open a source image
    • Use a colour field - the add-on will replace the missing image with a blank colour field of the same size as the missing image
    • Use a local fallback image - choose an image to use as a fallback from those registered with the File section of your EE server
    • Use a remote fallback image - choose an image to use as a fallback from a remote internet location

The fallback options will only be activated if the tag specifies (or implies) both the width and height of the image to be inserted - so either two dimensions need to be specified (width, height) or one dimension and an aspect ratio. 

This default setting can be over-ruled on a tag-by-tag basis through the use of the fallback_src= parameter.

Operational Limits

Enable Auto-adjust for Oversized Source Images

If selected this enables JCOGS Image's ability to Auto-adjust oversized source images based on either the file size or dimensions.

While this option is enabled JCOGS Image will try to rescale source images that exceed either of the set limits and so create a smaller interim version of the image file that is compliant with the limits which will then be used as the base for any image transformations requested. Using the smaller interim version may improve overall processing speed and mitigate problems that would otherwise be caused by hitting php resource limits on your server.

Note: A source image is considered to be oversized if it exceeds either your choice for the a maximum dimension for the source image or your choice for the maximum file size for the source image.

Images are tested first against the image dimension limit (if set) and then against the size limit.

Note: If this options is disabled, the constraint on maximum file size will still be applied, but rather than triggering an attempt to rescale the image, the limit will cause Image to not attempt to process the image.

Maximum dimension limit for source image processing (px)

Set a maximum dimension for source image files. If Auto-adjust for Oversized Source Images is enabled, JCOGS Image will attempt to temporarily rescale any source file that is larger than the set limit in either dimension such that its maximum dimension equals the limit value (the image aspect ratio is preserved). 

• Setting this limit can help to mitigate problems caused by php resource limits on your server.
• The limit is expressed as an integer pixel value: to enter a value use an integer value (e.g. 2500).
• To disable this option set this value to zero (which is the default value).
•  

Maximum source image size (MB)

Set a maximum filesize for source image files.

If Auto-adjust for Oversized Source Images is enabled, JCOGS Image will attempt to temporarily rescale any source image with a filesize larger than the set limit to one with a filesize smaller than the limit. Otherwise a source file that has a filesize larger than the limit set it will not be processed.

• Enter an integer value equal to the maximum size in Mbytes an image file may be (e.g. 4 - the default value).

The advanced configuration settings for JCOGS Image are primarily intended to support more complex usage cases; in normal usage you should not need to change any of these settings from their default values.

The advanced configuration options are normally hidden behind the View Advanced Options slider on this page: this is purposely there to encourage users to pause before making changes to advanced settings.

Caution: These settings should only be changed if a specific issue requires it.

Advanced Settings

View Advanced Options

When enabled, this slider displays a range of advanced system options.

 Each advanced setting is described below. 

Enable active checking of browser capabilities

When enabled JCOGS Image will actively check the image rendering capabilities of the browser visiting your EE site; if the browser is not able to render the image format you have selected (either via the save_type= parameter, or via the default option for processed image file format) it will change the format of the processed image to be one that the browser can render; if the target image format is one that enables transparency the fallback format will be PNG, otherwise it will be JPG. The default value is enabled.

You can also disable browser checks on a tag-by-tag basis by using the disable_browser_checks="yes" parameter.

Enable class / style attribute consolidation for tag-pair operation

When enabled JCOGS Image will separately find and consolidate the contents of all of the class='' and style='' parameters if finds enclosed within a JCOGS Image tag-pair, along with the content of any class='' or style='' parameter specfied within the opening JCOGS Image tag, to ensure that there is at most a single composite class and / or style statement in the final tag produced. 

JCOGS Image will also remove any class duplicates. 

By default this function is enabled. 

You may want to disable the function if you plan to enclose complex HTML structures with multiple class statements within a JCOGS Image tag pair or nest multiple tags with differing class statements for each.

You can also disable class / style consolidation on a tag-by-tag basis by using the consolidate_class_style="no" parameter.

Enable expansion of Image Variables within attributes parameter text

When enabled JCOGS Image will expand any Image Variables found within the content of the attributes= parameter before the output tag is assembled.

By default this function is enabled.

Cache filename separator character(s)

The filenames JCOGS Image uses to identify processed images have three components: the original filename; a cache duration marker; and an image processing options marker. JCOGS Image needs to be able to separate out these three elements of the filename during its operations, and to do this uses a special character sequence to identify where the three sections start and stop.

The filename separator used can be any sequence of characters but it cannot include spaces or any reserved characters (which are !*\'();:@&=+$,/?#[]).

This setting allows you to change the filename separator to whatever you wish it to be. The default value is _-_.

Limit the maximum length of the reflected copy of source filename

When JCOGS Image constructs the filename used to save and reference a processed image, it includes a reflected copy of the source image filename. This option lets you set a limit for the length of this reflected filename. For operational reasons, this limit can not exceed 175 characters and so the default value set must be 175 or less. 

Note: If a filename is shortened a random number is automatically appended to it to avoid inadvertant name clashes arising.

Include path to image source in processed filename hash

When enabled, this option causes JCOGS Image to include the path to the source image within the information used to generate the processed filename's unique hash element. When this option is enabled, JCOGS Image will generate different processed images when processing two source images that share the same name but have been retrieved from different locations.
Note: when the status of this option is changed, it will it will effectively invalidate all existing processed images stored in your file cache(s), requiring all these images to be reprocessed.

Append path to processed image to Action Link 

When enabled, this option causes JCOGS Image to include a url-encoded version of the link to the processed image referenced by an Action Link within the Action Link (as an additional GET varaible). This additional element is a non-functional change, but the presence of the link maybe of utility to developers wishing to manipulate action links in server level caching systems.

CE Image Remote Image Cache Directory

If JCOGS Image cannot retrieve a remote image it will also look for it in (if present) the directory that had been used by CE Image to store local copies of remote images. While this is not a complete solution to missing remote images, this facility has been found to help during site updates / migrations: some sites have found that remote images were being used in the site content that were found to be no longer available; due to its perpetual caching strategy CE Image masked this absence by continuing to draw the image from its remote image cache. When the sites were updated the absence was found, sometimes resulting in broken pages until replacement images were identified. By looking for missing images in the CE Image remote image cache it is possible that this issue can be mitigated.

By default JCOGS Image looks in the default location that was used by CE Image (images/remote) - but if your installation has changed this, you can put the correct location into this setting.

Since the path needs to be one that is within your site's webroot JCOGS Image assumes that the a path entered here is relative to your webroot. To minimise potential problems with JCOGS Image (and other add-ons) please also ensure that your EE 'default base path' setting is set correctly.

Minimum requested php memory (MB)

Enter a mminimum size for requested php memory allocation: if currently allocated memory is greater than this nothing will change, if less the add-on will temporarily request the specified higher amount from php.

Note: It is strongly recommended that you try fixing any processing issues by changing the setting for Maximum Dimension Limit for Source Image Processing before you consider adjusting this value.

Increase this value if your server reports exceeding its memory usage limits when processing images: when such happens image processing will fail and may halt the EE system too (resulting in users seeing the "White Screen of Death"). The default value of 64 (Mbytes) is usually ample for most web purposes.

Minimum requested php execution time (seconds)

Enter a minimum execution time limit to request from php: if currently allocated minimum execution time is greater than this nothing will change, if less the add-on will temporarily request the specified higher limit from php. 

Increase this value if your server reports exceeding its execution time limits - when such happens image processing will fail and may halt the EE system too (resulting in users seeing the "White Screen of Death"). The default value of 30 (seconds) is usually ample for most web purposes. Requesting a value of 0 prevents php from timing out.

Minimum remote connection time (seconds)

Enter a minimum duration for remote connections to request from php. If this value is too low your server may not have time to complete retrieval of large images from slow internet locations. Increase this value if your JCOGS Image debug log reports that remote image retrievals are failing due to connection timeout. The default value of 3 (seconds) is usually ample for most web purposes.

User agent string to use for remote file retrieval

Specify a user-agent string to report to remote servers when retriveing images from remote locations on the web. The default value works well for most web purposes.

JCOGS License Server Domain

JCOGS Image needs to contact a licensing server to validate your license key / email pair: this option allows you to change the domain used for this server. Changing this value unless directed to do so by JCOGS Design support is not recommended: doing so is likely to prevent the add-on from contacting the licensing server and lead to your software operating in demonstration mode.

System Settings settings are ones that primarily control how the add-on interacts with ExpressionEngine and its wider server environment.

Each of the System Defaults options are described below:

License

JCOGS Image License Key

Provides feedback on the current licensing status of the add-on, and an input box to enter a license key value. 

Note: For more information about JCOGS Image Licensing and how the license status affects how JCOGS Image operates, see the separate section on this topic.

Enter License Key email address

Your license key is linked to the email address used when you purchased the license - you must enter both the license and the email for the key to be validated. Use this input box to enter the appropriate email.

Register a staging domain

Note: This field only appears after you have successfully entered a valid license for JCOGS Image.

You can enter here the domain name used by a staging server linked to the live EE site used to register the JCOGS Image license. 

The staging server domain can be one open to the public internet. 

If copy of this add-on is installed on an EE server located at the domain entered into the staging domain field, that copy of JCOGS Image will be automatically validated - you will not need (or be able) to enter your license details a second time.

JCOGS Image provides considerable control over the configuration of the addon via settings pages within the add-on's area in the ExpressionEngine control panel. These settings control a combination of system configuration settings (such as details of the file system adapter to be used) and parameter defaults.

Many of these settings can be also set by way of entries in the ExpressionEngine config.php file. Enter a setting using the format:

$config['parameter'] = ‘value’; - for example: $config['jcogs_img_allow_scale_larger'] = 'yes';

Details of the settings that can be set this way are given in the table below: