`

Introduction Last updated: 3 November 2021

JCOGS Image is a simple to use tag based image processing add-on for ExpressionEngine 5 and 6. It is fast, efficient and provides a range of image manipulation options that go beyond those available within EE's built in image processing services.

Features

Broadly the image manipulation features offered by JCOGS Image fall into three categories:

  • Conversion
    JCOGS Image can perform on-the-fly conversion of image formats (e.g. jpg to png). Currently it supports png, jpg, gif, bmp and webp image formats.
  • Resizing
    JCOGS Image can crop and resize images and includes the ability to preserve an image's aspect ratio or distort it as required. Image cropping can use nominated aspect ratios, and can be combined with rescaling.
  • Manipulations
    JCOGS Image can apply a range of image effects to an image, including reflection around horizontal or vertical axis, rotation, and the application of a range of image filters (e.g. greyscale, blur etc). Filters can be combined sequentially, and can be applied to converted / resized images.

In addition JCOGS Image offers several other features that will be of particular value to EE developers:

  • Batch Processing
    JCOGS Image can be applied to single image instances or collections of images (to which the same modifications are applied).
  • CE Image compatibility
    JCOGS Image has strong compatibility with the CE Image add-on, offering developers a simpler upgrade path to EE5 and EE6 for sites developed using the CE-Img add-on.
  • “Drop-in” CE Image updates
    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 small differences in how some settings work. Sections later in this document for more complete compatibility information.

Requirements

JCOGS Image has been tested and is supported for use on EE5 and EE6 systems. It requires the server hosting the EE installtion to be running php 7.3 (or better) and some version of the GD2 library.

Installation

Copy the jcogs_img folder to your system/user/addons folder and then install from the ExpressionEngine Control Panel Add-ons page.

Configuration

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. The Control Panel settings area is used to set key default values.

The options provided through the control panel are as follows:

  • Enable JCOGS Image
    When this is disabled processing of JCOGS Image tags within your templates will be disabled - the tags will be read and removed from your templates, but produce no output.
  • Default Cache Directory
    JCOGS Image stores local cached copies of the images it processes. Use this input to set the location for these cache files: if the path does not already exist JCOGS Image will attempt to create the directory; if the directory cannot be created tag processing will fail. This default setting can be over-ruled on a tag by tag basis through the use of the cache_dir= parameter.
  • Default image duration for cached images (in seconds)
    Sets the default time that JCOGS Image will continue to use a cached copy of a processed image. A setting of -1 will provide a ‘perptual’ cache - cached images will continue to be used until they are deleted externally. A setting of 0 disables the cache. A setting of a positive integer value will keep images in the cache for the number of seconds specified. This default setting can be over-ruled on a tag by tag basis through the use of the cache= parameter.
  • Default quality for JPG images
    Sets the default quality value used when JCOGS Image saves JPG Format images.  This default setting can be over-ruled on a tag by tag basis through the use of the quality= parameter.
  • 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 Debugging Messages in Template Log
    When enabled this causes JCOGS Image to add informative messages about its activities to the Template Log.

Usage

JCOGS Image is an image processing utility. 

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 provided by EE (e.g. via a Files field), or one obtained from a remote internet location (via a URL). 

For example, for a channel with a file field called images:

{exp:jcogs_img:image src="{images}" }

will render as:

<img src="https://domain.com/media/jcogs_img/test_image_5cb969efbda33df285a33c09735e6594cbf6b5c4.jpg">

The power of JCOGS Image is that you can add a host of parameters to the tag to generate modified images and through use of its template variables you have fine control over what information is returned to EE about the image, either within the tag output (if required) or just within the EE template parsed output.

Through these JCOGS Image parameters and variables you can also create local copies of the transformed images produced by the add-on, improving the performance of your site by removing the need to redo the transformation steps each time a template is viewed.

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.

Usage Notes

Information about these additional options for using JCOGS Image is what makes up the rest of this documentation for this add-on.

Single Tag

The most common form of template tag used. In the JCOGS Image single tag with all the relevant 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 off developers ways to circumvent 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 the template content enclosed by the tag. The information returned by the tag-pair version of JCOGS Image will normally comprise the enclosed content with any JCOGS Image template variables within that content having been evaluated and replaced by the appropriate information about the image being processed. 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:

{exp:jcogs_img:pair 
    src='{images}' 
    width='500px' 
    height='700px' 
    max_height="350px" 
    min="240px" 
    aspect_ratio='16_9' 
    crop='y' 
    save_type='webp' 
    allow_scale_larger='y' 
    class='cats' 
    rotate="35"
    flip='h'}
<figure>
    <img src="{made}" {attributes}="" width="{width}" height="{height}">
    <figcaption>This picture is called {name}.{extension}</figcaption>
</figure>
{/exp:jcogs_img:pair}

will generate this HTML output:

<img src="/media/jcogs_img/50802526853_0c0cdb05d0_c_52eef17e88ec6541ff432ac461a62cb9a1596628.webp" class="cats" width="723" height="888">

 

And this picture:

This picture is called tag_pair_demo.webp

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 inlining of javascript events (such as onclick=). 

Syntax

{exp:jcogs_img:bulk} ... {/exp:jcogs_img:bulk}

Illustration

For example:

{exp:jcogs_img:bulk 
    width='300px' 
    aspect_ratio='16_9' 
    crop='y' 
    save_type='webp' 
    allow_scale_larger='y' 
    class='cats' 
    flip='h'}
<p>
    Macavity, Macavity, there’s no one like Macavity,
    There never was a Cat of such deceitfulness and suavity.
</p>
<img src="{images}" width="700px">
<p>
    He always has an alibi, and one or two to spare:
    At whatever time the deed took place—MACAVITY WASN’T THERE!
</p>
    <img src="https://placekitten.com/400/600">
{/exp:jcogs_img:bulk}

will generate HTML output like this:

<p>
    Macavity, Macavity, there’s no one like Macavity,
    There never was a Cat of such deceitfulness and suavity.
</p>
<img src="/media/jcogs_img/50802526853_0c0cdb05d0_c_42139d0677052065d989980f2e73fd284d253c87.webp" class="cats">
<p>
    He always has an alibi, and one or two to spare:
    At whatever time the deed took place—MACAVITY WASN’T THERE!
</p>
<img src="/media/jcogs_img/600_42139d0677052065d989980f2e73fd284d253c87.webp" class="cats">

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.

CE Image compatibility

JCOGS Image has strong compatibility with the stalwart CE Image add-on, offering developers a simpler upgrade path to EE5 and EE6 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
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
cache_dir Full
cache_mode New feature
create_tag Full
crop Full
debug Not implemented Deprecated in CE Image. Comprehensive debugging information available via Control Panel option.
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
fallback_src Full
filename N/A JCOGS Image uses a different approach to file names and so this is not needed
filename_prefix N/A JCOGS Image uses a different approach to file names and so this is not needed
filename_suffix N/A JCOGS Image uses a different approach to file names and so this is not needed
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.
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
interlace Full
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
quality Full
reflection Not implemented Unlikely to be replicated.
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 Not implemented Unlikely to be replicated.
save_type Full
src Full
text Not implemented Coming in a later version
top_colors Not implemented Unlikely to be replicated.
unique N/A File caching is handled differently by JCOGS Image - see separate notes
url_only Full
watermark Not implemented Coming in a later version
width Full

Parameters Last updated: 5 November 2021

The parameters and variable definitions for all three tag types are the same.

Some parameters and variables are marked with CE in first column. These parameters are named identically and have equivalent function to CE-Image parameters of the same name; implementation differences are noted in comments next to each.

add_dims

CE Compatibility: Full

Determines whether  HTML img dimension parameters width= and height= will be included within <img> tag.  The parameter is ignored where the tag does not output an <img> tag.

Syntax + Examples

add_dims="yes|no" - default value: yes for single tags, no for tag-pairs.

add_dims="yes"

Illustration

{exp:jcogs_img:image add_dims="yes" width="300"}

This single JCOGS Image tag will produce an HTML img tag containing width= and height= parameters.

Usage Notes

If you also choose options that will cause the JCOGS Image to generate an HTML <img> tag, this parameter will determine whether the HTML img dimension parameters (width= and height=) will be included in the tag.

add_dimensions

CE Compatibility: New feature

An alias for the add_dims parameter. See the definition of add_dims for parameters.

Usage Notes

If both add_dims and add_dimensions parameters are specified in the same tag, the value of add_dims will be used.

allow_scale_larger

CE Compatibility: Full

This parameter controls whether JCOGS Image is allowed to increase the size of the image to fit within the dimensions specified for the final image.

Syntax + Examples

allow_scale_larger="yes|no" - default value: no

allow_scale_larger="yes"

Usage Notes

Only applies to resize operations. Ignored otherwise.

If the parameter is set to no and other operations specified can be completed without enlarging the image then this parameter will have no effect. 

If the parameter is set to no and any of the other operations specified would require the size of the image to be increased for the operation to complete, these operations are not applied.

aspect_ratio

CE Compatibility: New feature

Adds a constraint to some operations to use the specified aspect ratio to constrain the dimensions of the final image. The aspect ratio is defined as the ratio between the horizontal and vertical dimensions.  In the parameter value the first integer value relates to the horizontal dimension, and the second to the vertical dimension. Any two values can be used. If only one value is given, the aspect ratio parameter is ignored.

Most often used with the crop operation, but also can be used when resizing images and the fit parameter is specified.

For cropping operations, aspect ratio is used to calculate the required image height if only width is specified, or the required image width if only height is specified. If neither width nor height are specified, the required height is calculated based on the width of the source image.

For resizing operations where only one dimension is specified (height or width) the aspect ratio is used to impute the other dimension of the ‘bounding box’ for the resized image so that the fit parameter can determine the appropriate height and width for the image after the resize.

Syntax + Examples

aspect_ratio="<integer>[_|px|%]<integer>" - default value: if the value provided is not a valid aspect ratio, the original aspect ratio is maintained.

aspect_ratio="16_9"

aspect_ratio="5/7"

aspect_ratio="4:3"

Illustration

{exp:jcogs_img:image width='300' aspect_ratio='16_9' crop='y'}

In this example the image will be scaled to be 300 px wide, and the height is set according to the aspect ratio specified.

Usage Notes

For cropping operations if both height and width are specified, the parameter is ignored.

attributes

CE Compatibility: Full

Content to be passed through to output unchanged.

If creation of an <img> tag is requested this content is simply placed within the tag along with any calculated values (e.g. width). 

The content is also available via the {attributes} variable which can be used in a single JCOGS Image tag within the output= parameter, or when using a tag-pair.

Syntax + Examples

attributes="<any content>" - default value: null

attributes="class='cats' style='margin:3em' data-toggle='up'"

Illustration

{exp:jcogs_img:image width='300' attributes="class='cats'" class="dogs"}

This example adds the content class='cats dogs' to the HTML <img> tag created by combining the class value specified in the attributes= parameter with the class attribute passed through as an unrecognised parameter.

Usage Notes

It is possible to end up in a situation where you have specified content for the attributes parameter in more than one place - for example by specifying an attributes= parameter in a tag-pair, including unrecognised parameters within the JCOGS Image tag, and / or including additional parameters within the content enclosed by the tag-pair.  

When this happens, JCOGS Image simply combines the content of all the sources found, but also intelligently combines any  class= and style= elements so that only one of each is included in the resulting output.

bg_color

CE Compatibility: Full

Defines the colour of the background behind the image layer during processing. If the image processing (e.g. rotation or the removal of transparency) will cause the background to show, this is the colour that appears.

The colour should be specified using a three or six-digit hex code, which may be with or without a leading # symbol.

Syntax + Examples

bg_color="[#]<3 or six digit hex_colour_code>" - default value: #FFFFFF (White)

bg_color="#373859"

bg_color="343434"

bg_color="#F7F"

border

CE Compatibility: Full

Define a solid color border around an image. 

The border should be specified in pixels using an integer (with or without a px suffix).

The colour should be specified using a three or six-digit hex code, which may be with or without a leading # symbol.

Syntax + Examples

border="<integer>[px|%]|[#]<three or six digit hex colour code>" - default value: 0|#FFFFFF

border="10|4a2d14"

border="10px"

border="10px|#DDD"

Illustration

{exp:jcogs_img:image width='300' border='10|4a2d14'}

In this illustration a border colour #4a2d14 that is 10 pixels wide is added to the image.

Usage Notes

The border is added to the outer edge of the image, so the size of your image will increase by 2x the width of border specified in each dimension.

cache

CE Compatibility: New feature

This parameter allows the cache setting for an image to be set at the tag level.

The parameter takes one value, which indicates the duration that cached image should remain in the cache.  There are three options:

  • cache="-1" The cache is set to ‘perpetual’ mode - an image will be kept in the cache until it is deleted (or overwritten). This option is the default value set when JCOGS Image is first installed.
  • cache="0" The cache is disabled - processed images will not be saved to the cache, and JCOGS Image will not look for cached copies of processed images.
  • cache="<integer>" JCOGS Image will create cache copies of processed images and continue to use them for <integer> seconds after the cached image is created.

If set in a tag, the value will over-rule the default value set in the JCOGS Image Control Panel Settings area (which is set to -1 when JCOGS Image is first installed).

Syntax + Examples

cache="-1|0|<positive integer value>"

cache="-1" - set the cache to perpetual mode for this tag

cache="0" - turn off caching for this tag

cache="604800" - set the cache to 604800 seconds (1 week)

cache_dir

CE Compatibility: Full

Defines the path to the JCOGS Image cache folder relative to the web_root directory.

This value if specified in a tag will over-rule the default location specified in the JCOGS Image control panel settings for that tag only.

Syntax + Examples

cache_dir="<path to folder to use>" - default value: the path specified in JCOGS Image Control Panel Settings area

cache_dir="media/images/cats"

Usage Notes

If the folder specified does not exist, JCOGS Image will try to create it; if that activity fails the tag processing will stop.

The value can be specified with or without a trailing slash.

cache_mode

CE Compatibility: New feature

Determines how JCOGS Image works with cached copies of processed images. There are two options:

  • Fast - JCOGS Image interrogates the cache using just the content of the src= or fallback_src= parameter. If a valid cache hit is found, no further processing of the source image is done, and the cached copy of the processed image is returned by the add-on.
  • Slow - JCOGS Image does some work to validate the source image before looking to see if a copy of the processed image is in the cache.

The default cache mode is Fast and as its name suggests is the fastest option, and for most purposes is a very good solution. However since the source image is not validated before the cache copy is retrieved, some aspects of JCOGS Image output are degraded since information obtained from an analysis of the source image is not available; this lack leads to two potential issues for advanced users:

  • Some JCOGS Image Variable values (specifically: base_64_orig, height_orig, width_orig, filesize_orig, filesize_bytes_orig) which rely upon access to the original image to be created are not available when a cached copy is found;
  • The availability of the remote image sources is not confirmed.

Syntax + Examples

cache_mode="fast|slow" - Default: fast

cache_mode="slow"

Usage Notes

The choice of cache mode does not affect whether or not an image is cached, just when in the image process sequence JCOGS Image looks for the existence of a cached copy of the processed image.

If the cache is disabled (e.g. by setting tag parameters cache="0" or overwrite_cache="yes"), this tag has no effect.

create_tag

CE Compatibility: Full

Controls whether a tag will produce as output an HTML <img> tag.

The default for single tags is for create_tag= to be ‘yes’, the default for tag-pairs is for create_tag= to be ‘no’; this difference reflects the different modes of operation provided by single and pair tags.

Syntax + Examples

create_tag="yes|no" - default value: for single-tags “yes”, for tag-pairs “no”

create_tags="yes"

create_tags="y"

Usage Notes

If create_tag="no" is specified for a single JCOGS Image tag, the image specified will be processed by the tag but no output will be returned to the template.

This option can be useful when debugging a template - as if JCOGS Image debugging is turned on the image processing steps will still generate debugging reports in the template debug log without adding an image to the template output.

crop

CE Compatibility: Full

Controls whether an image will be resized to fit the dimensions given or will be cropped. 

Cropped an image allows for a smaller section of the image to be extracted; you can control the size of the smaller section and also the where on the source picture you want the smaller section to be placed.

JCOGS Image also supports (by default) ‘smart scaling’ of the cropped image - a process by which JCOGS Image will attempt to reduce the size of the source image such that after the crop in one dimension the whole of the original image can be seen, and in the other the source image will be cropped to fit the overall dimensions given.

The crop will be determined by the dimensions given in the tag - either via specifying width and height parameters (or their proxies, such as min-height or max) or specifying one dimension and also specifying an aspect ratio (which will cause JCOGS Image to crop the image using a shape calculated from the dimension given).

The need for this information leads to a quite complex definition - comprising up to six values separated by the | symbol.

  • The first value indicates whether or not to crop the image and takes the values yes or no.  The default value is no.
  • The second value specifies the overall position for the crop shape relative to the source image in the form horizontal location, vertical location - where the horizontal position is one of left|center|right and the vertical position is one of bottom|center|top. The default values are center,center.
  • The third value specifies an adjustment of the position for the crop relative to the overall position, and is defined by two values, the first specifying in pixels how much to move the crop shape horizontally the second how much to move the crop shape vertically. The values can be positive or negative integers. The default values are 0,0.
  • The fourth value specifies whether to use smart scaling. It can take the values yes or no. The default value is yes.

Because of these defaults, specifying crop='yes' in a tag will cause it be cropped relative to the center point of the source image, and for the cropped image to be adjusted via super scaling.

Syntax + Examples

crop="yes|no[|[left|center|right],[bottom|center|top][|<integer>,<integer>[|[yes|no]]]]" - default value: no|center,center|0,0|yes

crop="yes" - equivalent to crop="yes|center,center|0,0|yes"

crop="yes|center,top" - equivalent to crop="yes|center,top|0,0|yes"

crop="yes||0,-20" - equivalent to crop="yes|center,center|0,-20|yes"

crop="yes|right,bottom|20,-20|no" - equivalent to crop="yes|right,bottom|20,-20|no"

Illustration

{exp:jcogs_img:image width='300' height='200' crop='yes'}

Crop an image to be 300 pixels wide and 200 pixles tall.

The resulting image is smart scaled to fit into a shape with dimensions 300px by 200px

Illustration

{exp:jcogs_img:image width='300' crop='yes' aspect_ratio='7:5'}

Crop an image to be 300 pixels wide and with an aspect ratio of 7x5.

The resulting image is smart scaled to fit into a shape with dimensions 300px by 214px

Illustration

{exp:jcogs_img:image width='200' crop='yes|||no' aspect_ratio='5:7'}

Crop an image to be 200 pixels wide with an aspect ratio of 5x7 with smart scaling turned off.

The resulting image will be a sub-section of the center of the image with dimensions 200px x 280px.

Illustration

{exp:jcogs_img:image width='300' crop='yes|left,top|50,50|no' aspect_ratio='16_9'}

Crop an image to be 300 pixels wide with an aspect ratio of 16:9 with smart scaling turned off, and with the crop taken from top left of the source image offset by 50 pixels in the horizontal and vertical directions.

The resulting image will be a sub-section of the top-left of the source image with dimensions 300px by 168px.

fallback_src

CE Compatibility: Full

Allows for the defintion of a fallback image that is used in cases where either the src= parameter is not specified, or is specified but the information provided does not point to a valid image.

This parameter is useful in cases where the developer cannot always be sure that the intended image data will always be available.

The options for what information is used to define the fallback_src= parameter is identical to that for the src= parameter.

Syntax + Examples

fallback_src="<any valid local image path>|<any valid remote image path>" - default value: null

fallback_src="/media/images/default_backdrop.jpg"

fallback_src="https://placekitten.com/400/300"

Illustration

{exp:jcogs_img:image width='300' fallback_src='https://placekitten.com/400/300'}

In this example src= image data is not provided so the image used is the one specified by the fallback_src= parameter.

filter

CE Compatibility: Full

Allows for the specification of one or more filters to be applied to the image during processing.

The syntax for this parameter comprises a series of pipe (|) separated sub-parameter blocks - each sub-parameter block relating to a filter you want to apply.

Filters are applied to the image in the order that they are specified in the filter parameter.

As each filter has its own parameters the definition of the sub-parameters is discussed in more detail in the separate filters section of this document.

Syntax + Examples

filter="<filter parameter definition>[|<filter parameter definition>]

filter='grayscale' 

filter='colorize,-20,20,-20'

filter='colorize,-20,20,-20|blur,5'

Illustration

{exp:jcogs_img:image width='300' filter='colorize,-20,20,-20|blur,5'}

In this example the image has a colorize filter applied followed by a blur filter.

fit

If two image dimensions are given (or implied) in a JCOGS Image and crop is not also specified, this tag determines how the image is scaled relative to the two dimensions.

The parameter can take one of three values: 

  • contain  The image is scaled to fit within the box defined by the two dimensions given (or imputed) while maintaining the image aspect ratio.whether image is scaled to fit completely into dimension (contain), or scaled to ensure image extends to all edges of bounding box without distortion. This is likely to result in a image that is smaller than the area defined by the bounding box. (cover), or is distorted to fit into space defined.
  • cover The image is scaled to completely fill the box on both dimensions. This is likely to result in an image that is larger than teh area defined by the bounding box.
  • distort The image dimensions are preserved and the image is allowed to be distorted to fit into the space defined.

Syntax + Examples

fit="contain|cover|distort" - Default: ‘’

fit="cover"

fit="contain"

fit="distort"

Illustration

{exp:jcogs_img:image width='300' height='300' fit='contain' cache_mode='slow'}

The image is scaled to fit within the 300x300 bounding box specified.

Illustration

{exp:jcogs_img:image width='300' height='300' fit='cover'}

The image is scaled to fill the 300x300 bounding box specified.

Illustration

{exp:jcogs_img:image width='300' height='300' fit='distort'}

The image is distorted to fit within the 300x300 bounding box specified.

Usage Notes

If the parameter is specified with no value (e.g. fit="") on an unrecognised value it is ignored.

If only one dimension is specified the value of this parameter is ignored.

flip

CE Compatibility: Full

Instructs JCOGS Image to flip the image content around either the vertical or horizontal axis (or both).

Syntax + Examples

flip=h|v|h|v - Default value: null

flip='h'

flip='v'

flip='h|v'

Illustration

{exp:jcogs_img:image width='300' flip='v'}

Flip the image about the vertical axis.

hash_filename

CE Compatibility: Full

JCOGS Image names the files it generates as a combination of the original file name and a unique identifier; this hybrid filename ensures reliable cache operations while also providing potentially useful file naming information to Search Engines.

For example, a file with the original name our_office.jpg might be given an output filename of our_office_3a7d48a6f0c27bbf29701f76859a63f0405ca737.jpg

This parameter allows you to obscure the original of the image in the output filename - the original name is replaced by a hash. Possible values are "yes" and "no", with the default being "no".

When enabled, this option would result in an output filename for our example image becoming something like 1d48854ed203acf437ef4a09c1112973fd5c9ad6_3a7d48a6f0c27bbf29701f76859a63f0405ca737.jpg.

Syntax + Examples

hash_filename=[yes|no] - Default: no

hash_filename="yes"

height

CE Compatibility: Full

Sets the height of the image to be produced.  The value can be given as an integer number (of pixels) with or without a trailing px suffix, or as a percentage value (an integer with a trailing %). If a percentage is specified, it is converted into a pixel value by multiplying the percentage value by the original image height.

If the value is not specified, JCOGS Image will try to impute a value for height from other parameters specified.

Syntax + Examples

height="<integer value>[px|%]" - Default value = “”

height="200px"

height="180"

height="33%"

Illustration

{exp:jcogs_img:image height='150px'}

Set the height of the image to 150px.

Since no other information is given, JCOGS Image will scale the image in proportion to its original dimensions to give the height requested.

Usage Notes

Precedence

This parameter will be potentially over-ruled by any explicit settings for  min_height= or max_height= or min= or max= in a tag.

% values

If a % value is specified, JCOGS Image works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

interlace

CE Compatibility: Full

When this parameter is set to ‘yes’ it instructs JCOGS Image to save the processed image as an interlaced (or ‘progressive’) jpg image.

Syntax + Examples

interlace="yes|no" - Default: no

interlace="yes"

interlace="no"

Usage Notes

This parameter is ignored if the save_type= parameter is set to anything other than jpg.

max

CE Compatibility: Full

Sets a maximum value for the width and height of the image after processing. 

The value should be specified either as a positive integer value with no units (px assumed), or as a positive integer value with either px or % as a suffix.

Syntax + Examples

max="<integer>[px|%]" - default value: 0

max="300px"

max="200"

max="30%"

Illustration

{exp:jcogs_img:image max="200" width="400" height="400" max_height="350" crop="yes"}

This tag will produce an image with dimensions 200x350.

The  max= parameter value over-rules the width= parameter value

The  max_height= parameter value over-rules the max= parameter value.

Usage Notes

Precedence

This parameter will over-rule any explicit setting for width= or height= in a tag.

This parameter will be over-ruled by any setting for max_width= or max_height= in a tag.

% values

If a % value is specified, JCOGS Image works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

max_height

CE Compatibility: Full

Sets a maximum value for the height of the image after processing. 

The value should be specified either as a positive integer value with no units (px assumed), or as a positive integer value with either px or % as a suffix.

Syntax + Examples

max_height="<integer value>[px|%] - Default: ‘’

max_height="220"

max_height="200px"

max_height="47%"

Illustration

{exp:jcogs_img:image height="270px" max_height="220"}

Limit the maximum height of the image to 220px.

The height= figure given is over-ruled by this parameter.  Since no other information is specified, the image is rescaled to give a height of 220px and the aspect ratio of the original image is maintained.

Usage Notes

Precedence

This parameter will over-rule any explicit setting for the height= or max= parameters in a tag.

% values

If a % value is specified, JCOGS Image works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

max_width

CE Compatibility: Full

Sets a maximum value for the width of the image after processing. 

The value should be specified either as a positive integer value with no units (px assumed), or as a positive integer value with either px or % as a suffix.

Syntax + Examples

max_width="<integer value>[px|%] - Default: ‘’

max_width="320"

max_width="280px"

max_width="66%"

Illustration

{exp:jcogs_img:image width='300' max_width='280px'}

Limit the maximum width of the image to 280px.

The width= figure given is over-ruled by this parameter.  Since no other information is specified, the image is rescaled to give a width of 280px and the aspect ratio of the original image is maintained.

Usage Notes

Precedence

This parameter will over-rule any explicit setting for the width= or max= parameters in a tag.

% values

If a % value is specified, JCOGS Image works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

min

CE Compatibility: Full

Sets a minimum value for the width and height of the image after processing. 

The value should be specified either as a positive integer value with no units (px assumed), or as a positive integer value with either px or % as a suffix.

Syntax + Examples

min="<integer>[px|%]" - default value: 0

min="300px"

min="200"

min="30%"

Illustration

{exp:jcogs_img:image min="250" width="200" height="200" min_height="230" crop="yes"}

This tag will produce an image with dimensions 250x230.

The  min= parameter value over-rules the width= parameter value

The  min_height= parameter value over-rules the min= parameter value.

Usage Notes

Precedence

This parameter will over-rule any explicit setting for width= or height= in a tag.

This parameter will be over-ruled by any setting for min_width= or min_height= in a tag.

% values

If a % value is specified, JCOGS Image works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

min_height

CE Compatibility: Full

Sets a minimum value for the height of the image after processing. 

The value should be specified either as a positive integer value with no units (px assumed), or as a positive integer value with either px or % as a suffix.

Syntax + Examples

min_height="<integer value>[px|%] - Default: ‘’

min_height="120"

min_height="150px"

min_height="25%"

Illustration

{exp:jcogs_img:image height="220px" min_height="250"}

Limit the minimum height of the image to 250px.

The height= figure given is over-ruled by this parameter.  Since no other information is specified, the image is rescaled to give a height of 250px and the aspect ratio of the original image is maintained.

Usage Notes

Precedence

This parameter will over-rule any explicit setting for the height= or min= parameters in a tag.

% values

If a % value is specified, JCOGS Image works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

min_width

CE Compatibility: Full

Sets a minimum value for the width of the image after processing. 

The value should be specified either as a positive integer value with no units (px assumed), or as a positive integer value with either px or % as a suffix.

Syntax + Examples

min_width="<integer value>[px|%] - Default: ‘’

min_width="120"

min_width="150px"

min_width="25%"

Illustration

{exp:jcogs_img:image width="220px" min_width="250"}

Limit the minimum width of the image to 250px.

The width= figure given is over-ruled by this parameter.  Since no other information is specified, the image is rescaled to give a width of 250px and the aspect ratio of the original image is maintained.

Usage Notes

Precedence

This parameter will over-rule any explicit setting for the width= or min= parameters in a tag.

% values

If a % value is specified, JCOGS Image works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

output

CE Compatibility: Full

Causes the output of a tag to be determined by a string entered into this parameter: any JCOGS Image Variables encountered are replaced by values derived from the source image and the manipulations specified for this tag by other parameters.

Syntax + Examples

output="<string containing text and JCOGS Image variables>" - Default: ‘’

output="The width of the image is {width} pixels, the height is {height} pixels."

output="{base_64}"

output="The name of the image is {name}"

Usage Notes

When this parameter is specified, the value of the create_tag= parameter is ignored. 

overwrite_cache

CE Compatibility: Full

When set to ‘yes’ this parameter causes JCOGS Image to regenerate the image from the source regardless of other cache settings.

Syntax + Examples

overwrite_cache="yes|no" - Default: no

overwrite_cache="no"

Usage Notes

Precedence

If set to yes this parameter over-rules any other cache settings in the tag or set in the JCOGS Image Control Panel Settings area. If set to no, other cache settings will be tested before a decision is made about whether to use a cached copy of an image.

quality

CE Compatibility: Full

When set, this parameter instructs JCOGS Image to save the processed image as with the specified jpg quality level.

Syntax + Examples

quality="<integer value between 0-100>" - Default: 90

quality="70"

Usage Notes

This parameter is ignored if the save_type= parameter is set to anything other than jpg.

rotate

CE Compatibility: Full

This parameter determines the amount of rotation to be applied to an image.

The rotation is specified using a single positive or negative integer value to represent the angle of rotation (in degrees) required. Rotation is measured from the horizontal, moving in an anti-clockwise direction.

As the picture rotates, the size of the containing rectangle enlarges to allow the rotated image to sit on the page without distortion, exposing some parts of this containing rectangle: the background colour of this containing rectangle is defined either by the background colour set for the tag - which can be set either within the tag using the bg_color= parameter - the default background colour set in the JCOGS Image Control Panel Settings area.

Syntax + Examples

rotate="<integer>" - Default: 0

rotate="75"

rotate="-120"

Illustration

{exp:jcogs_img:image width='300' rotate="30" bg_color="4a2d14"}

The image is rotated 30° from the horizontal. The background area exposed by the rotation is coloured #4a2d14.

Note that the size of the output image is larger than the dimensions specified in the tag parameters.

Usage Notes

Precedence

The rotation operation is applied after crop and resize operations, and after image flip operations.

save_type

CE Compatibility: Full

Determines the encoding format to be used by the processed image.

The format options available are determined by the abilities of the php image processing library used: for GD2 (the default library used by JCOGS Image) the available formats are:

extension

image format

bmp

Windows bitmap format

gif

Graphics Interchange Format

jpeg/jpg

JPEG image format

png

Portable Network Graphics format

webp

Webp format

Later versions of JCOGS Image will support other graphics libraries, which if installed may give access to other image formats.

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

Syntax + Examples

save_type="bmp|gif|jpeg|jpg|png|webp" - Default: jpg

save_type="bmp"

save_type="webp"

Usage Notes

Transparency

Not all formats support transparency. Where possible transparency in images is preserved by JCOGS Image during processing, but it is also important to make sure that the processed 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 save_type="png" in your tag.

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

Currently JCOGS Image saves 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. A future update to JCOGS Image will aim to offer both lossy and lossless compression options for these image formats.

src

CE Compatibility: Full

Defines the image that is to be used by the tag.

The image source can be any local file or be one obtained via a URL. 

Remote files are cached locally during processing but only the processed version of the image is cached.

The format options available are determined by the abilities of the php image processing library used: for GD2 (the default library used by JCOGS Image) the available formats are:

extension

image format

bmp

Windows bitmap format

gif

Graphics Interchange Format

jpeg/jpg

JPEG image format

png

Portable Network Graphics format

webp

Webp format

Later versions of JCOGS Image will support other graphics libraries, which if installed may give access to other image formats.

It is not important whether the source image file has an extension, or whether the given extension is correct - JCOGS Image validates each image before processing, a step that includes validating the actual image format being used.

Syntax + Examples

src="<any valid local image path>|<any valid remote image path>" - default value: null

src="/media/images/growling_tiger.jpg"

src="https://placekitten.com/400/300"

Illustration

{exp:jcogs_img:image src='media/a_word_from_our_sponsor.png'}

A tag using a local image source.

Illustration

{exp:jcogs_img:image src='https://placekitten.com/300/225'}

A tag using a remote image source.

Usage Notes

Remote Image Files

If a remote source image file is specified the source file will be downloaded to the local server before processing begins, which adds time to the total processing time for the template holding the JCOGS Image tag.

If a remote image is not obtained within a reasonable period, or if it is found to be unavailable, JCOGS Image will first attempt to use a fallback_src= image. If no fallback image is specified, or if that image too is unavailable, JCOGS Image will terminate processing of the tag.

The default caching setup for JCOGS Image (perpetual cache, “Fast” cache mode) enables the add-on to avoid the need to download or process the remote source image again in subsequent calls to the template: for site performance reasons you are strongly encouraged to retain these settings for remote image files (either by leaving the add-on with default settings, or adding cache= and cache_mode= parameters to your tags with remote image sources).

Enabling caching but setting cache mode to “Slow” will continue to allow the add-on to use valid cached images if it finds them, but adds an extra processing step where by JCOGS Image attempts to validate the source image before it looks to see if there is a cached copy available: this validation is useful under some conditions, but does require the add-on to re-download the remote image so that it can do its validation checks, and so comes with a small performance penalty.

url_only

CE Compatibility: Full

If this parameter is set to yes then the source image will be processed according to the parameters set within the tag and the only output will be a URL pointing to the processed image on the host server.

Syntax + Examples

url_only="yes|no" - Default: no

url_only="yes"

url_only="no"

Usage Notes

This is one of the several ways in which JCOGS Image can be instructed to provide just a URL to the processed image.

width

CE Compatibility: Full

Sets the width of the image to be produced.  The value can be given as an integer number (of pixels) with or without a trailing px suffix, or as a percentage value (an integer with a trailing %). If a percentage is specified, it is converted into a pixel value by multiplying the percentage value by the original image height.

If the value is not specified, JCOGS Image will try to impute a value for width from other parameters specified.

Syntax + Examples

width="<integer value>[px|%]" - Default value = “”

width="200px"

width="180"

width="33%"

Illustration

{exp:jcogs_img:image width='300'}

Set the width of the image to 300px.

Since no other information is given, JCOGS Image will scale the image in proportion to its original dimensions to give the height requested.

Usage Notes

Precedence

This parameter will be potentially over-ruled by any explicit settings for  min_width= or max_width= or min= or max= in a tag.

% values

If a % value is specified, JCOGS Image works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

Variables Last updated: 5 November 2021

JCOGS Image makes a large number of variable elements available for each image that it processes.

Variable elements can be included within an output= parameter, and or included within a JCOGS image tag-pair, and can be used to help construct either custom <img> or <picture> tags, or generate other forms of useful output within your template (such as picture captions).

Currently the only way to generate base64 output is via a JCOGS Image variable.

attributes

CE Compatibility: Full

Contains content of attributes parameter if set, plus any unrecognised parameters in the tag, plus for tag-pair operations any non-JCOGS image variables and unrecognised parameters enclosed by the tags.

Syntax

{attributes}

Illustration

The JCOGS Image tag:

{exp:jcogs_img:image src="{images}" width="300" attributes="style='margin-top:3em'" class="cats" data-mood="fierce"} class="eggs" data-type="lions" {attributes} {/exp:jcogs_img:image}

will generate this output

data-type="lions" data-mood="fierce" class="cats eggs" style="margin-top:3em"

Explanation: Parameters that JCOGS Image does not recognise ("unrecognised parameters") that are within the tag or enclosed by the tag pair are passed straight into the {attributes} variable. class= and style= parameters from within the tag or enclosed by the tag pair are collected and reconciled to give just one instance of each parameter in the {attributes} variable.

base_64

CE Compatibility: Full

Provides a base64 encoded version of the source image after JCOGS Image tag parameters have been applied to the source image.

Syntax

{base_64}

base_64_orig

CE Compatibility: Full

JCOGS Image - Variables - Provides a base64 encoded version of the source image before JCOGS Image tag parameters have been applied.

Syntax

{base_64_orig}

extension

CE Compatibility: Full

The filename extension of the processed image.

Syntax

{extension}

extension_orig

CE Compatibility: Full

The filename extension of the source image.

Syntax

{extension_orig}

filesize

CE Compatibility: Full

The size of the processed image in power based units (e.g. Kbytes)

Syntax

{filesize}

filesize_bytes

CE Compatibility: Full

The filesize of the processed image in bytes.

Syntax

{filesize_bytes}

filesize_bytes_orig

CE Compatibility: Full

The filesize of the source image in bytes.

Syntax

{filesize_bytes_orig}

filesize_orig

CE Compatibility: Full

The filesize of the source image in power based units (e.g. Kbytes)

Syntax

{filesize_orig}

height

CE Compatibility: Full

The height in pixels of the processed image.

Syntax

{height}

height_orig

CE Compatibility: Full

The height in pixels of the source image.

Syntax

{height_orig}

made

CE Compatibility: Full

Provides the relative path from the web_root folder to the cached copy of the processed image.

Syntax

{made}

made_url

CE Compatibility: Full

Provides a full URL pointing at the cached copy of the processed image.

Syntax

{made_url}

name

CE Compatibility: Full

The name of the processed image (without extension).

Syntax

{name}

name_orig

CE Compatibility: Full

The name of the source image file (without extension).

Syntax

{name_orig}

orig

CE Compatibility: Full

Provides the relative path from the web_root folder to the source image (if available).

Syntax

{orig}

orig_url

CE Compatibility: Full

Provides a full URL pointing at the source image (if it is available).

Syntax

{orig_url}

path

CE Compatibility: Full

Provides the full local path to the cached copy of the processed image.

Syntax

{path}

path_orig

CE Compatibility: Full

Provides the full local path to the source image (if available).

Syntax

{path_orig}

type

CE Compatibility: Full

The image format used for the processed image.

Syntax

{type}

type_orig

CE Compatibility: Full

The image format used for the source image.

Syntax

{type_orig}

width

CE Compatibility: Full

The width in pixels of the processed image.

Syntax

{width}

width_orig

CE Compatibility: Full

The width in pixels of the source image.

Syntax

{width}

Filters Last updated: 5 November 2021

brightness

CE Compatibility: Full

Adjusts the brightness of the image. Takes one value - an integer in range -255 to +255. A value of 0 produces no change, positive numbers increase brightness. Default = 0.

Syntax + Examples

filter="brightness,<integer>" - default integer value: 0

filter="brightness,30"

Illustration

{exp:jcogs_img:image width='300' filter='brightness,40'}

In this example the image is brightened by 40/255 of the maximum brightness adjustment (i.e. increased by 15%).

Illustration

{exp:jcogs_img:image width='300' filter='brightness,-40'}

In this example the image is darkened by 40/255 of the maximum brightness adjustment (i.e. decreased by 15%).

blur

CE Compatibility: New feature

Applies a gaussian blur filter to the current image. One value adjusts the amount of blur applied: value an integer in range 0 to +100. A value of 0 produces no change, positive numbers increase amount of blur. Default = 1.

Syntax + Examples

filter="blur,<integer>" - default integer value: 0

filter="blur,30"

Illustration

{exp:jcogs_img:image width='300' filter='gaussian_blur,30'}

Increase the blur in the source image by 30/100 of total range.

Usage Notes

The way in which the amount of blur applied to an image is calculated in a different way to that used in CE Image. So if you are updating a site that previously used CE Image, to get the same blur effect the value of blur applied may need to be adjusted.

colorize

CE Compatibility: Full

Adjusts the Red, Green and Blue components of an image. Three parameters, each a value in range -255 to +255. A value of 0 produces no change, positive numbers increase strength of colour. Default = 0.

Syntax + Examples

filter="colorize,<integer>,<integer>,<integer>" - default integer value: 0,0,0

filter='colorize,-20,20,-20'

Illustration

{exp:jcogs_img:image width='300' filter='colorize,-20,20,-20'}

This filter reduces the strength of the Red and Blue channels each by 20/255 (8%), and increases the stength of the Green channel by 20/255 (8%).

contrast

CE Compatibility: Full

Adjusts the contrast of the image. One parameter, a value in range -100 to +100. A value of 0 produces no change, positive numbers decrease contrast. Default = 0.

Syntax + Examples

filter="contrast,<integer>" - default integer value: 0

filter="contrast,30"

Illustration

{exp:jcogs_img:image width='300' filter='contrast,-40'}

In this example the image contrast is increased by 40/100 (40%) of the maximum adjustment, by specifying a negative amount of contrast (-40).

Usage Notes

The CE Image version of this filter has a peculiar scaling system for filter values - with maximum contrast being generated when the filter is set to its most negative value -100.

For compatibility purposes JCOGS Image has adopted this scaling system, but we are first to say that we simply have no idea why it is the way it is…!

gaussian_blur

CE Compatibility: Partial

This parameter is an alias of the JCOGS Image blur filter and included for upgrade compatibility.

Please note the comments on equivalence between JCOGS Image blur and CE Image gaussian_blur provided in the entry for JCOGS Image blur filter.

grayscale

CE Compatibility: Full

Converts an image to a greyscale version. No parameters.

Syntax + Examples

filter="grayscale"

filter="grayscale"

Illustration

{exp:jcogs_img:image width='300' filter='grayscale'}

Create a greyscale copy of the source image.

greyscale

CE Compatibility: New feature

An alias of the JCOGS Image grayscale filter, included to placate British English speaking users of the add-on… 

Syntax + Examples

filter="greyscale"

filter="greyscale"

invert

CE Compatibility: New feature

Reverses all colors of the current image to create a “negative” version of the source image. No parameters.

Syntax + Examples

filter="invert"

filter="invert"

Illustration

{exp:jcogs_img:image width='300' filter='invert'}

Create an inverted copy of the source image.

negate

CE Compatibility: Full

An alias of the JCOGS Image filter invert. Included for CE Image filter parameter compatibility.

Syntax + Examples

filter="negate"

filter="negate"

opacity

CE Compatibility: Full

Set the opacity in percent of the current image ranging from 100% for opaque and 0% for full transparency. One parameter, a value in range 0 to +100. A value of 100 produces no change. Default = 100.

Syntax + Examples

filter="opacity,<integer>" - Default: 100

filter="opacity,70"

Illustration

{exp:jcogs_img:image width='300' filter='opacity,50'}

Reduce image opacity to 50% of source image level.

Usage Notes

Opacity can only be changed on images saved in a format that supports transparency - for now that limits use of this filter to source images using the PNG format (support for WEBP transparency is to be supported in a future update).

pixelate

CE Compatibility: Full

Applies a pixelation effect to the current image. One value, the size of the pixel block to use for the pixelation effect. A value of 0 produces no change. Default = 0.

Syntax + Examples

filter="pixelate,<integer>" - Default: 0

filter="pixelate,10"

Illustration

{exp:jcogs_img:image width='300' filter='pixelate,12'}

Add pixelation to source image using a 12x12 pixel block.

sharpen

CE Compatibility: Full

Sharpen current image with an optional amount. One parameter, a value in range 0 to +100. A value of 0 produces no change. Default = 10.

Syntax + Examples

filter="sharpen,<integer>" - Default: 0

filter="sharpen,10"

Illustration

{exp:jcogs_img:image width='300' filter='sharpen,30'}

Increase the sharpness of the image by 30/100 (30%) of the total range available.

Advanced Topics Last updated: 6 November 2021

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.  It has not been updated since 19 June 2017 when version 3.0.1 was released.

In its day it was a popular add-on and many sites from that era face challenges when updating to newer versions of ExpressionEngine as prior to the release of JCOGS Image there was no easy upgrade path, and recoding the templates of these older sites to use alternative solutions was time consuming and difficult.

JCOGS Image is entirely new code written expressly for use on EE5 and EE6 systems, is compatible with the latest features of these modern versions of the CMS, supports more image formats (including webp) and is also compatible with php8; perhaps more importantly it is also actively supported. Yet it also offers a very high degree of tag-level compatibility with CE Image; offering developers a simple to implement but very high quality upgrade path for sites that were developed using CE Image.

Parameter compatibility

Currently JCOGS Image has full parameter level compatibility for 28 of the 36 parameters supported by CE Image (this excludes parameters associated with file handling). None of the currently unsupported parameters are ones that are commonly used, and so in the very large majority of use cases JCOGS Image is able to fully replace CE Image.

Some of the missing parameters are unlikely to ever be supported (e.g. the option to create ASCIIart versions of pictures), others (such as adding text and watermarks) are planned to be included in future updates.  

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 parameter definition syntax for filters, and equivalent filters for 10 of the 22 filters offered by CE Image. Some of the missing filters  - such as scatter or emboss - are unlikely to ever be supported because there is no obvious use cases for them, but it is likely that some of the missing ones will be added in future updates.

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

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:

{exp:jcogs_img:image 
width="300"
class="cats"
data-item='kibble'
src="{images}"
}

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 attribute entries between a pair of JCOGS Image tags when you have also set create_tag="yes"

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.

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

So for example, here is a pair of tags being applied to a single image source: 

{exp:jcogs_img:image 
parse="inward"
border="5|4a2d14"
create_tag='yes'
src="{exp:jcogs_img:single 
    url_only='yes'
     src='{images}' 
     width='300px' 
     border='5'}"
}
{/exp:jcogs_img:image}

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.

 

As the example tag above illustrates, if you plan to ‘nest’ JCOGS Image tags within your templates there are a few of things to remember:

Use parse="inward" to ensure enclosed tags are 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, it helps to put the EE parameter parse='inward' into the parameter list for an ‘outer’ tag to ensure that processing of the ‘inner’ tag is completed before the processing of the outer tag begins.

{exp:jcogs_img:image 
parse="inward"
border="5|4a2d14"
create_tag='yes'
src="{exp:jcogs_img:single 
    url_only='yes'
     src='{images}' 
     width='300px' 
     border='5'}"
}
{/exp:jcogs_img:image}

Use different method names and / or tag-pairs 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 ... 
{/exp:jcogs_img:image}

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=...}
{/exp:jcogs_img:image}
... some template code ...
{exp:jcogs_img:image src=...}
... some JCOGS Image variables and other content ... 
{/exp:jcogs_img:image}

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 ... 
{/exp:jcogs_img:image}

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.

Image Caching

To improve performance JCOGS Image uses a powerful image caching system to store copies of processed images on the server. Where possible JCOGS Image will re-use these cached copies of processed images rather than processing images over and over again each time a template is called.

To be effective a caching system needs to be flexible, efficient and reliable, and this is an area where JCOGS Image performance is significantly better than (e.g.) CE Image. The key differences are:

  • JCOGS Image offers fine-grained control over caching - letting you set caching strategies on a per-image basis
  • JCOGS Image cache supports variable cache-durations in addition to the ‘perpetual’ and ‘none’ options offered by CE image
  • JCOGS Image cache key mechanism provides for a more reliable association between source image, processing options and cached copy

To work reliably the caching mechanism needs to be able to differentiate between small differences in image processing options.  JCOGS Image does this using a combination of the original image file name and a cache-key that is based on a hash of all of the operations and parameters applied to the image during processing. This allows cached copies of all processed images to be stored in the same directory, and makes it possible for the same cached image to be used where ever on a site a particular combination of image and manipulations is required - it is not necessary to store multiple versions of the same image simply because the image is used in a different template (as is the case with path based caching such as used by CE Image).

Time based caching

An innovation offered by JCOGS Image is the option to set expiry times for images processed by JCOGS Image - if your site uses an image from a remote location that changes periodically but keeps the same URL, this innovation allows you to instruct JCOGS Image to refresh the local processed copy of the remote image on a similar frequency, automatically.

Fast and slow caching mode

JCOGS Image also offers to ‘modes’ of operation for its cache.  

The default mode is “Fast” - the add-on will look for a cached copy of a processed image immediately processing begins; if it finds a cached copy it will simply return this to the CMS without further checks occuring. This is fast and reliable, but has a limitation in that since the original image is not retrieved information about the source image is not available to the add-on's Template Variable system.

“Slow” cache mode waits until the source image requested has been validated by the add-on before looking for a cached copy: if a cache copy of the processed image is found the cached copy is returned and no image transformation takes place. This is strategy is necessarily slightly slower in operation to the “Fast” mode (but not significantly for locally stored images) but does make it possible to include information about the source image via the Template Variable system. 

If your site has a large number of images obtained from remote sources, use of ‘slow’ cache mode should be considered carefully - as for remote images the validation step will require the source image to be downloaded from source each time. Fortunately you can set caching mode on a per-tag basis (via the cache_mode= parameter) and so ‘Slow’ cache mode should only be used for images where you really need the original image data to be reported.

Hooks

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
ce_img_startjcogs_img_start

Called when image processing starts. 

Accepts no data. 

Returns no data.

ce_img_pre_parsejcogs_img_pre_parse

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'

Changelog Last updated: 6 November 2021

1.0.11 (25 October 2021)

  • First Commercial Release

1.0.12 (8 November 2021)

  • Bug Fixes for
    •  error in parsing the {attributes} variable
    • error in min / max precendence calculations
    • error in the processing of FIT parameter
  • Add border= parameter
  • Add cache_mode option (fast / slow)
  • Improved documentation site launched

Purchase JCOGS Image Last updated: 7 November 2021

If you have not already purchased a copy of the JCOGS Image Add-on, you can do so from either the ExpressionEngine Add-on Store, or from Devot:ee.