Add-on Documentation from JCOGS Design

IntroductionLast updated: 12 December 2024

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

Features

JCOGS Image provides comprehensive image manipulation options, along with additional features and tools that make it easier to optimise the use of images within your templates.

Image Manipulation Options

These  fall into three categories:

  • Conversion
    JCOGS Image can perform on-the-fly conversion of image formats (e.g. jpg to webp). The range of image formats supported is limited only by the capabilities of the GD2 library installed on your server - on most servers this will include gif, png, jpg, gif, windows bmp (wbmp), bmp, xbm and webp. In addition JCOGS Image can read HEIC format images.
  • Resizing
    JCOGS Image can crop and resize images and includes the ability to generate multiple versions of the same image for use in responsive variants of the HTML <img> tag. Image cropping and resizing operations can use nominated aspect ratios, and can be combined in one tag (scale and crop).
  • Manipulations
    JCOGS Image can apply an extensive range of effects and adjustments to the appearance of an image; these including reflection around horizontal or vertical axis, rotation, and the application of a range of image filters (e.g. greyscale, blur etc). Manipulations can be combined sequentially within a single operation and can be applied to converted / resized images.

Developer tools

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

  • Built in support for Cloud File Systems
    JCOGS Image's powerful unified image cache can be stored either locally to the web server it is running on, or on one of several Cloud File Systems such as AWS S3.
  • Built in support for advanced HTML image tags
    JCOGS Image can generate <img> tags automatically and concurrently include with these advanced options such as support for lazy-loading of images and the generation of multiple images to support responsive image definitions via the HTML5 srcset parameter.
  • Automatic passthrough and consolidation of non-Image parameters
    JCOGS Image passes through to the generated <img> tag anything entered into a tag that are does not comprise valid Image parameters: you can enter things like "alt" and "data" attributes for the final <img> tag directly into the JCOGS Image tag. If you include "class" and / or "style" parameters, these will be passed through - but also multiple parameters of this type will be consolidated into just one attribute in the created tag. More on this feature here.
  • Dynamic image format selection based on browser capabilities
    The image formats supported by JCOGS Image are limited only by the limitations of your host server, but to ensure that your images are seen it also includes active monitoring of the image formats supported by the user's browser: if a user would not be able to see an image in the format chosen by the developer JCOGS Image can automatically adjust the image format on the fly - regenerating the processed image in a format they can see - a feature that takes much of the risk out of adopting ‘new’ image formats such as webp.
  • Default fallback images
    With JCOGS Image you can specify fallback images on a per-tag basis, but also choose a global fallback image - which can be a local or remote image, or a simple colour field.
  • Batch Processing
    JCOGS Image can be applied to single image instances or collections of images (to which the same modifications are applied) - a great option for cleaning up the images included by your editors in blog posts (for example)!
  • CE Image compatibility
    Although it is based on a completely new image processing code base and supports modern web standards such as php8 and the webp image format, and is fully compatible with ExpressionEngine version 7, JCOGS Image also offers exceptional compatibility with the legacy CE Image add-on. JCOGS Image offers developers a simple upgrade path sites developed using the CE-Img add-on: in most cases it is possible to simply search / replace ‘ce_img’ with ‘jcogs_img’ - for example {exp:ce_img:single...} becomes {exp:jcogs_img:single...}. Easy! Due to JCOGS Image's outstanding compatibility with CE Image, almost all such tag upgrades are achieved without any loss of function or change in output appearance.
    • 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.

* Note: JCOGS Image's support for EE5 is provided through use of version 1.3.22 of the add-on. This version is also compatible with php 7.4 should this be required.

Requirements

Important Note:

As of version 1.4.0 the minimum requirements for JCOGS Image have changed: you will need a server running ExpressionEngine 6 and 7 and php 8.1 (or better) for the add-on to operate.

If your server is running ExpressionEngine 5 or php 7.4, use JCOGS Image 1.3.23, but note that not all the features in 1.4.11 are available to you.

The documentation that follows is for JCOGS Image 1.4.11; most of which also applies to version 1.3.23.

Minimum Requirements

To use JCOGS Image 1.4.0 or later you will need the following things to be available / in place:

  • A web server running php version 8.1 or better.
  • The web server's php installation needs to have a copy of the GD or GD2 library installed.
  • The web server's php installation needs to have the allow_url_fopen directive set - Image needs this to complete license validation and to retrieve remote images.
  • An ExpressionEngine 6 or 7 installation - with a valid value set for the EE base_path configuration setting.

JCOGS Image will do its best to let you know if a requirement is not being met:

  • Within the Control Panel / Setup area JCOGS Image will display a warning message outlining what element of the requirements is not currently being met.
  • If JCOGS Image debugging is enabled, JCOGS Image tags will write messages into the EE template debugging log to let you know about any server requirement that is not being met.

Usage Notes

Note: Limits on supported php versions

JCOGS Image itself is php 8.2 and 8.3 compatible. However ExpressionEngine 5 and ExpressionEngine 6 have limitations when it comes to use of advanced versions of php. So for compatability we recommend use of the following php versions:

  • ExpressionEngine 5 installations - use php 7.4 and JCOGS Image 1.3.23
  • ExpressionEngine 6 installations - use php 8.1 and JCOGS Image 1.4.11
  • ExpressionEngine 7 installations - use php 8.2 and JCOGS Image 1.4.11

Usage Notes

Note: Image processing libraries

Currently JCOGS Image relies upon the php GD library to operate; support for other libraries (e.g. Gmagick and Imagick) is being developed.

Usage Notes

Using JCOGS Image on servers configured to use open_basedir

Open_basedir is a facility in php that limits the files that can be accessed by php to a specified file-tree (or file-trees); it is a method for improving the security of a server. Since version 1.4.2 JCOGS Image is operationally fully compatible with use of this system.

Usage Notes

Using JCOGS Image with EE Coilpack

JCOGS Image is compatible with EE Coilpack, but operation of the bulk tag is improved if an additional parameters is added to the call to the function from whatever templating environment you using (e.g. Twig, Blade) - the additional parameter required is:

tagdata: text,

Installation

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

Updating

To update the add-on copy the updated jcogs_img folder to your system/user/addons folder, replacing the folder that was there before, and then update the add-on from the ExpressionEngine Control Panel Add-ons page.

Usage Notes

Important Note: 

When you update an earlier copy of JCOGS Image to version 1.4 or greater, due to changes in the configuration of JCOGS Image's Unified Cache (to enable new features related to the cloud file systems), your existing processed image cache will be cleared.

Usage Notes

Third-party Caching: 

When you update JCOGS Image may clear both its own Image cache and the EE Template cache; it does this when this is necessary to ensure that when your site's pages next are accessed the images displayed are the correct ones. 

If you have installed a third-party caching tool (such as Speedy or Rocket) or if your site uses an external caching system (Litespeed, Varnish etc.) you will need to ensure yourself that those caches are cleared as appropriate; failure to do so may lead to unpredictable output from your website until such times as those caches reset themselves.

Licensing and Operating Modes

JCOGS Image is licensed software, to get full use from it you will need to purchase a license key.

A license key will allow the add-on to operate without limitation on a single EE installation running on a server connected to the public internet and on any number of EE installations linked to servers with local IP ranges or using domains ending in any of these top level domain suffixes: acc, acceptance, demo, example, invalid, loc, local, localhost, sandbox, stage, staging, test, testing, vm.    

You can to purchase a license online from the EE Add-on Store. Once purchased, enter your license key and the email address used for the purchase into the appropriate boxes in the System Defaults section of the JCOGS Image add-on control panel pages.

Use with staging servers

To facilitate the development of sites, licensed copies of JCOGS Image offer you the opportunity to register a staging server linked to a separate public internet domain to use alongside the live site. 

Enter the domain name of the staging server into the input field that will appear below the spaces used to register the license key and email address. 

The license status of the staging server will be recognised automatically when you install a copy of JCOGS Image on the staging server.

Using JCOGS Image without a license - demonstration mode

When used without a license JCOGS Image will operate in a demonstration mode. 

 

While in demonstration mode JCOGS Image is fully functional, making it possible for you to fully evaluate the software, however:

  • When demonstration mode is enabled JCOGS Image will add a watermark to any images processed.

If you encounter any difficulties activating your add-on please contact support@jcogs.net with details.