Add-on Documentation from JCOGS Design

IntroductionLast updated: 16 April 2022

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

JCOGS Image provides comprehensive image manipulation options, along with a range of development tools to make it easier to include 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 png). The range of image formats available is limited only by the capabilities of the GD2 library installed on your server - formats that on many servers 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 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.

Development 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
    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 they would not be able to see an image in the format pre-chosen JCOGS Image will adjust the format on the fly to send them an 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, JCOGS Image offers exceptional compatibility with the legacy CE Image add-on. JCOGS Image offers developers a simpler upgrade path for EE2 and EE3 sites developed using the CE-Img add-on: in most cases it is possible to upgrade a site by simply doing a search / replace - for example {exp:ce_img:single...} with {exp:jcogs_img:single...}. Easy! Due to JCOGS Image's outstanding compatibility with CE Image, most such upgrades are achieved without loss of function.
    • 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

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 or from Devot:ee. 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.