ConfigurationLast updated: 10 December 2022

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:

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.

Image Path prefix / Path to Image CDN

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.

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, and control how JCOGS Image approaches automatic management of the cache contents.

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 - the default directory and any others that have been specified via  the cache_dir= parameter within a tag.

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.

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 four settings available that relate to caching system operation:

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.

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.

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.

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.

Image Operational Defaults

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.

• LQIP 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.
• A third 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 gives marginally better performance compared to disabling lazy loading on modern browsers where you are sure that javascript is enabled. In all other cases, enabling Lazy Loading will result in faster page loading.

Enable progressive enhancement mode.

When either LQIP or Dominant Colour modes are chosen for Lazy Loading, this option adds some additional code to the rendered template to ensure that the images generated will render correctly in browsers where javascript support is not present or not enabled (fewer than 1% of web users). 

It is strongly recommended that you leave this option enabled. 

Disabling this option may speed the loading of pages slightly, but potentially will also result in visitors using browsers with javascript disabled seeing degraded images.  If absolute speed in modern browsers is important, a better solution would be to select the HTML5 option in the Lazy Loading Mode selector above.

Note: This option has no effect if HTML5 mode is chosen, or Lazy Loading is disabled.

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.

View Advanced Options

When enabled, this slider displays a range of advanced system options. Each option 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.
 

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 _-_.

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.

Maximum Source Image Size (MB)

Set a maximum size for image source files: source files that are larger than the limit set will not be processed. Enter an integer value equal to the maximum size in Mbytes an image file may be (e.g. 4).

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.

If this limit is set to a high value (e.g. over 6) it is possible that your server may try to exceed its memory usage or process time limits while 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 4 (Mbytes) is usually ample for most web purposes.

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. For more information about JCOGS Image Licensing and how the license status affects how JCOGS Image operates, see the separate section on this elsewhere in this documentation.

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.