Add-on Documentation from JCOGS Design

UsageLast updated: 16 April 2022

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 be 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="/images/jcogs_img/cache/50802526853_0c0cdb05d0_c_-_28de80_-_09beb37dfb08841ba81890d5f23afca1042d281b.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.

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:

{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:

<figure> <img src="/media/jcogs_img/50802526853_0c0cdb05d0_c_52eef17e88ec6541ff432ac461a62cb9a1596628.webp" class="cats" width="723" height="888"> <figcaption>This picture is called tag_pair_demo.webp</figcaption> </figure>

 

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

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}

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
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
create_tag Full
crop Full
debug Not implemented Deprecated in CE Image. Comprehensive debugging information available via Control Panel option.
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
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.
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 tags generated by the add-on.
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 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
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
svg_width 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
edgedetect Full
emboss Full
gaussian_blur Partial
grayscale Full
greyscale New feature
invert New feature
lqip New feature
mask New feature
mean_removal Full
negate Full
opacity Full
pixelate 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).
smooth Full
sobel_edgify Partial Due to differences in the algorithm used to calculate the filtered image the 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
base_64_orig 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
lqip New feature Added in version 1.2
made Full
made_url Full
mime_type New feature
name Full
name_orig Full
orig Full
orig_url Full
path Full
path_orig Full
type Full
type_orig Full
width Full
width_orig Full