Add-on Documentation from JCOGS Design

ConfigurationLast updated: 5 November 2022

The add-on can be used 'out of the box' without further configuration; most settings can be adjusted on a case by case basis by parameters added to the JCOGS Image tag. 

If you want to change the default values used by JCOGS Image for its settings, this can be achieved via the add-on's Control Panel settings area. The settings are spread over two pages which are described in more detail below.

System Defaults

System Default 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 and On/Off Control

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

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.

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 Options

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.

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.

Image Cache Options

Image Caching Report

A summary of the status of the Image cache: whether it is operational; and if so what is stored within it and when the cache was last manually reset.

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

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.

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.

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.

Image Default Settings

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.

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.

Set default width for unsized SVG images

Operations within JCOGS Image sometimes need to know the width of the original image: 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 svg_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 SVG images

Operations within JCOGS Image sometimes need to know the width of the original image: 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 svg_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.

Image Enhancement Options

Enable Auto Sharpening by default

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

Enable Lazy Loading by Default

Determines whether JCOGS Image will creates lazy-loading <img> tags 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

Maximum dimension limit for source image processing

This option allows you to set a maximum dimension for image source files to have prior to beginning the processing of the image.

If this option is enabled and a JCOGS Image is fed a source file that is larger than the set limit in either dimension a rescaled interim version of the image file will be generated prior to processing with its maximum dimension (i.e. either width or height as appropriate) set to the limit value, and the other value scaled in proportion (so 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).

Caution:

    • If this limit is set to too high a value (e.g. over 3000) it is possible that your server may try to exceed its memory usage or process time limits when processing an image - when such happens image processing will fail and may halt the EE system too (resulting in users seeing the "White Screen of Death").
    • If this limit is set to too low a value (e.g. under 500) you might begin to see processing artifacts in your final output.

To disable this option set this value to zero (the default value).

Advanced Settings

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.

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

Enable automatic image cache maintenance

When enabled, JCOGS Image will periodically review the content of the default image cache directory and remove any cached images that have remained longer than the cache duration in force when they were saved.

Set the interval between image cache audits

This setting controls the interval between cache maintenance activities - choose an integer number of seconds. Default value is one week - 60*60*24*7 = 604800 seconds.

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.

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.

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.