JIT Image Manipulation
JIT Image Manipulation provides a URL-based API for dynamically transforming images.
Overview
JIT (Just-in-time) Image Manipulation is an extension that can dynamically transform images based on a set of parameters provided to it via specially-formed URLs. The extension is able to crop and/or resize an original image (whether internal or external to a Symphony project) and then cache and return the resulting, modified image.
Usage
JIT Image Manipulation is invoked via a specially-formed URL. The base of the URL is http://your-site.com/image/. Additional URL parameters follow, specifying the desired transformation mode, options, and file location (see below).
The extension can be utilized from within Symphony's templating layer by using this special URL in the src attribute of an img element. For example:
<img src="http://yoursite.com/image/1/200/0/images/ninja-parade.jpg"/>
External Images & Trusted Sites
In order for the extension to be able to transform external images, the images' host domain must first be added to the whitelist of "Trusted Sites" in System > Preferences. Trusted sites can be added one per line and should be in the following format:
images.external-site.com*
Recipes
Recipes are named rules for the JIT settings which help improve security and are more convenient. They can be edited on the preferences page in the JIT section and are saved in /workspace/jit-image-manipulation/recipes.php. A recipe URL might look like:
<img src="{$root}/image/thumbnail{image/@path}/{image/filename}" />
When JIT parses a URL like this, it will check the recipes file for a recipe with a handle of thumbnail and apply it's rules. You can completely disable dynamic JIT rules and choose to use recipes only which will prevent a malicious user from hammering your server with large or multiple JIT requests.
Recipes can be copied between installations and changes will be reflected by every image using this recipe.
Details
Modes
JIT Image Manipulation has four modes of operation, each of which requires a slightly different URL structure. See below for details on specific parameters.
| Mode | URL Structure and Description |
|---|---|
|
/ image / e / path Default: Direct display will simply display the original image as-is when no mode is provided. |
|
| 1 |
/ image / 1 / w / h / e / path Mode 1: Resize will resize the original image using the width and height parameters provided. If either width or height is |
| 2 |
/ image / 2 / w / h / p / e / path Mode 2: Crop to Fill will first use the position parameter and the smaller of the two dimension parameters (width and height) to resize the image while maintaining its original aspect ratio. Then it will crop the remainder of the image using the other (larger) dimension. |
| 3 |
/ image / 3 / w / h / p / b / e / path Mode 3: Crop will resize the original image’s canvas using the width, height, and position parameters. If the resulting canvas size is smaller than the original in either dimension, the original will be cropped. If it is larger than the original in either dimension, the additional space will be filled using the background color parameter. |
| 4 |
/ image / 4 / w / h / e / path Mode 4: Resize to Fit will resize the original image to fit within the width and height parameters while maintaining aspect ratio. This option does not crop the image and ensure both width and height of the image stays within the defined boundaries. |
Parameters
Image transformation options are specified via the following parameters:
| Parameter | Description |
|---|---|
| Width | Number in pixels. If 0, height must be specified and width will auto-adjust, keeping original aspect ratio. |
| Height | Number in pixels. If 0, width must be specified and height will auto-adjust, keeping original aspect ratio. |
| Position | Number 1–9, specifying region from which to crop/resize. See grid below. |
| Background Color | Hex color value. Supports CSS-style short hex strings (ff2233 == f23) |
| External | Optional. 0 or omitted for internal images. 1 for external images. |
| Path | Path to the original image. If the image is internal, this is a relative path from /workspace. If the image is external, it is a URL (excluding http://). |
Positioning Grid
When using the "Crop to Fill" or "Resize Canvas" modes, the transformation will be anchored according to a position parameter. The image below shows the possible parameter values along with their respective positions.
