IntroductionLast updated: 14 October 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. - 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.22, but note that not all the features in 1.4.4 are available to you.
The documentation that follows is for JCOGS Image 1.4.4; most of which also applies to version 1.3.22.
Minimum Requirements
To use JCOGS Image 1.4.4 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 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.22
- ExpressionEngine 6 installations - use php 8.1 and JCOGS Image 1.4.4
- ExpressionEngine 7 installations - use php 8.2 and JCOGS Image 1.4.4
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.