UsageLast updated: 15 October 2024
JCOGS Image is a powerful image processing utility.
Basic usage
In its simplest use, JCOGS Image creates correctly formed HTML <img> tags within your template; all you need to do is provide the tag with a path to an image source.
The image source can be one of:
- a URL provided by EE Files field variable (or the equivalent from an add-on such as Assets or Channel Images);
- a path to file stored in or below the webroot folder of the server upon which EE is running;
- a URL for a file in a remote location; or
- a copy of the database string entry used to store the file record within the EE database.
The image needs to be in a supported format.
For example, if a file called cats.jpg obtained from a channel with a file field called images
then the JCOGS Image tag:
{exp:jcogs_img:image src="{images}" }
will generate an HTML <img>
tag like this:
<img src="/images/jcogs_img/cache/cats_-_28de80_-_09beb37dfb08841ba81890d5f23afca1042d281b.jpg">
.
Typical usage
The utility of JCOGS Image is unlocked by adding one or more of the many possible parameters and / or filters to the JCOGS Image tag. By adding parameter and filter instructions you can instruct the add-on to modify your image before generating the <img>
tag for you (for example, cropping, rotating, adding a watermark, or recolouring), and / or trigger advanced image features such as automatic lazy loading of your images, auto-sharpening, or the generation of srcset attributes for your <img> tag.
For more complex / advanced situations you can alternatively use a tag-pair and JCOGS Image's template variables to build a customised <img>
or <picture>
tag, or use a bulk processing tag to apply the same image transformations to all the images within a template block - which, for example, is useful for normalising all the images within a Rich Text field.
JCOGS Image creates local copies of the images it generates, and has an advanced caching system that helps you avoid the need to redo the transformation steps each time a template is viewed.
Advanced usage
For advanced developers JCOGS Image also provides a range of tag syntax options to accommodate different / complex template layout conditions, for example allowing you to mix multiple tags within the same template, and to nest tags to allow multiple transformations to be applied sequentially to a single image.
Image / Single Tag
The most common form of template tag used: all the parameters required to identify the source image and the manipulations and transformations required are included within the tag itself.
To avoid any parsing confusion within the EE parse system, JCOGS Image single tags can use either image
or single
as the opening / closing tag element as required.
Syntax
{exp:jcogs_img:single}
{exp:jcogs_img:image}
{exp:jcogs_img:single}
Illustration
{exp:jcogs_img:image width='300px' save_type='webp' aspect_ratio='16_9' crop='y' max='400' class='kittens' add_dims="yes" flip='v'}
The example tag given above will generate the image shown, via this HTML img tag:
<img src="https://domain.com/images/jcogs_img/cache/local_cache_image_file_name.webp" class="kittens" width="300" height="168">
Note that options chosen for the JCOGS Image tag parameters have resulted in output from the tag which comprises:
- a well formed HTML img tag
- the img tag includes image dimensions
- the img tag includes the attribute class='kittens'
Also, the chosen JCOGS Image parameters have resulted in the image referenced in the img tag being:
- a cached copy of a local image file which in turn is a modified version of the source file
- cropped to give version of the original image shrunk to 300px wide
- with a 16x9 aspect ratio
- an image content which is the source image flipped vertically, and
- saved in the webp format.
JCOGS Image's default 'smart scale' crop means the image height has was reduced to maintian the requested 16x9 aspect ratio (over-riding both the height and max parameters included in the example).

Usage Notes
JCOGS Image tags can use several method names.
{exp:jcogs_img:image}
{exp:jcogs_img:single}
and{exp:jcogs_img:pair}
are each aliases of the same method, and each can be used as either a single tag or as a tag-pair.
This name duplication is provided partly to provide better compatibility with CE Image tag naming converntions, and partly to offer developers ways to circumvent EE tag name parsing clashes.
Pair tag
JCOGS Image can also be accessed via the tag-pair form where a tag has an opening element (similar to the single-tag form described above) and also a closing element. Information can be passed to the add-on both from parameters placed within the opening tag and from the information enclosed between the opening and closing tag elements.
When a closing tag is defined JCOGS Image will process any parameters specified in the opening tag and replace any Image variables specified within the enclosed content with information relevant to the processed image. This approach allows you to create your own customised HTML output, and is particularly useful for creating the image content required by complex HTML image tags such as <figure> and <picture>.
For example:
will generate this HTML output:
And this picture:

Note: the dimensions reported for the processed image are not those specified in the opening tag - this is because of the rotation, and the width / height reported in the img tag are the dimensions required for the bounding box such that the rotated image can be placed on the page without distortion.
As is the case with single tag version of JCOGS Image, tag pairs can use any of image
single
or pair
as the method name in the opening / closing tag element as required.
Syntax
{exp:jcogs_img:pair} ... {/exp:jcogs_img:pair}
{exp:jcogs_img:image} ⦠{/exp:jcogs_img:image}
{exp:jcogs_img:single} ⦠{/exp:jcogs_img:single}
Bulk Tag
Sometimes developers have to design templates to work with blocks of content that may contain one or more images added by content editors: the JCOGS Image bulk tag offers a way to apply some image processing to these images to (for example) ensure that they are optimally sized and in the ideal image format.
The bulk tag uses the tag-pair format, and searchs the template content enclosed by its opening / closing tags for <img>
tags; any tags found are processed by JCOGS Image using the parameters found in the opening bulk tag.
The bulk tag is most often used to apply 'standard' modifications to all the images within a content block (e.g. making all the images the same size / aspect ratio, applying a standard filter to each, converting all to a preferred image format etc.). JCOGS Image's intelligent handling of class, style and pass-through attributes also makes it easy for the developer to add a range of attributes to the <img> tags - for example adding one or more classes or inline styles to each <img>, or adding implementation specific attributes (such as data-* attributes) or the inlining of javascript events (such as onclick=).
Syntax
{exp:jcogs_img:bulk} ... {/exp:jcogs_img:bulk}
Illustration
For example:
will generate HTML output like this:
This in turn will create output that looks like this:

Usage Notes
Note the example illustrates how bulk tag processing has processed and cached locally one local image (the first one in the example) and one image obtained from the web - JCOGS Image works equally well with either kind of image source.
Usage Notes
In general JCOGS Image will ignore any width or height parameters included in the enclosed <img> tags, any other parameters found will be added to the replacement image tag generated by JCOGS Image (i.e. passed through unchanged). Critical exceptions to this are how JCOGS Image handles any class or style parameters found - for these JCOGS Image will aggregate the entries generated by the Bulk tag (from the parameters given to it) and those found in the <img> tag - so the resulting <img> tag has at most one class= and one style= parameter entry.
Palette Tag
CE Image Compatibility: Partial
The palette pair type tag that gives you access to an analysis of the colours that appear in a processed image. It is broadly similar in function to the CE-Image ātop_colorsā parameter.
The palette for the image is determined using a well regarded algorithm called Modified Median Cut Quantization. The maximum number of colours in the palette can be controlled through the palette_size parameter, which must be at least 2.
The tag supports some special variables:
- {dominant_color} - the rgba() colour code for the image's dominant colour
- {colors}ā¦{/colors} - a variable pair that loops through the palette values identified for the image. The values exposed by this variable pair are:
- {color} returns the rgb() color value of a palette colour
- {rank} returns the ordinal rank of the palette colour (#1 being the dominant colour)
Illustration

Syntax
{exp:jcogs_img:palette src="" palette_size="<int>"} - default: palette_size=8
{exp:jcogs_img:palette src={images} palette_size="6"}
{dominant_color}
{colors}
{rank} - {color}
{/colors}
{/exp:jcogs_img:palette}
Usage Notes
Because the palette tag works on the processed image (i.e. JCOGS Image's output, not the source image) you can include JCOGS Image parameters, including filters, in the tag - these will be evaluated before the palette is obtained.
Size Tag
CE Image Compatibility: Full
The size tag is included for backward compatibility with early installations of CE Image.
The tag is a clone of the Image tag, and takes all the same parameters.
Syntax
{exp:jcogs_img:size}
{exp:jcogs_img:size}
Action Links
JCOGS Image's Action Link system allows you to add images processed by JCOGS Image to any web page whether or not it is part of an ExpressionEngine template.
There are a variety of uses for Action Links, but the foremost is as a way to offer a more flexible way of integrating images with ExpressonEngine sites that use template caching. Although there are a variety of approaches used, the aim of template caching is to make it possible to send the content of an ExpressionEngine web page to a user without having to process the template that is used to generate the content; doing this speeds up retrieval of the information. When a template is cached usually the links to images within the template are saved as āhard codedā urls - when the cached template is sent to a browser there is no opportunity to check that these images are available (or indeed, modify them to suit changing circumstances).
If you get JCOGS Image to save the link to the processed image as an Action Link, it is the Action Link that is āhard codedā into the cached content - and when the cached template is then sent to the browser, it is the Action Link that it tries to open. The Action Link triggers JCOGS Image which checks to see if the requested processed image is in the cache, the cached image is returned; if the image is missing, the Action Link contains enough information to allow JCOGS Image to regenerate the required image (and save it to the cache so future attempts to retrieve the same automatic action link image will be cache-fast).
Using JCOGS Image automatic Action Links in this way makes it possible for you to worry less about ensuring that your image cache and template cache are both āin syncā - when you are using automatic Action LInks, clearing the image cache does not also require you to also clear all / any templates that have been cached. But there are also other uses for Action Links - particularly the āmanualā version.
Generating an 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. This feature allows you to add images processed by JCOGS Image to any web page whether or not it is part of an ExpressionEngine template. To do this you need to find the correct action link code for your server, and then append the JCOGS Image parameters that define the image you want to generate to the URL as āGETā variables.
For example, imagine you have a JCOGS Image tag in your template that looks like this:
{exp:jcogs_img:image src="/images/of/cats/small.webp" width="350px" aspect_ratio="1_1" crop="yes"}.
If the action link URL for a server is https://domain.com/?ACT=44 then you could replicate the output of this tag using the following URL:
https://domain.com/?ACT=44&src=/images/of/cats/small.webp&width=350px&aspect_ratio=1_1&crop=yes
When this URL is evaluated (e.g. by pasting into a browser url bar) it contacts JCOGS Image on your server which then looks to see the processed image for this set of parameters is already in the cache, and if not it processes the options just like it would in a template, and then either way returns the processed image. If action links like this are placed in the src attribute of HTML <img> tags, the image returned is treated as the tag āsourceā and will appear within your HTML template just like any other image referenced by a regular URL.
Automatic Action Links
JCOGS Image can also generate Action Link URLs automatically (the Action Link appears in place of the URL to the processed image that is normally appears in JCOGS Image tag output). You can activate automatic Action Link generation either by setting a default option on the JCOGS Image System Settings panel or by by adding the parameter action_link='yes' to a JCOGS Image tag.
When you enable automatic Action Links, a specially formatted Action Link will be generated that can be used as in the src= attribute of an HTML <img> tag; when this special Action Link is evaluated by an HTML tag it makes a call to your ExpressionEngine server looking for the processed image created by JCOGS Image when the action link was generated.
- If the processed image is found in the image cache, ExpressionEngine returns it immediately and the image is displayed in your page.
- If the processed image is not found in the image cache, JCOGS Image will regenerate the image (and save it in the cache for next time) and return the image. JCOGS Image can do this regeneration without having to make any calls to the wider ExpressionEngine environment (as all the information JCOGS Image needs to reprocess the image is stored in the automatic Action Link) which makes regeneration speedy.
Usage Notes
Note: For system security reasons, manual action links are limited to using source images that are stored on the hosting ExpressionEngine system; images retrieved from remote servers / locations are not supported.
Usage Notes
Note: An automatic Action Link can use both remote and local image sources - just like the JCOGS Image tag that generated it.
Usage Notes
Note: Image retrieval using direct URL links will be slightly faster than using Action Links; so it is best to only turn on this system when you know you need it.
CE Image compatibility
JCOGS Image has strong compatibility with the stalwart CE Image add-on, offering developers a simpler upgrade path to EE5, EE6 and EE7 for sites developed using the CE-Img add-on.
Drop-in compatibility
Although JCOGS Image is based on a completely new image processing code base, it is possible to upgrade an existing site to JCOGS Image without loss of function simply doing a search / replace on the CE Image tag name - so for example {exp:ce_img:single...}
would change to {exp:jcogs_img:single...}
. In most cases the templates will generate output similar to that produced with CE Image.
Note: Some CE Image functions are not replicated (e.g. ASCIIart) and for some advanced uses (e.g. filters) there are some differences in how some settings work. Sections later in this document for more complete compatibility information.
CE Image Parameter Compatibility Table
Parameter | CE Image Compatibility | Notes |
---|---|---|
add_dimensions | New feature | |
add_dims | Full | |
allow_scale_larger | Full | |
ascii_art | Not implemented | Unlikely to be replicated. |
aspect_ratio | New feature | |
attributes | Full | |
auto_cache | N/A | File caching is handled differently by JCOGS Image - see separate notes |
auto_sharpen | New feature | |
aws_auto_url | Not implemented | Could be implemented in a future version if demand for this exists |
bg_color | Full | |
bg_color_default | Not implemented | Currently available via Control Panel option. Could be replicated as a parameter if demand for this exists. |
border | Full | Added in version 1.1 |
bucket | Not implemented | File caching is handled differently by JCOGS Image - see separate notes |
cache | New feature | This parameter allows the cache setting for an image to be set at the tag level. |
cache_dir | Full | |
consolidate_class_style | New feature | |
create_tag | Full | |
crop | Full | JCOGS Image's implementation of crop includes additional features not present in the CE Image crop parameter. |
debug | Not implemented | Deprecated in CE Image. Comprehensive debugging information available via Control Panel option. |
default_img_width | New feature | |
disable_browser_checks | New feature | |
disable_xss_check | Not implemented | XSS checks on paths provided are not optional. |
encode_urls | N/A | JCOGS Image uses a different approach to file names and so this is not needed |
exclude_class | New feature | |
exclude_regex | Full | CE Image's version of this tag only searches within the src= attribute of the |
exclude_style | New feature | |
face_crop_margin | New feature | |
face_detect_sensitivity | New feature | |
fallback_src | Full | |
filename | Full | |
filename_prefix | Full | |
filename_suffix | Full | |
filter | Full | Not all the filter options available in CE Image are currently implemented, see separate notes on this in the Filters section of this document. |
fit | New feature | |
flip | Full | |
force_remote | N/A | This behaviour is handled automatically, there is no equivalent operation |
hash_filename | Full | |
height | Full | |
hide_relative_path | N/A | JCOGS Image uses a different approach to file names and paths and so this is not needed |
image_path_prefix | New feature | |
interlace | Full | |
lazy | New feature | Implements automatic lazy-loading for |
manipulate | Not implemented | Could be replicated if demand for this exists |
max | Full | |
max_height | Full | |
max_width | Full | |
min | Full | |
min_height | Full | |
min_width | Full | |
output | Full | |
overwrite_cache | Full | |
palette_size | Partial | Related tag is broadly similar in function to the CE-Image ātop_colorsā parameter. |
png_quality | New feature | |
preload | New feature | Implements automatic image preloading for |
quality | Full | |
reflection | Full | |
remote_cache_time | N/A | File caching is handled differently by JCOGS Image - see separate notes |
remote_dir | N/A | File caching is handled differently by JCOGS Image - see separate notes |
rotate | Full | |
rounded_corners | Partial | Added in version 1.3. Separately specified colour backgrounds for each corner for non-transparent image formats not supported. |
save_type | Full | |
sizes | New feature | |
src | Full | |
srcset | New feature | Automatically add responsive variants of the processed image to an <img> tag via the srcset= and sizes= parameters |
svg_passthrough | New feature | |
text | Full | Added in version 1.1 |
top_colors | Partial | A broadly similar output is provided by JCOGS Image's palette method. |
unique | N/A | File caching is handled differently by JCOGS Image - see separate notes |
url_only | Full | |
use_image_path_prefix | New feature | |
watermark | Full | Added in version 1.1 |
width | Full |
CE Image Filter Compatibility Table
Filter | CE Image Compatibility | Notes |
---|---|---|
auto_sharpen | Full | |
blur | New feature | |
brightness | Full | |
colorize | Full | |
contrast | Full | |
dominant_color | New feature | |
dot | Full | |
edgedetect | Full | |
emboss | Full | |
face_detect | New feature | |
gaussian_blur | Partial | |
grayscale | Full | |
greyscale | New feature | |
invert | New feature | |
lqip | New feature | |
mask | New feature | |
mean_removal | Full | |
negate | Full | |
noise | Full | |
opacity | Full | |
pixelate | Full | |
replace_colors | Partial | The filter is broadly equivalent in function to the replace_colors filter found in CE Image, but has slightly different parameters intended to simplify operations. |
scatter | Full | |
selective_blur | Full | |
sepia | Full | The 'slow' version of the sepia filter is fully equivalent to the filter provided with CE Image, but takes about 5x longer to process an image than the 'fast' version (the default). |
sharpen | Full | |
smooth | Full | |
sobel_edgify | Partial | Due to differences in the algorithm used to calculate the filtered image only the threshold sub-parameter is replicated: other sub-parameters will be ignored. |
CE Image Variable Compatibility Table
Variable | CE Image Compatibility | Notes |
---|---|---|
aspect_ratio | New feature | Added in version 1.1 |
aspect_ratio_orig | New feature | Added in version 1.1 |
attributes | Full | |
average_color | Full | Added in version 1.3 |
base_64_orig | Full | |
base64 | Full | |
dominant_color | New feature | Added in version 1.2 |
extension | Full | |
extension_orig | Full | |
filesize | Full | |
filesize_bytes | Full | |
filesize_bytes_orig | Full | |
filesize_orig | Full | |
height | Full | |
height_orig | Full | |
img_credit | New feature | Added in version 1.3 |
img_description | New feature | Added in version 1.3 |
img_location | New feature | Added in version 1.3 |
img_title | New feature | Added in version 1.3.10 |
lazy_image | New feature | Added in version 1.3 |
lqip | New feature | Added in version 1.2 |
made | Full | |
made_url | Full | |
made_with_prefix | New feature | |
mime_type | New feature | |
name | Full | |
name_orig | Full | |
orig | Full | |
orig_url | Full | |
path | Full | |
path_orig | Full | |
preload | New feature | Added in version 1.4.7 |
sizes_param | New feature | Added in version 1.3 |
srcset_param | New feature | Added in version 1.3 |
type | Full | |
type_orig | Full | |
width | Full | |
width_orig | Full |