Add-on Documentation from JCOGS Design

Advanced TopicsLast updated: 14 March 2024

Migrating from CE Image

JCOGS Image is a modern, supported, effective replacement for CE Image

CE Image is an image manipulation add-on that was created to work with ExpressionEngine 2 and 3. In its day it was a popular add-on and is implemented on many legacy sites. However CE Image is not supported and has not been updated since 19 June 2017 (when version 3.0.1 was released): sites that use it face challenges when updating to newer versions of ExpressionEngine as recoding the templates of these older sites to use alternative solutions is time consuming and difficult.

JCOGS Image is an entirely new add-on written expressly for use on EE5, EE6 and EE7 systems and offers developers a simple to implement high quality upgrade path for sites that were developed using CE Image. JCOGS Image offers a very high degree of tag-level compatibility with CE Image; is compatible with the latest features of the ExpressionEngine CMS; is fully compatible with php8 and is actively supported.  In addition, JCOGS Image provides powerful extensions to the Image processing capabilities of EE, providing support for additional image formats, a broad range of manipulations and filter options, and useful built in features such as automatic lazy loading.

Parameter compatibility

Currently JCOGS Image has full functional compatibility with CE Image at the parameter level, implementing 36 of the the 37 operations found in CE IMage - only two maniuplations are not fully supported: ascii_art (which is not supported at all) and rounded_corners (which has a small limitation relating to transparency control for corners).  A handful of non-transformational parameters mostly associated with file handling are not supported, where differences in how JCOGS Image approaches file and caching operations make them not meaningful: when such parameters are included in a JCOGS Image tag they will simply be ignored. In the very large majority of use cases JCOGS Image is able to fully replace CE Image.

Variable compatibility

JCOGS Image supports all of the variables that were made available by CE Image, so any code that relies upon this advanced use option will work identically with JCOGS Image.

Filter compatibility

JCOGS Image provides 100% compatibility with CE Image filter capabilities and its definition syntax for filters.

File handling compatibility

JCOGS Image approaches the storing and caching of processed images in a quite different way to CE Image. In practical terms these differences make no difference to operational use of the add-on, but do mean that some of the parametric controls available in CE Image are no longer necessary (or meaningful).

Performance compatibility

In a test profile covering all of the parametric and filter options available JCOGS Image was found to process images more quickly than CE Image on the same set of test operations, and produce smaller image files: across 33 equivalent images the files produced by JCOGS Image used approximately 55% of the space required by the CE Image output.

‘Drop-in’ upgrades

For most sites the very high degree of compatibility between JCOGS Image and CE Image tag parameters mean that updating a template is a straightfoward 3 step process:

  1. Install JCOGS Image add-on on your EE5, EE6 or EE7 system.
  2. Open a template in you favourite editor, search for “exp:ce_img” and replace these instances with “exp:jcogs_img”
  3. Save the template, reload the affected page in ExpressionEngine.

That's it. It's pretty easy and (to the best of our knowledge) works!  However if this is too much, we are working on an ‘auto update’ system that will do these steps for you… 

N.B. As would be the case for any update of a site, you are strongly encouraged to keep good backups while you do any major changes in site configuration or software.

Image Formats

Source Images

JCOGS Image can work with source images in all of the GD2 supported image formats (see notes on this in Processed Images below), plus it can also read HEIC images and has limited support for SVG and animated GIF format source images.

Processed Images

The format options available for processed images are determined primarily by the abilities of the php image processing library used on the server running the EE instance.

JCOGS Image actively checks what formats are supported by the server and only makes those available.

A list of the available processed image formats is available on the JCOGS Image Control Panel settings page in the drop-down for ‘Default Image Format’ (which also ensures that the Default Image Format is always one that can be processed by the server!).

If you specify an image format in a JCOGS Image tag that is not supported by the server, JCOGS Image will use the Default Image Format to encode the image instead.

For GD2 (the default library used by JCOGS Image) commonly available formats include:


image format


Windows bitmap format


Graphics Interchange Format


JPEG image format


Portable Network Graphics 



For an image to be seen in a browser it is also important that the browser viewing the web page also supports the image format chosen. Where possible, when processing an image JCOGS Image actively checks that the current browser is able to display the format chosen; if the browser would not be able to display the image format chosen JCOGS Image substitutes a format that is supported both by the server and the browser (usually JPG).

JCOGS Image offers limited support for handling SVG files and for animated GIF files - effectively both of these image types are passed through the add-on unchanged, but this feature allows them to be included in template workflows, and to benefit from JCOGS Image's image sizing and advanced cache management facilities. SVG Files are also ‘sanitised’ as part of this processing.

The choice of which image formats to use when is a complex discussion area, and outside the scope of this manual to consider.


Not all image formats support transparency. Where possible transparency in images is preserved by JCOGS Image during processing, but for transparency to be maintained in a processed image it is also important to make sure that the image is saved in a format that also supports transparency: in particular if you are manipulating a PNG image with transparency and wish the processed image to retain this transparency, make sure you specify an appropriate format either in the save_type= parameter in your tag, or as the Default Image Format.

Please note also that not all filter operations preserve transparency. 

When transparency is removed during a operation, the transparent pixes are replaced by pixels coloured according to whatever colour is chosen as the (default) background colour. 

Lossy vs Lossless

JCOGS Image always attempts to save images using the smallest file size option available for any given format. So for PNG and WebP images which support both lossy and lossless image storage formats, the images are saved using the lossy (compressed) format.

JCOGS Image offers both lossy and lossless compression options for these image formats (webp, png), however it is worth noting that this facility depends on support for these operations being available in the php libraries JCOGS Image uses: for example, saving lossless webp images requires the server to be running php 8.1 or better.

Image Optimisation

A variety of utilities offer options to ‘optimise’ images of some image formats (most notably images of PNG or JPG type). ‘Optimisation’ generate similar looking images to the source, but with a smaller filesize. Promotional literature for the various image optimisation routines available often note that dramatic file sze reductions can be obtained, particularly for PNG images. The saving in file size coming from usually the ommission of ‘redundant' data from the source image. However, to allow maniuplation of an optimised image, these optimisations usually have to be reversed.

JCOGS Image is able to work with most ‘optimised’ images,  but does not save images back to their optimised state.

The tools used by libraries to optimise images typically are not included in standard web server builds, and so it is not easy for JCOGS Image to include ‘optimisation’ steps within its core feature set (though such will be considered in some future update).

If you are using JCOGS Image on a regular server then JCOGS Image will automatically substitute an image format of that the user's browser can view should your site be viewed by a browser not able to handle webp images. If you are using JCOGS Image on a server with a static cache - where JCOGS Image's auto-substitution tools will not work - define your images using the HTML <picture> tag with web as the main image, with a jpg or png alternative image specified in a <source> declaration.

Usage Notes

Webp - better than optimised PNG 

In our limited testing we find that the filesize saving achieved by PNG optimisers while dramatic (up to 50%) is small compared to the saving achieved by moving a PNG to WEBP format (up to 75%). So our recommendation for now is that if minimisation of image filesize is critical to your application, consider using webp as the default image format. 

SVG Support

Passthrough Support for SVG

JCOGS Image version 1.2.16 introduces a new feature called SVG Passthrough Support.

The aim of this new feature is to enable SVG images to be functionally included within image workflows. Prior to this version JCOGS Image treated SVG images as an unrecognised format, and either loaded a fallback image or rejected the tag. From verison 1.2.16 onward SVG images are included within the list of permitted media types, and JCOGS Image provides for SVG images a limited (but useful) subset of JCOGS Image's manipulation options:

  • Image sizing
    The desired width / height of processed SVG images can be set using all of the options available to regular images - set dimensions based on minimum or maximum values absolute values or through use of aspect ratios.
  • SVG santitizing
    As noted above SVG images can be created that are the carriers of malicous content. JCOGS Image will automatically scan SVG images it reads for XSS type security issues and remove them: the sanitisation process used is a version of the highly regarded DOMPurify tool used in HTML environments.
  • Image caching
    All of the standard options associated with the JCOGS Image cache are available to processed SVG files - in particular this provides a mechanism for remote image files to be cached on the server along with local image files.

The aim of this level of support is to remove the first obstacle to integrating SVG images more fully into your web design workflow. It is recognised that this is a small (but useful and important) step, but hopefully the first of a series of improvements that will ultimately lead to SVG images having access to most or all of the facilities provided by JCOGS Image.

Unfortunately one facility that is not available currently for SVG images is converting them to other image formats. 

The reasons for this cautious approach are primarily due to the nature of the SVG file format itself, and are largely outside the scope of JCOGS Image itself to fix; however in so far as it is possible to resolve them, JCOGS Design is committed to finding the solutions required.

What are SVG files?

Scaleable Vector Graphics (SVG) is an XML based document format that allows the combination of a 2D vector graphics mark-up language with a simple page description language. SVG files need to be rendered by appropriate rendering systems for them to become visible as pictures. It has been in active development since 1999, but one that only recently has become a format that is widely used. 

Although in some respects SVG represents an extraordinarily powerful approach to image definition, currently most practical uses of the standard appears to be define scalable vector images in a compact and portable format.

The core elements of the format were defined in a W3C standard in 2003 as SVG 1.1 - the current active version; SVG 2 has been in discussion since 2016 but as yet remains a draft proposal.

SVG image files do not directly contain an image - rather they contains instructions from which a rendered image can be constructed. These instructions can range from turtle-graphic style instructions for drawing vector based shapes to the expansion of base64 encoded images (which can be of any image format supported by the rendering browser) to the rendering of images obtained dynamically from remote web locations. In addition, the XML can contain information about transformations to apply to the rendered image - including rotations, applications of filters, dimension changes etc. Further, an SVG file can contain embedded CSS and Javascript instructions, and SIML animation instructions, offering scope for ‘dynamic’ image capabilities. 

The very broad scope of elements that can be included in SVG files opens up a serious risk of malicious use that has lead to some calls for SVG files to be exclueded from (for example) email attachments, in particular SVG files can be vectors for XSS type malware.

Can I use them?

Widespread browser support for rendering some types of SVG images was largely in place by 2013, however SVG is a complicated standard and even by 2022 full support for all features is still not available. The key iOS platform gained the ability to render svg format images within <img> tags only in 2015. 

Support for generating SVG images in popular graphics applications such as Adobe Illustrator is good, but again none currently support the full SVG 1.1 standard.

Implications for JCOGS Image

JCOGS Image is a tool for generating manipulated images for display within web pages and the focus of interest for the add-on is on helping its users work with any image format that can be deployed within a web page. Providing support for SVG has been a priority since the outset.

Unfortunately the complicated SVG 1.1 standard presents some challenges for JCOGS Image (and other applications of a similar nature):

  • The ‘image’ generated by an SVG needs to be rendered before it can be manipulated. 
    To (for example) change the image format of an SVG to (say) webp, JCOGS Image needs to be able to generate a rendering of the image defined by the instructions in the SVG file. For users, this rendering is done by the browser, but rendered image may be affected by attributes of the local environment (for example the local dimensions of the image holder within browser), the platform it is being rendered on, and the local availability of some resources (such as True Type fonts).
  • Competent SVG rendering engines that can be deployed within php are not yet available
    Although work to develop SVG rendering and manipulation libraries that can be deployed within php is in progress, there has been limited success and currently native php mechanisms to manipulate SVGs are not available. In the interim php applications have addressed the the SVG rendering issue (where it is done at all) through the use use of external execution units; these external units are effectively limited function web browsers. In practical terms the approach adopted is to send the SVG definition to a remote process which effectively loads the XML in a browser, captures the rendered image generated and returns a acopy of this to the php process. Such rendering solutions are difficult to support, not particularly efficient or scalable, and incomplete (for example they do not flexibly address the environment / platform issue noted above).
  • For SVG images, some transformation operations may be better delivered through editing the SVG format directly
    Image resizing, cropping, and most other transformations can be delivered for SVG images  through modifications of the XML specifying the ‘image’, likewise steps like adding borders, reflections, and overlay images and text can be achieved by applying SVG primitives to the XML file.

The consequence of these challenges is that full support of the SVG image formats by JCOGS Image remains a future goal. Until then JCOGS Image offers only limited support for the SVG image format.

Future developments

Work is underway to expand the range of maniuplation options available to include cropping, rotation and flipping: as php support for SVG grows the range of options that will work with SVGs will grow further.

Pass-through attributes and attribute consolidation

JCOGS Image provides powerful options for ‘passing through’ HTML parameters to the finished HTML <img> tag (or other tags if you are using the tag-pair approach to build advanced HTML tags).

Any parameters included within a JCOGS Image tag that are not valid JCOGS Image parameters are collected up and added to the tag output - either as attributes included within a created <img> tag, or as the content of the {attributes} variable.  This allows you to simply add any additional parameters you would like to include in the output <img> tag to those included to control the image processing.

For example:


will produce a tag of this form:

<img src="..." class="cats" data-item="kibble">

You can also include additional parameters to pass through to the output / attributes variable by: 

  • adding an attributes="" parameter to your tag - whatever is enclosed in this parameter is appended to the attributes variable output and / or included in the generated <img> tag
  • enclosing attributes entries between a pair of JCOGS Image tags when you have also set create_tag="yes"

Including Image Variables in attributes parameter entries

By default (from Image version 1.3.9 onwards, when this feature was introduced) if you include one or more Image Variables within your attributes entry these variables will be evaluated before the resulting tag is drawn to your web page. This feature allows you to include image specific information (such as filesize) within custom attributes in your generated tag. So for example this simple tag:

{exp:jcogs_img:image src="{images}" attributes="data-filesize='{filesize_bytes}'"}

 will produce an HTML tag similar to this 

<img src="..." data-filesize="40135">

This feature can be disabled via the Enable expansion of Image Variables within attribute parameter text setting which can be found in Image's Advanced Settings panel.

Special handling for Class and Style attributes

Because you can specify additional attributes in several places it is possible for JCOGS image to find multiple examples of attributes defined within your tag inputs.  For class and style attributes (only) JCOGS Image will collect and consolidate the content from multiple attributes and deliver just one class and one style tag that contains all of the applicable content - it will also attempt to remove duplicate style or class entries if there are any.

Sometimes it is not helpful for this class and style consolidation to happen - for example where for some reason you have enclosed multiple HTML elements within a JCOGS Image tag-pair, each with its own class or style attributes. This consolidation function can be disabled on a tag by tag basis by adding the consolidate_class_style="no" parameter to a tag, or by disabling the Class / style attribute consolidation for tag-pair operation default setting - which can be found in the Advanced Settings panel.

Lazy Loading

Lazy loading is a technique to speed up the loading of image intensive pages: in its simplest form lazy loading prevents the downloading images that are outside the part of the screen currently being viewed by the user.

The simple implementation can lead to multiple issues that present to the user through a degraded experience both visually (for example layout ‘jank’) and functionally (causing problems for users of assistive technologies). 

The best approaches to lazy-loading (and web design in general) adopted the design philosophy of progressive enhancement.  Lazy loading is something that can only happen within browsers that support local processing - i.e. browsers that have javascript support and javascript processing enabled. Even though very few users of a site arrive without javascript support (probably less than 1%) the lazy loading solution is better if it fails gracefully for such users.

JCOGS Image's approach to lazy loading supports progressive enhancement, is efficient, fast and offers strong compatibility with current browsers.

Use of JCOGS Image Lazy loading is triggered by adding the lazy= parameter to a tag, or by enabling it as a system default in the JCOGS Image add-on control panel area.

Starting with a plain tag <img src="my_image.jpg">, the JCOGS Image lazy loading feature does the following:

  1. it adds the HTML5 loading="lazy" parameter to <img> tags it creates. This encourages the browser to defers loading the image files defined in the <img> src= and srcset= parameters until they come close to the browser viewport, this works only in browsers that implement HTML5 and have javascript turned on, it is ignored in browsers where this option is not supported;
    <img src="my_image.jpg"loading="lazy">
  2. it replaces the processed image within the <img> tag with a placeholder image created from the processed image; the placeholder images have the same dimensions as the processed image but are either a low-resolution version of that image, or a plain colour field that is keyed to the ‘dominant colour’ of the processed image, and so the placeholder images are represented by much smaller image files than the processed image, and so even if the HTML5 loading='lazy' parameter is ignored the amount of image data downloaded by the browser on initial load is reduced;
    <img src="lqip_my_image.jpg"data-ji-src="my_image.jpg">
  3. it adds an additional ‘fallback’ <img> definition to the page for each image processed that is only visible if javascript is not present or enabled - on the basis that if a browser does not support javascript it might not support advanced image formats, if the save_type for the current image is not jpg a jpg version of the processed image is created so it can be linked to by this noscript image tag;
    <img src="lqip_my_image.jpg" data-ji-src="my_image.jpg"><noscript class="ji__progenhlazyns"><img src="my_image.jpg"  ></noscript>
  4. it adds a CSS rule to the page that hides the <img> tags that have lazy loading changes if javascript is not present;
    <img src="lqip_my_image.jpg" data-ji-src="my_image.jpg"><noscript class="ji__progenhlazyns"><img src="my_image.jpg"  ></noscript>
  5. it adds a small javascript utility to the page which (i.e. if javascript is supported) deletes the ‘no javascript’ images from the page (since if javascript is active they are not needed) and enables a monitor that checks to see if a JCOGS Image lazy loaded image is getting close to the browser viewport. When the image gets close the javascript replaces the src= definition (which is pointing at the placeholder image) with a new version that is pointing at with the full-resolution processed image. This change triggers the browser to download the full-resolution image and display it - so the user mostly only ever sees the full-resolution version.

The method used works and for the most-part is transparent to the user and not dependent upon browser javascript support.

JCOGS Images' lazy-loading system is completely compatible with its responsive image options delivered via the srcset= option.

Usage Notes

Lazy-loading is only applied to <img> tags that are generated by JCOGS Image. 

If you use JCOGS Image to generate output that is not a complete <img> tag (e.g. using a tag-pair configuration to construct an image tag using Image Variables, or including url_only="yes" or output= parameters in a single tag) then the lazy= tag will be ignored.

Image Caching

JCOGS Image uses a powerful image caching system to store copies of processed images on the server. When image caching is enabled and when possible, JCOGS Image will re-use a cached copy of processed image. 

For most users, enabling JCOGS Image caching will significantly improve the speed of response for your site.

JCOGS Image has a number of high-performance features:

  • fine-grained control over caching - set caching strategies on a per-image basis
  • support for variable cache-durations - set cache lives on a per-image or system wide basis
  • reliable - a tight managed association between source image, processing options and cached copy ensures that you always get the right image back from the cache
  • unified cache - all images are normally stored in a single folder which means that regardless of how many templates a processed appears within the same cached copy will be used each tim - saving on storage and processing time
  • auto-cache maintenance features - JCOGS Image provides tools to automatically remove redundant images from the cache

JCOGS Image uses a carefully constructed modified filename for processed images that includes the original file name, and additional elements that help it track the image processing options chosen when the image was created and also the caching lifetime chosen for the image.

Usage Notes

Use with other caching systems

JCOGS Image's caching system only updates images in its cache when EE processes a template that contains JCOGS Image tags and if finds that the cache does not contain a copy of the processed image, or if the cache-life of a copy of the processed image requested has expired. When you are using either quasi static caching (e.g. EE's Template Caching) or fully static caching when a page in that caching system is requested EE may not notify JCOGS Image that the image has been requested, and so even if the images in JCOGS Image's cache have expired they will not be deleted / recreated until the next time EE re-processes the relevant templates. Under such circumstances the cache duration settings used for an image will not always have the effect expected, and enabling the JCOGS Image cache auto-management feature may produce unhelpful results.

Nesting Tags

Most operations that you might want to carry out on an image source can be completed by adding parameters to a single JCOGS Image tag: in particular Filters are applied sequentially in the order you add them to the filter parameter. Yet sometimes it is useful to apply an transformation to an already transformed image. 

To support this needs JCOGS Image supports the ‘nesting’ of tags - putting one JCOGS Image tag ‘within’ another, and using the output of the ‘inner' tag as the source image for the operations of the outer tag.

Here is a pair of tags being applied to a single image source - the output of the exp:jcogs_img:single tag is being used as the source for the exp:jcogs_img:image tag: 


The effect of these two ‘nested’ tags is to add two borders to the original image, and to resize the source image so that it is (before the borders are added) 300px wide.

Example of image tag nesting.

In addition to this kind of nesting, JCOGS Image also supports the inclusion of Image tags within JCOGS Image Pair tags.

For more complex / deep nesting you should use a tag suffix to differentiate nested levels of JCOGS Image tags - this approach would theoretically allow you to nest images as many times as you would like, but it is important to note that such deep nesting is not recommended for performance reasons.

Variable Prefixing

Using a tag suffix with a Pair tag also enables the use of automatic variable prefixing. Operation is simple - if you append a suffix to your JCOGS Image tag, variables produced by the tag are accessed by putting the same prefix followed by a colon character before the variable name. For example if we recode the example above using this approach we get something like:

    <img src="{inner:made}" width="{inner:width}" height="{inner:height}">

If you plan to ‘nest’ JCOGS Image tags within your templates there are a few of things to remember:

Parse="inward" if you want enclosed tags to be processed first

EE's template parser normally does a good job of working out the correct sequence to work through the tags within a template, but when the tags are calls to the same add-on/method sometimes this does not work so well. For JCOGS Image, if you want to ensure that an “inner” tag is processed first, it helps to put the EE parameter parse='inward' into the parameter list for the ‘outer’ tag to ensure that processing of the ‘inner’ tag is completed before the processing of the outer tag begins.


Use different method names and / or tag-pairs and/or add a variable suffix to sidestep EE parsing issues

Sometimes the EE template parser can get confused when you have more than one tag that can exist in both single-tag and tag-pair modes.  Consider this example:

{exp:jcogs_img:image src=...}
... some template code ...
{exp:jcogs_img:image src=...}
... some JCOGS Image variables and other content ... 

EE's template parser will get confused about which opening tag the {/exp:jcogs_img:image} closing tag refers to - probably choosing the first tag as the opening one - which will lead to unexpected / unwanted results.  There are two ways to avoid this:

Always use closing tags - this option avoids the confusion, but keep in mind (for CE Image compatbility) tag-pairs intepret some parameters in a different way to single tag (for example the create_tag parameter)

{exp:jcogs_img:image src=...}
... some template code ...
{exp:jcogs_img:image src=...}
... some JCOGS Image variables and other content ... 

Use different JCOGS Image names to avoid the confusion - If you use a different method name for single tags to tag-pairs you can also avoid this parsing confusion. JCOGS Image gives you the choice of three alternative names - image, single, and pair.

{exp:jcogs_img:single src=...}
... some template code ...
{exp:jcogs_img:image src=...}
... some JCOGS Image variables and other content ... 

Usage Notes

Note: if you use the tag-pair form, remember that for this tag to generate any output you either need to specify some template variables between the tag pair, or add the parameter create_tag='yes' to the parameters for the outer tag.

Specifying Colours

Several of the parameters used by JCOGS Image require the specification of colours.

JCOGS Image supports use of both hex-code and CSS type rgb() and rgba() colour specification models.

Hex-code format

Originally based on use of a hexadecimal triplet with each pair of digits relating to one of the R, G and B components of the web standard  RGB colour model, the hex-code format has over time expanded to represent colours using three, four, six or eight digit hexadecimal numbers.

JCOGS Image will accept any valid version of the hex-code format in any colour parameter - adding a leading # if one is omitted:

  • Three-digit and four-digit hex codes are converted to six-digit and eight-digit hex codes before processing by duplicating each value - so #rgb → #rrggbb, and #rgba → #rrggbbaa.
  • Eight digit hex codes are converted into six digit hex codes by removing the last two digits, which in turn are converted into an opacity value for the colour being specified.
  • Six digit hex codes are converted into the RGB colour model by expanding the hex value pairs into equivalent integers in range 0-255 to give three integer values (one for R, one for G, one for B).

CSS rgb() and rgba() format

JCOGS Image will accept colours specified in either the rgb() or rgba() formats used within CSS system.

Mix and match…

You can use any combination of valid colour codes to specify colours, JCOGS Image validates any colour specified by attempting to convert it into an rgba() type value, which is then used internally for all operations.

Animated GIF Support

Passthrough Support for Animated GIF Images

JCOGS Image version 1.3 introduced a new feature called Animated GIF Passthrough Support.

The aim of this feature is to allow animated GIF images to be functionally included within image workflows. 

When Image detects that a source image is an animated GIF, and when the output format selected for the image is also GIF (either by default, or because of a save_type= parameter setting) Image will ignore all Image parameters in the relevant tag except Image Sizing instructions, and will generate a processed image that is also an animated GIF that will be included in JCOGS Image's unified caching system.

The aim of this level of support is to remove the first obstacle to integrating Animated GIF images more fully into your web design workflow. It is recognised that this is a small (but useful and important) step.

Extending Animated GIF Support - adding the ability to force the behaviour even when save_type is specified

Since Passthrough support was introduced some users have noted that under some circumstances animated GIF images are still being collapsed to still images. This was found to be occurring when a site-wide default image format had been set (e.g. to webp) - this setting was overriding the Animated GIF passthrough support. To address this, in Image version 1.3.8 a new Image setting was introduced (the catchily titled “Enable dominance for preserving animated gif image formats”) that when set tells Image to ignore save_type= parameter values when it is working with Animated GIF images.

Understanding the JCOGS Image file-naming approach

Many questions are asked about how JCOGS Image names its processed images. These notes explain a bit more about what is behind the approach used.

The Image file name has three components - all are important

Image names a processed image with a file name comprising three elements - the original file name followed by two hashes: one relating to the ‘cache duration’ assigned to the image and a second that relates to what transformations were done to the original image in order to generate it. Image does this so that when it pulls an image from the cache it can be sure that it pulls the correct one. 

What is wrong with just using the original file name?

There are multiple site operation issues that arise from the “same as the original” naming strategy: all relate to how to handle the same source image appearing more than once within a site.

  • Within a page
    If different versions of the same image appears multiple times on the same page (e.g. a thumbnail and a hi-res version) and you use the ‘same name’ strategy then you will have a direct clash - the browser will get confused about which version of the image to use where. A common resolution for this is to rename one or other version of the image so both can co-exist on the same page… in which case you are implicitly moving away from the “same name as the original” strategy … in which case you might as well just use JCOGS Image names and be done with the complication!
  • Across multiple pages
    On large / complicate sites the same image may appear in multiple pages even if you only have one copy per page (and in multiple versions across those pages). On such sites the ’same as original’ naming approach becomes one that is almost unusable. You’ll be serving multiple different images all with the same name (which therefore cannot be saved in the same directory). To allow for this a common solution is ‘directory based’ caching - either ‘file tree based' (the one used by CE Image) which saves cached images in a tree structure that replicates the routing pattern used by the web server, or a ‘category based' approach (the one used by EE’s Files system) where you save multiple versions of the image in ’named’ directory folders within the primary cache directory. Both are potentially horrifically inefficient approaches - for example on a site where you have ‘dynamic routing’ (e.g. the second slug in the URI is based on a date, the third based on a user name) the ‘file tree’ based solution will ‘cache’ copies of all images against that specific URI pattern, even though it is improbable that the same URI will ever be called again: those cached images are generated and saved and never used again. Category based caching doesn’t know what versions of an image will be needed by which templates, and so typically (as in case of EE’s files system) preemptively generate all variants for all images ‘just in case’. Both of these variants suffer from issues relating to cache management - it is very difficult to ‘clear’ these caches since you have no easy way of knowing which files within the cache are ‘used’ or not - so mostly people just leave them there always and forever. Which is fine, until you need to update an image … clearly the processed image can be regenerated - but the caching system has no idea if that processed image has already been generated and saved in a different folder … so you end up doing lots of unnecessary image processing.

Is the JCOGS Image caching approach any good?

The three element filenames are required by JCOGS Image's ‘unified cache’ approach - all the images processed by the add-on for a site are stored in a single folder. The filenaming approach used makes it possible for each and every use instance of a specific transformation of a source image across the whole of a site to be served from the same single cached copy. If you have multiple variants of the same image, the naming convention allows you to keep them separate within the same folder. Because Image has the cache-life for an image available from the file name, it is possible for Image to manage the cache - periodically checking and clearing images that have expired. Similarly if Image is requested to generate a specific version of an image, it can easily check thanks to the third segment of the filename if that specific version has been made before and get it back from the cache if so. On large / image intensive sites the caching approach Image uses is both space efficient and highly performant.

Doesn’t the extra filename elements mess with Google Analytics?

No. The file naming approach was developed in the light of extensive consultations with SEO experts and others. These consultations noted three factors that indicate Image's processed file naming strategy will not harm a site's SEO rating:

  1. Because the pattern starts with the original filename, this information is not lost and can be used as a search basis in Google Search. 
  2. Because the additional elements are hashes, so they do not in themselves lead to ‘false positive’ findings (as is case when you, for example, put actual image dimensions into the filename). 
  3. Because most image naming is nonsense (IMG_078932.jpg) search engines have learned to use contextual information rather than file name information as the key determinant of how image information is indexed. So in a very real sense the search engines “don’t care” about filenames.


JCOGS Image provides three hooks that are functionally equivalent to the hooks offered by CE Image. The hooks offered are:

CE Image HookJCOGS Image HookDescription

Called when image processing starts. 

Accepts no data. 

Returns no data.


Called when image processing is complete but before any tagdata from the calling tag-pair is parsed prior to its return to the template. The hook thus allows you to manipulate the image variables before they are returned to the template. 

The following data is passed by the hook when called:
   $tagdata: The un-parsed tagdata.
   $variables: The array of all of the variables that will be parsed before the tagdata is returned to the template.

The $tagdata must be returned to the hook when your local processing of it is completed.

ce_img_savedjcogs_img_savedCalled when an image is saved. The hook returns:
   $this->path_final: The local path on the server to the saved image.
   $type: The image type, which will be one of the following: ‘bmp’, ‘gif’, ‘jpg’, ‘jpeg’, 'png', 'webp'