Add-on Documentation from JCOGS Design

IntroductionLast updated: 10 December 2022

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 EE'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 available 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
  • 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 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
  • 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 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.

Requirements

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

  • A web server running php version 7.4, 8 (recommended) or 8.1 (recommended).
  • 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 5, 6 or 7 installation.

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 you try to process a template containing JCOGS Image tags on a server that does not meet the JCOGS Image requirements these tags will return no output. However, if JCOGS Image debugging is enabled, the tags will write messages into the EE template debugging log to let you know about which server requirement is not currently being met.

Usage Notes

Note: Limits on supported php version

JCOGS Image itself is php 8.2 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
  • ExpressionEngine 6 installations - use php 7.4 → php 8.1 
  • ExpressionEngine 7 installations - use php 8.0 → php 8.2

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.

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

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.