Add-on Documentation from JCOGS Design

ParametersLast updated: 5 November 2022

The parameters and variable definitions for all three tag types are the same.

Some parameters and variables are marked with CE in first column. These parameters are named identically and have equivalent function to CE-Image parameters of the same name; implementation differences are noted in comments next to each.

auto_sharpen

CE Image Compatibility: New feature

A parameter that requests JCOGS Image to apply the auto_sharpen filter to the processed image. 

There is only one valued - either yes or no - if the value is yes then the auto_sharpen filter is applied to the image during processing. 

This parameter is equivalent to including the term ‘auto_sharpen’ in the string supplied to the filter parameter. The parameter is primarily intended as a means to give users the ability to selectively over-write the setting of the Enable Auto Sharpening by default default image setting.

Note: if the filter parameter is supplied the ‘auto_sharpen’ value, the filter will be applied to the processed image regardless of the value provided by the auto_sharpen parameter.

Syntax + Examples

auto_sharpen='yes|no' - default value: ‘no’.

auto_sharpen='yes'

auto_sharpen='no'

Illustration

{exp:jcogs_img:image width='300' auto_sharpen='yes'}

Apply the sharpen filter to an image using the auto_sharpen parameter.

Usage Notes

If other filter values are specified in the same tag, and those other filters include auto_sharpen, then adding this parameter to the tag will have no effect.

If other filter values are specified but those other filters do not include auto_sharpen, then the auto_sharpen filter will be applied after those other filters have been applied.

add_dims

CE Image Compatibility: Full

Determines whether  HTML img dimension parameters width= and height= will be included within <img> tag.  The parameter is ignored where the tag does not output an <img> tag.

Syntax + Examples

add_dims="yes|no" - default value: yes for single tags, no for tag-pairs.

add_dims="yes"

Illustration

{exp:jcogs_img:image add_dims="yes" width="300"}

This single JCOGS Image tag will produce an HTML img tag containing width= and height= parameters.

Usage Notes

If you also choose options that will cause the JCOGS Image to generate an HTML <img> tag, this parameter will determine whether the HTML img dimension parameters (width= and height=) will be included in the tag.

add_dimensions

CE Image Compatibility: New feature

An alias for the add_dims parameter. See the definition of add_dims for parameters.

Usage Notes

If both add_dims and add_dimensions parameters are specified in the same tag, the value of add_dims will be used.

allow_scale_larger

CE Image Compatibility: Full

This parameter controls whether JCOGS Image is allowed to increase the size of the image to fit within the dimensions specified for the final image.

Syntax + Examples

allow_scale_larger="yes|no" - default value: no

allow_scale_larger="yes"

Usage Notes

Only applies to resize operations. Ignored otherwise.

If the parameter is set to no and other operations specified can be completed without enlarging the image then this parameter will have no effect. 

If the parameter is set to no and any of the other operations specified would require the size of the image to be increased for the operation to complete, these other operations are not applied.

aspect_ratio

CE Image Compatibility: New feature

Adds a constraint to some operations to use the specified aspect ratio to constrain the dimensions of the final image. 

The aspect ratio is defined as the ratio between the horizontal and vertical dimensions, and is submitted to the addon in the form of two values separated by a spacing character - for example 16_9.  The first integer value relates to the horizontal dimension, and the second to the vertical dimension. Any two values can be used. 

If the value given does not conform to the required format, the aspect ratio parameter is ignored.

If both width and height are specified in the tag then this parameter is ignored.

Most often the parameter is used with the crop operation, but also can be used when resizing images and the fit parameter is specified.

For cropping operations, aspect ratio is used to calculate the required image height if only width is specified, or the required image width if only height is specified. If neither width nor height are specified, the required height is calculated based on the width of the source image.

For resizing operations where only one dimension is specified (height or width) the aspect ratio is used to impute the other dimension of the ‘bounding box’ for the resized image so that the fit parameter can determine the appropriate height and width for the image after the resize.

Syntax + Examples

aspect_ratio="<integer>[_|px|%]<integer>" - default value: if the value provided is not a valid aspect ratio, the original aspect ratio is maintained.

aspect_ratio="16_9"

aspect_ratio="5/7"

aspect_ratio="4:3"

Illustration

{exp:jcogs_img:image width='300' aspect_ratio='16_9' crop='y'}

In this example the image will be scaled to be 300 px wide, and the height is set according to the aspect ratio specified.

Usage Notes

If both height and width are specified in the tag then this parameter is ignored.

attributes

CE Image Compatibility: Full

Content to be passed through to output unchanged.

If creation of an <img> tag is requested this content is simply placed within the tag along with any calculated values (e.g. width). 

The content is also available via the {attributes} variable which can be used in a single JCOGS Image tag within the output= parameter, or when using a tag-pair.

Syntax + Examples

attributes="<any content>" - default value: null

attributes="class='cats' style='margin:3em' data-toggle='up'"

Illustration

{exp:jcogs_img:image width='300' attributes="class='cats'" class="dogs"}

This example adds the content class='cats dogs' to the HTML <img> tag created by combining the class value specified in the attributes= parameter with the class attribute passed through as an unrecognised parameter.

Usage Notes

It is possible to end up in a situation where you have specified content for the attributes parameter in more than one place - for example by specifying an attributes= parameter in a tag-pair, including unrecognised parameters within the JCOGS Image tag, and / or including additional parameters within the content enclosed by the tag-pair.  

When this happens, JCOGS Image simply combines the content of all the sources found, but also intelligently combines any  class= and style= elements so that only one of each is included in the resulting output.

bg_color

CE Image Compatibility: Full

Defines the colour of the background behind the image layer during processing. If the image processing (e.g. rotation or the removal of transparency) will cause the background to show, this is the colour that appears.

The colour can be specified using any valid JCOGS Image colour format.

Syntax + Examples

bg_color="[#]<3 or six digit hex_colour_code>" - default value: #FFFFFF (White)

bg_color="#373859"

bg_color="343434"

bg_color="#F7F"

border

CE Image Compatibility: Full

Define a solid color border around an image. 

For operations that change the shape of the image - for example applying a shape mask or rounded corners - the border is drawn relative to the resulting shape.

The border width can be be specified using any valid JCOGS Image dimension format (i.e. with or without a px suffix or as a %). % values will be evaluated relative to the width of the processed image that the border is being added to.

The colour should be specified using any valid JCOGS Image Colour format.

Syntax + Examples

border="<integer>[px|%]|[#]<three or six digit hex colour code>" - default value: 0|#FFFFFF

border="10|4a2d14"

border="10px"

border="10px|#DDD"

Illustration

{exp:jcogs_img:image width='300' border='10|4a2d14'}

In this illustration a border colour #4a2d14 that is 10 pixels wide is added to the image.

Illustration

{exp:jcogs_img:image width='300' border='15px|rgb(220,240,260)' rounded_corners='all,20px' save_type='png'}

A border added to an image with rounded corners.

Illustration

{exp:jcogs_img:image width='300' border='15px|rgb(255,176,5)' filter='mask,polygon-7' save_type='png'}

A border added to an image that has been masked with a shape.

Usage Notes

The border is added to the outer edge of the image, so the size of your image will increase by 2x the width of border specified in each dimension.

Usage Notes

Performance Note: 

  • Adding a border to a standard rectangular image is a straightforward activity and is completed rapidly by JCOGS Image.
  • Adding a border to an image that is not rectangular (e.g. after transformations such as masking or adding rounded corners have been applied) is more complicated. The method used by JCOGS Image is efficent and effective but resource intensive; for optimum site performance it is recommended that you ensure that non-rectangular images with borders added are cached.

cache

CE Image Compatibility: New feature

This parameter allows the cache setting for an image to be set at the tag level.

The parameter takes one value, which indicates the duration that cached image should remain in the cache.  There are three options:

  • cache="-1" The cache is set to ‘perpetual’ mode - an image will be kept in the cache until it is deleted (or overwritten). This option is the default value set when JCOGS Image is first installed.
  • cache="0" The cache is disabled - processed images will not be saved to the cache, and JCOGS Image will not look for cached copies of processed images.
  • cache="<integer>" JCOGS Image will create cache copies of processed images and continue to use them for <integer> seconds after the cached image is created.

If set in a tag, the value will over-rule the default value set in the JCOGS Image Control Panel Settings area (which is set to -1 when JCOGS Image is first installed).

Syntax + Examples

cache="-1|0|<positive integer value>"

cache="-1" - set the cache to perpetual mode for this tag

cache="0" - turn off caching for this tag

cache="604800" - set the cache to 604800 seconds (1 week)

cache_dir

CE Image Compatibility: Full

Defines the path to the JCOGS Image cache folder relative to the web_root directory.

This value if specified in a tag will over-rule the default location specified in the JCOGS Image control panel settings for that tag only.

Syntax + Examples

cache_dir="<path to folder to use>" - default value: the path specified in JCOGS Image Control Panel Settings area

cache_dir="media/images/cats"

Usage Notes

If the folder specified does not exist, JCOGS Image will try to create it; if that activity fails the tag processing will stop.

The value can be specified with or without a trailing slash.

create_tag

CE Image Compatibility: Full

Controls whether a tag will produce as output an HTML <img> tag.

The default for single tags is for create_tag= to be ‘yes’, the default for tag-pairs is for create_tag= to be ‘no’; this difference reflects the different modes of operation provided by single and pair tags.

Syntax + Examples

create_tag="yes|no" - default value: for single-tags “yes”, for tag-pairs “no”

create_tags="yes"

create_tags="y"

Usage Notes

If create_tag="no" is specified for a single JCOGS Image tag, the image specified will be processed by the tag but no output will be returned to the template.

This option can be useful when debugging a template - as if JCOGS Image debugging is turned on the image processing steps will still generate debugging reports in the template debug log without adding an image to the template output.

crop

CE Image Compatibility: Full

Controls whether an image will be resized to fit the dimensions given or will be cropped. 

Cropping an image allows for a smaller section of the source image to be extracted; you can control the size of the smaller section and also the position on the source picture from which you want the smaller section to be extracted.

JCOGS Image supports (by default) ‘smart scaling’ of the cropped image - a process by which JCOGS Image will attempt to reduce the size of the source image such that after the crop in one dimension the whole of the original image can be seen, and in the other the source image will be cropped to fit the overall dimensions given.

The crop will be determined by the dimensions given in the tag - either via specifying width and height parameters (or their proxies, such as min-height or max) or specifying one dimension and an aspect ratio (which will cause JCOGS Image to crop the image using a shape calculated from the dimension given).

The need for this information leads to a quite complex definition - comprising up to four sets of values separated by the | symbol.

  • The first value indicates whether or not to crop the image and takes the values yes or no.  The default value is no.
  • The second value specifies the overall position for the crop shape relative to the source image in the form horizontal location, vertical location - where the horizontal position is one of left|center|right and the vertical position is one of bottom|center|top. The default values are center,center.
  • The third value specifies an adjustment of the position for the crop relative to the overall position, and is defined by two values, the first specifying in pixels how much to move the crop shape horizontally the second how much to move the crop shape vertically. The values can be positive or negative integers. The default values are 0,0.
  • The fourth value specifies whether to use smart scaling. It can take the values yes or no. The default value is yes.

Because of these defaults, specifying crop='yes' in a tag will cause it be cropped relative to the center point of the source image, and for the cropped image to be adjusted via super scaling.

Syntax + Examples

crop="yes|no[|[left|center|right],[bottom|center|top][|<integer>,<integer>[|[yes|no]]]]" - default value: no|center,center|0,0|yes

crop="yes" - equivalent to crop="yes|center,center|0,0|yes"

crop="yes|center,top" - equivalent to crop="yes|center,top|0,0|yes"

crop="yes||0,-20" - equivalent to crop="yes|center,center|0,-20|yes"

crop="yes|right,bottom|20,-20|no" - equivalent to crop="yes|right,bottom|20,-20|no"

Illustration

{exp:jcogs_img:image width='300' height='200' crop='yes'}

Crop an image to be 300 pixels wide and 200 pixles tall.

The resulting image is smart scaled to fit into a shape with dimensions 300px by 200px

Illustration

{exp:jcogs_img:image width='300' crop='yes' aspect_ratio='7:5'}

Crop an image to be 300 pixels wide and with an aspect ratio of 7x5.

The resulting image is smart scaled to fit into a shape with dimensions 300px by 214px

Illustration

{exp:jcogs_img:image width='200' crop='yes|||no' aspect_ratio='5:7'}

Crop an image to be 200 pixels wide with an aspect ratio of 5x7 with smart scaling turned off.

The resulting image will be a sub-section of the center of the image with dimensions 200px x 280px.

Illustration

{exp:jcogs_img:image width='300' crop='yes|left,top|50,50|no' aspect_ratio='16_9'}

Crop an image to be 300 pixels wide with an aspect ratio of 16:9 with smart scaling turned off, and with the crop taken from top left of the source image offset by 50 pixels in the horizontal and vertical directions.

The resulting image will be a sub-section of the top-left of the source image with dimensions 300px by 168px.

disable_browser_checks

CE Image Compatibility: New feature

Determines whether JCOGS Image will check to see if the user's browser is able to display the processed image format selected.

This parameter can be used to over-ride the default setting for this behaviour set in the add-on's control panel area.

Syntax + Examples

disable_browser_checks="yes|no" - Default: no

disable_browser_checks="yes"

disable_browser_checks="no"

fallback_src

CE Image Compatibility: Full

Allows for the defintion of a fallback image that is used in cases where either the src= parameter is not specified, or is specified but the information provided does not point to a valid image.

This parameter is useful in cases where the developer cannot always be sure that the intended image data will always be available.

The options for what information is used to define the fallback_src= parameter is identical to that for the src= parameter.

Fallback information can also be specified via the system default values set through the add-on control panel; the fallback source specified within a tag will have priority over the default value.

Syntax + Examples

fallback_src="<any valid local image path>|<any valid remote image path>" - default value: null

fallback_src="/media/images/default_backdrop.jpg"

fallback_src="https://placekitten.com/400/300"

Illustration

{exp:jcogs_img:image width='300' src='cats' fallback_src='https://placekitten.com/400/300'}

In this example src= image data is not provided so the image used is the one specified by the fallback_src= parameter.

filename

CE Image Compatibility: Full

Allows you to specify the filename prefix you would like the processed image to use.

JCOGS Image names the processed images it generates using a combination of a filename and some special characters used to support reliable cache operations: this combination preserves potentially useful file naming information for Search Engines while allowing JCOGS Image to attach the cache related information it needs to the processed image filename.

This parameter allows you to specify an alternative to for the original filename of the image.  Note: this does not replace the full filename of the processed image, just the initial element.

For example, an image with the original name our_office.jpg when processed might be given the filename of our_office__-_2710_-_0a257337af443a3a347dcd528e6b77f6dccf82d4.jpg.  When the tag generating the image includes the parameter filename='Cats_Make_Curious_Companions' the processed image filename would be Cats_Make_Curious_Companions__-_2710_-_0a257337af443a3a347dcd528e6b77f6dccf82d4.jpg.

Syntax + Examples

filename="[<string>]" - default: null

filename="Cats_Make_Curious_Companions"

filename_prefix

CE Image Compatibility: Full

Allows you to specify a prefix to add to filename the processed image will use.

JCOGS Image names the processed images it generates using a combination of a filename and some special characters used to support reliable cache operations: this combination preserves potentially useful file naming information for Search Engines while allowing JCOGS Image to attach the cache related information it needs to the processed image filename.

This parameter allows you to specify a prefix to be added to the original filename of the image.

For example, an image with the original name our_office.jpg when processed might be given the filename of our_office__-_2710_-_0a257337af443a3a347dcd528e6b77f6dccf82d4.jpg.  When the tag generating the image includes the parameter filename_prefix='Cats_' the processed image filename would be `Cats_our_office__-_2710_-_0a257337af443a3a347dcd528e6b77f6dccf82d4.jpg.

Syntax + Examples

filename_prefix="[<string>]" - default: null

filename_prefix="Cats_"

filename_suffix

CE Image Compatibility: Full

Allows you to specify a suffix to be appended to the filename the processed image will use.

JCOGS Image names the processed images it generates using a combination of a filename and some special characters used to support reliable cache operations: this combination preserves potentially useful file naming information for Search Engines while allowing JCOGS Image to attach the cache related information it needs to the processed image filename.

This parameter allows you to specify a suffix to add to for the original filename of the image.  Note: adds the suffix to the original filename, it does not add a suffix to the whole processed image filename.

For example, an image with the original name our_office.jpg when processed might be given the filename of our_office__-_2710_-_0a257337af443a3a347dcd528e6b77f6dccf82d4.jpg.  When the tag generating the image includes the parameter filename_suffix='_likes_cats' the processed image filename would be `our_office_likes_cats__-_2710_-_0a257337af443a3a347dcd528e6b77f6dccf82d4.jpg.

Syntax + Examples

filename_suffix="[<string>]" - default: null

filename_suffix="_likes_cats"

filter

CE Image Compatibility: Full

Allows for the specification of one or more filters to be applied to the image during processing.

The syntax for this parameter comprises a series of pipe (|) separated sub-parameter blocks - each sub-parameter block relating to a filter you want to apply.

Filters are applied to the image in the order that they are specified in the filter parameter.

As each filter has its own parameters the definition of the sub-parameters is discussed in more detail in the separate filters section of this document.

Syntax + Examples

filter="<filter parameter definition>[|<filter parameter definition>]

filter='grayscale' 

filter='colorize,-20,20,-20'

filter='colorize,-20,20,-20|blur,5'

Illustration

{exp:jcogs_img:image width='300' filter='colorize,-20,20,-20|blur,5'}

In this example the image has a colorize filter applied followed by a blur filter.

fit

If two image dimensions are given (or implied) in a JCOGS Image and crop is not also specified, this tag determines how the image is scaled relative to the two dimensions.

The parameter can take one of three values: 

  • contain  The image is scaled to fit within the box defined by the two dimensions given (or imputed) while maintaining the image aspect ratio.whether image is scaled to fit completely into dimension (contain), or scaled to ensure image extends to all edges of bounding box without distortion. This is likely to result in a image that is smaller than the area defined by the bounding box. (cover), or is distorted to fit into space defined. This is the default value.
  • cover The image is scaled to completely fill the box on both dimensions. This is likely to result in an image that is larger than teh area defined by the bounding box.
  • distort The image dimensions are preserved and the image is allowed to be distorted to fit into the space defined.

Syntax + Examples

fit="contain|cover|distort" - Default: ‘contain’

fit="contain"

fit="cover"

fit="distort"

Illustration

{exp:jcogs_img:image width='300' height='300' fit='contain'}

Contain

The image is scaled to fit within the 300x300 bounding box specified.

Illustration

{exp:jcogs_img:image width='300' height='300' fit='cover'}

Cover

The image is scaled to fill the 300x300 bounding box specified.

Illustration

{exp:jcogs_img:image width='300' height='300' fit='distort'}

Distort

The image is distorted to fit within the 300x300 bounding box specified.

Usage Notes

If the parameter is specified with no value (e.g. fit="") or an unrecognised value it is ignored and the default value is used.

flip

CE Image Compatibility: Full

Instructs JCOGS Image to flip the image content around either the vertical or horizontal axis (or both).

Syntax + Examples

flip=h|v|h|v - Default value: null

flip='h'

flip='v'

flip='h|v'

Illustration

{exp:jcogs_img:image width='300' flip='v'}

Flip the image about the vertical axis.

hash_filename

CE Image Compatibility: Full

JCOGS Image names the processed images it generates using a combination of a filename and some special characters used to support reliable cache operations: this combination preserves potentially useful file naming information for Search Engines while allowing JCOGS Image to attach the cache related information it needs to the processed image filename.

For example, a file with the original name our_office.jpg might be given an output filename of our_office__-_2710_-_0a257337af443a3a347dcd528e6b77f6dccf82d4.jpg

This parameter allows you to obscure the original of the image in the output filename - the original name is replaced by a hash. Possible values are "yes" and "no", with the default being "no".

When enabled, this option would result in an output filename for our example image becoming something like 1d48854ed203acf437ef4a09c1112973fd5c9ad6__-_2710_-_0a257337af443a3a347dcd528e6b77f6dccf82d4.jpg.

Syntax + Examples

hash_filename=[yes|no] - Default: no

hash_filename="yes"

height

CE Image Compatibility: Full

Sets the height of the image to be produced.  The value can be given as an integer number (of pixels) with or without a trailing px suffix, or as a percentage value (an integer with a trailing %). If a percentage is specified, it is converted into a pixel value by multiplying the percentage value by the original image height.

If the value is not specified, JCOGS Image will try to impute a value for height from other parameters specified.

Syntax + Examples

height="<integer value>[px|%]" - Default value = “”

height="200px"

height="180"

height="33%"

Illustration

{exp:jcogs_img:image height='150px'}

Set the height of the image to 150px.

Since no other information is given, JCOGS Image will scale the image in proportion to its original dimensions to give the height requested.

Usage Notes

Precedence

This parameter will be potentially over-ruled by any explicit settings for  min_height= or max_height= or min= or max= in a tag.

% values

If a % value is specified, JCOGS Image works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

image_path_prefix

CE Image Compatibility: New feature

Enter a prefix for the published path to a processed image.
If entered, this value will be prefixed to the processed image path in all HTML tags generated by JCOGS Image and will also made available via the {made_with_prefix} variable.
Note: Even if specified here, the prefix will only be added to a JCOGS Image tag that has the parameter use_image_path_prefix='yes' set, otherwise this value is ignored.
A default value for this setting can be set within the Default Settings section of the Add-on Control Panel area.

Syntax

image_path_prefix="<path to prefix to URLs generated by Image>"

image_path_prefix="https://my_cdn/my_images/"

interlace

CE Image Compatibility: Full

When this parameter is set to ‘yes’ it instructs JCOGS Image to save the processed image as an interlaced (or ‘progressive’) jpg image.

Syntax + Examples

interlace="yes|no" - Default: no

interlace="yes"

interlace="no"

Usage Notes

This parameter is ignored if the save_type= parameter is set to anything other than jpg.

lazy

CE Image Compatibility: New feature

Instructs JCOGS Image to configure the <img> tag created to ‘lazy load’.

Lazy-loading is a technique to speed up the loading of image intensive pages: the loading of full-size images is deferred while the image is outside the part of the screen currently being viewed by the user.

JCOGS Image's approach to lazy-loading is one that is performant and offers strong compatibility with current browsers:

  • it activates the HTML5 loading="lazy" parameter in image tags it creates - which defers loading image files until they come close to the browser viewport: by not downloading images that cannot be seen this reduces the amount of content that has to be downloaded from the server prior to rendering the page
  • it replaces the processed image within the <img> tag with a placeholder image created from the processed image; these are images that have the same dimensions as the processed image but are either a low-resolution version of that image, or a plain colour field that is keyed to the ‘dominant colour’ of the processed image. This placeholder image has the same dimensions as the processed image but is much smaller than the original image
  • it also loads a small javascript utility with the page which monitors whether an image is ‘in-view’ and replaces the placeholder image with the full-resolution processed image just before the image appears on screen.

The method used works and for the most-part is transparent to the user.

Lazy-loading can be set as a system option in the add-on control panel, and / or be set by adding the lazy= parameter to a tag.  There are four options for the tag:

  • no - turns off lazy-loading for this tag - over-rules any system default that has been set
  • html5 - turns on lazy-loading via the HTML5 loading=lazy option, but does not enable placeholder image substitution
  • lqip - low quality image placeholder - turns on lazy-loading and instructs that the placeholder image should be a representative of the processed image, but much smaller (typically between one quarter and one sixth of the size of the processed image it is replacing)
  • dominant_color - turns on lazy-loading and instructs that the placeholder image should be a simple colour-field using the ‘dominant colour’ of the processed image - such simple colour fields are very much smaller than the image they replace - often being less than one twentieth of the size of the processed image being replaced

JCOGS Images' lazy-loading system is completely compatible with its responsive image options delivered via the srcset= option.

A more detailed discussion of how JCOGS Image's lazy-loading mechanism works is given in the Advanced Topic “Lazy Loading”.

Illustration

Full-size Image - 9Kb
LQIP Image - 2Kb
Dominant Colour Image - 200 bytes

For more information about how JCOGS Image has implemented lazy-loading, see the Advanced Topic entry “Lazy Loading”.

Syntax + Examples

lazy="no|lqip|dominant_color" - default as set in Control Panel option

lazy="no"

lazy="lqip"

lazy="dominant_color"

lazy="html5"

Usage Notes

Lazy-loading is only applied to <img> tags that are generated by JCOGS Image. If you ask JCOGS Image to output things other than complete <img> tags (e.g. url_only="yes" or output=) then the lazy= tag will be ignored.

Usage Notes

When active, Lazy loading requires that JCOGS Image generates an additional image low-resolution image - this additional processing will marginally increase the time the add-on requires to generate the image output. JCOGS Image will apply the same caching rules set for the processed image to the low-resolution image - so provided you have enabled image caching the long term impact of any additional processing will be minimal.

max

CE Image Compatibility: Full

Sets a maximum value for the width and height of the image after processing. 

The value should be specified either as a positive integer value with no units (px assumed), or as a positive integer value with either px or % as a suffix.

Syntax + Examples

max="<integer>[px|%]" - default value: 0

max="300px"

max="200"

max="30%"

Illustration

{exp:jcogs_img:image max="200" width="400" height="400" max_height="350" crop="yes"}

This tag will produce an image with dimensions 200x350.

The  max= parameter value over-rules the width= parameter value

The  max_height= parameter value over-rules the max= parameter value.

Usage Notes

Precedence

This parameter will over-rule any explicit setting for width= or height= in a tag.

This parameter will be over-ruled by any setting for max_width= or max_height= in a tag.

% values

If a % value is specified, JCOGS Image works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

max_height

CE Image Compatibility: Full

Sets a maximum value for the height of the image after processing. 

The value should be specified either as a positive integer value with no units (px assumed), or as a positive integer value with either px or % as a suffix.

Syntax + Examples

max_height="<integer value>[px|%] - Default: ‘’

max_height="220"

max_height="200px"

max_height="47%"

Illustration

{exp:jcogs_img:image height="270px" max_height="220"}

Limit the maximum height of the image to 220px.

The height= figure given is over-ruled by this parameter.  Since no other information is specified, the image is rescaled to give a height of 220px and the aspect ratio of the original image is maintained.

Usage Notes

Precedence

This parameter will over-rule any explicit setting for the height= or max= parameters in a tag.

% values

If a % value is specified, JCOGS Image works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

max_width

CE Image Compatibility: Full

Sets a maximum value for the width of the image after processing. 

The value should be specified either as a positive integer value with no units (px assumed), or as a positive integer value with either px or % as a suffix.

Syntax + Examples

max_width="<integer value>[px|%] - Default: ‘’

max_width="320"

max_width="280px"

max_width="66%"

Illustration

{exp:jcogs_img:image width='300' max_width='280px'}

Limit the maximum width of the image to 280px.

The width= figure given is over-ruled by this parameter.  Since no other information is specified, the image is rescaled to give a width of 280px and the aspect ratio of the original image is maintained.

Usage Notes

Precedence

This parameter will over-rule any explicit setting for the width= or max= parameters in a tag.

% values

If a % value is specified, JCOGS Image works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

min

CE Image Compatibility: Full

Sets a minimum value for the width and height of the image after processing. 

The value should be specified either as a positive integer value with no units (px assumed), or as a positive integer value with either px or % as a suffix.

Syntax + Examples

min="<integer>[px|%]" - default value: 0

min="300px"

min="200"

min="30%"

Illustration

{exp:jcogs_img:image min="250" width="200" height="200" min_height="230" crop="yes"}

This tag will produce an image with dimensions 250x230.

The  min= parameter value over-rules the width= parameter value

The  min_height= parameter value over-rules the min= parameter value.

Usage Notes

Precedence

This parameter will over-rule any explicit setting for width= or height= in a tag.

This parameter will be over-ruled by any setting for min_width= or min_height= in a tag.

% values

If a % value is specified, JCOGS Image works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

min_height

CE Image Compatibility: Full

Sets a minimum value for the height of the image after processing. 

The value should be specified either as a positive integer value with no units (px assumed), or as a positive integer value with either px or % as a suffix.

Syntax + Examples

min_height="<integer value>[px|%] - Default: ‘’

min_height="120"

min_height="150px"

min_height="25%"

Illustration

{exp:jcogs_img:image height="220px" min_height="250"}

Limit the minimum height of the image to 250px.

The height= figure given is over-ruled by this parameter.  Since no other information is specified, the image is rescaled to give a height of 250px and the aspect ratio of the original image is maintained.

Usage Notes

Precedence

This parameter will over-rule any explicit setting for the height= or min= parameters in a tag.

% values

If a % value is specified, JCOGS Image works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

min_width

CE Image Compatibility: Full

Sets a minimum value for the width of the image after processing. 

The value should be specified either as a positive integer value with no units (px assumed), or as a positive integer value with either px or % as a suffix.

Syntax + Examples

min_width="<integer value>[px|%] - Default: ‘’

min_width="120"

min_width="150px"

min_width="25%"

Illustration

{exp:jcogs_img:image width="220px" min_width="250"}

Limit the minimum width of the image to 250px.

The width= figure given is over-ruled by this parameter.  Since no other information is specified, the image is rescaled to give a width of 250px and the aspect ratio of the original image is maintained.

Usage Notes

Precedence

This parameter will over-rule any explicit setting for the width= or min= parameters in a tag.

% values

If a % value is specified, JCOGS Image works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

output

CE Image Compatibility: Full

Causes the output of a tag to be determined by a string entered into this parameter: any JCOGS Image Variables encountered are replaced by values derived from the source image and the manipulations specified for this tag by other parameters.

Syntax + Examples

output="<string containing text and JCOGS Image variables>" - Default: ‘’

output="The width of the image is {width} pixels, the height is {height} pixels."

output="{base_64}"

output="The name of the image is {name}"

Usage Notes

When this parameter is specified, the value of the create_tag= parameter is ignored. 

overwrite_cache

CE Image Compatibility: Full

When set to ‘yes’ this parameter causes JCOGS Image to regenerate the image from the source regardless of other cache settings.

Syntax + Examples

overwrite_cache="yes|no" - Default: no

overwrite_cache="no"

Usage Notes

Precedence

If set to yes this parameter over-rules any other cache settings in the tag or set in the JCOGS Image Control Panel Settings area. If set to no, other cache settings will be tested before a decision is made about whether to use a cached copy of an image.

quality

CE Image Compatibility: Full

When set, this parameter instructs JCOGS Image to save the processed image as with the specified quality level.

A quality value of 100 gives the highest quality output; lower quality values give lower quality output but usually the filesize of the images produced is also smaller.

The default value used by JCOGS Image is a quality level of 90.

Syntax + Examples

quality="<integer value between 0-100>" - Default: 90

quality="70"

Usage Notes

This parameter is ignored if the save_type= parameter is set to anything other than webp or jpg.

Usage Notes

For servers running php 8.1 or better setting the quality value to 100 causes webp format images to be saved in webp's lossless format.

reflection

CE Image Compatibility: Full

Adds a simulated reflection of the image below the main image.

The parameter accepts up to four sub-parameters to control aspects of how the reflection is created:

  • gap height: a vertical separation between the bottom of the image and the start of the reflection. Can be specified using any valid JCOGS Image dimension value; if a % value is specified it is evaluated relative to the height of the image being reflected. Default value: 0;
  • start opacity: the opacity of the reflected image at the top of the reflected image (i.e. ‘closest’ to the image being reflected). The value should be specified as an integer between 0 (fully transparent) and 100 (fully opaque). Default value: 80;
  • end opacity: the opacity of the reflected image at the bottom of the reflection (i.e. furthest away from the image being reflected). The value should be specified as an integer between 0 (fully transparent) and 100 (fully opaque). Default value: 0;
  • reflection height: The height of the reflected image.Can be specified using any valid JCOGS Image dimension value; if a % value is specified it is evaluated relative to the height of the image being reflected. Default value: 50%;

If the reflection is applied to an image that is saved in a format that supports transparency (e.g. webp, png) then the image background is set to be transparent.

If the reflection is applied to an image that is saved in a format that does not support transparency (e.g. jpg) then the background behind the reflection is coloured using the default background colour, or whatever colour is specified in the tag using the bg_color= parameter.

Syntax + Examples

reflection="<gap>[,<start opacity>[,<end opacity>[,<reflection height>]]]" - default 0,80,0,50%

reflection="0"

reflection="10,70,30,40%"

Illustration

{exp:jcogs_img:image width='300' reflection='0'}

Reflection using default parameters

Illustration

{exp:jcogs_img:image width='300' reflection='20px,70,10,60%'}

Reflection using all available parameters

rotate

CE Image Compatibility: Full

This parameter determines the amount of rotation to be applied to an image.

The rotation is specified using a single positive or negative integer value to represent the angle of rotation (in degrees) required. Rotation is measured from the horizontal, moving in an anti-clockwise direction.

As the picture rotates, the size of the containing rectangle enlarges to allow the rotated image to sit on the page without distortion, exposing some parts of this containing rectangle: the background colour of this containing rectangle is defined either by the background colour set for the tag - which can be set either within the tag using the bg_color= parameter - the default background colour set in the JCOGS Image Control Panel Settings area.

Syntax + Examples

rotate="<integer>" - Default: 0

rotate="75"

rotate="-120"

Illustration

{exp:jcogs_img:image width='300' rotate="30" bg_color="4a2d14"}

The image is rotated 30° from the horizontal. The background area exposed by the rotation is coloured #4a2d14.

Note that the size of the output image is larger than the dimensions specified in the tag parameters.

Usage Notes

Precedence

The rotation operation is applied after crop and resize operations, and after image flip operations.

rounded_corners

CE Image Compatibility: Partial

This parameter allows you to apply a radius based filter to one or more corners of an image, to give an image rounded corner(s) each with a separately defined radius. As with other filtering operations if you are saving an image in a format that supports transparency (i.e. webp, png) the area removed to create the corner will be transparent, otherwise the default background colour will be used.

Corners are identified via a short code:

  • tl - the top-left corner
  • tr - the top-right corner
  • bl - the bottom-left corner
  • br - the bottom-right corner
  • all - set all the corners to the same radius

If corner values are defined more than once in a parameter, the instance defined last in the string will be the one used.

The radius to use for the corner is specified using any valid JCOGS Image Dimension (i.e. integer, px, %)

Syntax

rounded_corners="[all|tl|tr|bl|br],<integer>[,<colour>]…" - default = null

rounded_corners="all,20"

rounded_corners="tl,20|br,40px|tr,25%"

Illustration

{exp:jcogs_img:image width='300' rounded_corners='all,30' save_type='webp'}

Apply a 30px radius to all four corners.

Illustration

{exp:jcogs_img:image width='300' rounded_corners='all,30' bg_color='rgb(250,76,5)' save_type='jpg'}

Apply a 30px radius to all four corners.

Image format specified does not support transparency, so background colour value used.

Illustration

{exp:jcogs_img:image width='300' rounded_corners="all,20px|br,30%" save_type="webp"}

Combine ‘all’ and ‘br’ values to set a different corner value in one corner

Illustration

{exp:jcogs_img:image width='300' rounded_corners="all,20px|br,30%" save_type="webp" border="10|rgb(250,176,5)"}

Borders can be applied to images with rounded corners.

Usage Notes

CE Image Compatibility Note: The CE Image facility to specify a different background colour for each corner is not supported. To specify a background colour to use where corners are being applied to a non-transparent image format, use the bg_color parameter to specify the same colour to use for all the corners defined.

save_type

CE Image Compatibility: Full

Determines the encoding format to be used by the processed image.

The format options available are determined by the abilities of the php image processing library used on the server running the EE instance. JCOGS Image actively monitors the available formats and only makes available formats that are supported: the formats available are listed in the JCOGS Image Control Panel settings page in the drop-down for ‘Default Image Format’ (which also ensures that the Default Image Format is always one that can be processed by the server!).

If you specify an image format in a JCOGS Image save_type that is not supported by the server, JCOGS Image will use the Default Image Format to encode the image instead, or will retain the format of source if a default is not specified.

For GD2 (the default library used by JCOGS Image) commonly available formats include:

extension

image format

bmp

Windows bitmap format

gif

Graphics Interchange Format

jpeg/jpg

JPEG image format

png

Portable Network Graphics 

webp

Webp 

For an image to be seen in a browser it is also important that the browser viewing the web page also supports the image format chosen. Where possible, when processing an image JCOGS Image actively checks that the current browser is able to display the format chosen; if the browser would not be able to display the image format chosen JCOGS Image substitutes a format that is supported both by the server and the browser (usually JPG).

The choice of which image formats to use when is a complex discussion area, and outside the scope of this manual to consider.

Syntax + Examples

save_type="bmp|gif|jpeg|jpg|png|webp" - Default: jpg

save_type="bmp"

save_type="webp"

Usage Notes

Transparency

Not all formats support transparency. Where possible transparency in images is preserved by JCOGS Image during processing, but it is also important to make sure that the processed image is saved in a format that also supports transparency: in particular if you are manipulating a PNG image with transparency and wish the processed image to retain this transparency, make sure you specify save_type="png" in your tag.

Not all filter operations preserve transparency.

When transparency is removed during a operation, the transparent pixes are replaced by pixels coloured according to whatever colour is chosen as the default background colour.

Usage Notes

Lossy vs Lossless

JCOGS Image always attempts to save images using the smallest file size option available for any given format. So for PNG and WebP images which support both lossy and lossless image storage formats, the images are saved using the lossy (compressed) format. 

When JCOGS Image is run on a server providing php 8.1, when a webp format image is saved with a quality value of 100 it will be saved in webp's lossless image format.

Usage Notes

Static Caching vs. Image Format Detection

JCOGS Image will actively attempt to ensure that your images are presented to a browser in a format that the browser can read. However for this active engagement to work, JCOGS Image has to be able to communicate with the browser. Due to how static caching works, JCOGS Image will not be able to make any adjustments to the images sent to a browser on pages that are in a static cache, and so you should be cautious about what image format you choose for pages that will be delivered in this way.

One option is to specify ‘safe’ formats (such as JPG, PNG, GIF) for your images - these formats have effectively universal support.

Another option is to code up your pages using the HTML <picture> tag - which lets you specify multiple formats for the same image, and the browser can then choose a version it can read from those offered.

 A future update to JCOGS Image will add in the ability to auto-generate <picture> tags for this purpose, but for now you will need to code up your own versions, making use of JCOGS Image variables to construct the tags to your liking.

Usage Notes

SVG Format

JCOGS Image currently provides limited support for SVG files. That support does not currently include the ability to convert images from or to the SVG format, and so if you specify svg as the save_type this value will be ignored and the default image format will be used instead.

src

CE Image Compatibility: Full

Defines the image that is to be used by the tag.

The image source can be any local file or be one obtained via a URL. 

Remote files are cached locally during processing but only the processed version of the image is cached.

The format options available are determined by the abilities of the php image processing library used: for GD2 (the default library used by JCOGS Image) the available formats are:

extension

image format

bmp

Windows bitmap format

gif

Graphics Interchange Format

jpeg/jpg

JPEG image format

png

Portable Network Graphics format

webp

Webp format

Later versions of JCOGS Image will support other graphics libraries, which if installed may give access to other image formats.

It is not important whether the source image file has an extension, or whether the given extension is correct - JCOGS Image validates each image before processing, a step that includes determining the actual image format being used.

Syntax + Examples

src="<any valid local image path>|<any valid remote image path>" - default value: null

src="/media/images/growling_tiger.jpg"

src="https://placekitten.com/400/300"

Illustration

{exp:jcogs_img:image src='media/a_word_from_our_sponsor.png'}

A tag using a local image source.

Illustration

{exp:jcogs_img:image src='https://placekitten.com/300/225'}

A tag using a remote image source.

Usage Notes

Remote Image Files

If a remote source image file is specified the source file will be downloaded to the local server before processing begins, which adds time to the total processing time for the template holding the JCOGS Image tag.

If a remote image is not obtained within a reasonable period, or if it is found to be unavailable, JCOGS Image will first attempt to use a fallback_src= image. If no fallback image is specified, or if that image too is unavailable, JCOGS Image will terminate processing of the tag.

The default caching setup for JCOGS Image enables the add-on to avoid the need to download or process the remote source image again in subsequent calls to the template: for site performance reasons you are strongly encouraged to retain these settings for remote image files (either by leaving the add-on with default settings, or adding cache= parameter to your tags with remote image sources).

srcset

CE Image Compatibility: New feature

Automatically add responsive variants of the processed image to an <img> tag via the srcset= and sizes= parameters of the HTML <img> tag.

Responsive image variants are helpful to reduce the amount of image data that is loaded by a visiting browser.  Within the HTML <img> tag:

  • the srcset= parameter allows you to identify several resolution variants of a source image;
  • the sizes= parameter allows you to define how the browser should preferentially download images from those specified in the srcset= parameter based on the rendered size of the image space that the the <img> tag is trying to fill.

Follow the link at the start of the preceding paragraph for a good introductory explanation of the principles involved.

The srcset= parameter, as used within JCOGS Image, simply takes a series of width specifications (in any dimension format understood by JCOGS Image) separated by the | pipe character. 

Note: The values given should be in order of increasing size, and be less than the width of the processed image - values in the sequence that fail these tests will be ignored

In response, JCOGS Image will create a version of the processed image scaled (i.e. maintaining the aspect ratio of the processed image) to the each of the valid widths specified, and assemble a valid HTML <img> srcset= parameter to reference these images.

Concurrently JCOGS Image will build content for the sizes= parameter a simple rule that instructs the browser to load the first responsive variant that is greater than or equal to the real width of the image space being filled - see the illustration below for more details. If you want to define a more complicated sizes= parameter, do so and add it to your JCOGS Image tag along with your srcset= parameter, and this will be prefixed to the automatically generated sizes= definition in the HTML template code produced.  Since the HTML sizes= parameters are evaluate in the order they are provided, and evaluation stops after the first rule encountered for whose conditions are met, this approach ensures that any custom sizes= rules will take priority over the default rules generated by JCOGS Image.

Syntax

srcset="<integer>[px|%][|<integer>[px|%]] … repeat … " - default value: null

srcset="350|450|700"

srcset="280px|50%|771|800px"

Illustration

{exp:jcogs_img:image width='550' srcset='250|50%|300px|400'}

The example parameters will produce an HTML <img> tag with the following content: 


<img src="image.webp" srcset="image_250w.webp 250w, image_300w.webp 300w, image_349w.webp" sizes="(max-width:250px) 250w, (max-width:300px) 300w, 349w ">

JCOGS Image has created an entry in the srcset= parameter within the <img> tag for each of the size options included in the parameter within the JCOGS Image tag, and a simple default sizes= parameter.

Usage Notes

Note about the pixel density version of srcset

The HTML specification for srcset within an img tag describes two ways to specify alternative images. One using width descriptors and one using pixel density descriptors. It also notes that you cannot combine both width and pixel density descriptors in the same tag.

Pixel density descriptors can be easily simulated using width descriptors. Accordingly when generating its output JCOGS Image chooses to only support width descriptors.

Usage Notes

Choosing the right approach for responsive images within your site is a complex process. To get the best results you are recommended to consult one of the many good introductory explanations of the principles involved that are available.

svg_height

CE Image Compatibility: New feature

Sets the default height to use when processing an SVG file that does not include such height information. 

The value can be given as an integer number (of pixels) with or without a trailing px suffix.

If the source SVG image contains height information that value will be used to set the original height value for the image.

If the source SVG image contains aspect ratio information, the original height value will be estimated by multplying the original width by the aspect ratio.

If no information about height or aspect ratio is provided this value will be used as. 

This parameter will over-rides the default value set for the tag during the processing of the image tag it relates to.

Syntax + Examples

svg_width="<integer value>" - Default: 150

svg_passthrough="400"

Usage Notes

Operations within JCOGS Image sometimes need to know the height of the original image. Not all SVG image files contain this information. Some do, others contain just an aspect ratio and some contain no information at all. As a result any processing of an SVG file needs to have some default width / height to work with.

Usage Notes

This parameter will only have effect if SVG Passthrough operation is enabled.

svg_passthrough

CE Image Compatibility: New feature

Determines whether SVG format image sources are processed or ignored.

When this option is enabled, JCOGS Image will generate an output file based from a source SVG file - the svg file itself is simply copied from the source to the JCOGS Image cache directory, but some of the requested parameters are acted upon. This behaviour is designed primarily to allow SVG images to be included in media collections, such that if they are included as source files Image generates some output rather than the previous behaviour (and still the default) of producing of none.

For a more complete discussion of JCOGS Image's support for SVG image format, there is an Advanced Topic entry about this.

Syntax + Examples

svg_passthrough="yes|no" - Default: no

svg_passthrough="yes"

svg_passthrough="no"

Usage Notes

Recommendation: It is highy recommended that an image dimension (e.g. width or height parameter or similar) is included in the JCOGS Image template tag used to trigger processing: doing so will put a limit on the size of the SVG rendered in your template output. Without such limitation the SVG will be scaled to the dimensions specified in the SVG itself (if such are specified).

Usage Notes

JCOGS Image's ability to process SVG images is limited: this limitation primarily is a reflection of the wider absence of SVG tools within the php language environment.

Currently the parameters acted upon are limited to those related to image size (e.g. width, height, max, min, aspect ratio etc) and image caching (cache duration, cache location). 

Over time the range of parameters supported will be expanded as the capabilities of available php tools expands.

svg_width

CE Image Compatibility: New feature

Sets the default width to use when processing an SVG file that does not include such width information. 

The value can be given as an integer number (of pixels) with or without a trailing px suffix.

If the source SVG image contains width information that value will be used to set the original width value for the image, otherwise this value will be used as the default width (in px). This parameter will over-rides the default value set for the tag during the processing of the image tag it relates to.

Syntax + Examples

svg_width="<integer value>" - Default: 350

svg_passthrough="400"

Usage Notes

Operations within JCOGS Image sometimes need to know the width of the original image. Not all SVG image files contain this information. Some do, others contain just an aspect ratio (but no base width) and some contain no information at all. As a result any processing of an SVG file needs to have some default width / height to work with.

Usage Notes

This parameter will only have effect if SVG Passthrough operation is enabled.

text

CE Image Compatibility: Full

Overlays text on an image. 

This parameter gives options to control font, colour, size, position of the text relative to the background image, and whether to add a shadow to the text. Text added is is word-wrapped within either the containing box of the image, or within a narrower box if a width adjustment is specified.

There is much information needed to define what text to overlay on the image, and so the parameter string for this is necessarily complex, containing up to 16 elements (two more than in the CE Image equivalent); however only one is mandatory (the text to overlay).  The elements should be separated by the pipe character (|) and are (in the order they need to be included in the parameter):

  • the text to add - any string of characters and spaces enclosed.  If the text is directly entered it cannot include any pipe ('|') characters (as this gets confused with the element separator), but these characters can be included if the text added as an EE variable.
  • minimum width / height - can set the minimum size the target image has to have for the text to be added - if omitted or set to zero text will always be added. Values can be any valid JCOGS Image dimension: if a % value is specified it will be calculated based on the width of the processed image. If omitted, both values default to zero.
  • font_size - the size of the font to use. Can be specified in terms of pixels or points (add pt sufix to number). If omitted the value defaults to 12px.
  • line_height - the height of the line to use - controls the vertical spacing of text. Can be specified using any valid JCOGS Image dimension (so integer, px, %): if a % specified, it is converted to a pixel value relative to the font size specified. If omitted the default value is 1.25 (so a default line height of 15px).
  • font_color - the colour to use for the text added. Can be specified using any valid JCOGS Image colour format (so any hex-code, or rgb() or rgba()). If omitted the value defaults to white.
  • font_src - the path to the font file that you want to use for the text added. The font file should be a true-type font file (ttf). If omitted the value defaults to Voces Regular.
  • text_align - determines how the text will be aligned within the text-box area. Options are left, center and right. If omitted the value defaults to center.
  • width_adjustment - allows you to specify a width-adjustment for the box that encloses the overlayed text. Can be specified using any valid JCOGS Image dimension (integer, integer+px, %). Positve values are read as the width that you want the text box to have (so 40% would indicate a width for the text equal to 40% of the width of the processed image). Negative values are read as the reduction in size from the width of the processed image - (so -40% would indicate a width for the text equal to 60% of the width of the processed image).  % values are translated based on the width of the processed image. Values that define a width greater than that of the processed image will be ignored.
  • position - set the horizontal and vertical position for the text box within the image box. Options for horizontal are left, center, right.  Options for vertical are top, center, bottom. If omitted these values default to center.
  • offset - set a horizontal and vertical offset from the general position specified for the location of the text-box.  Values can be entered using any valid JCOGS Image dimension format, if a % value is specified it will be calculated relative to the width of the processed image. So an offset of -20px,10% would cause the text box to be moved left by 20px, and up by 10% of the width of the image from the location defined by the position parameter. If omitted the values default to zero.
  • opacity - set the opacity for the text to be added. Value must be an integer between 0 (transparent) and 100 (opaque). This value will over-rule by any opacity set in the font_color parameter. If opacity is omitted and no font_color opacity is specified the value defaults to 100, otherwise the font_color opacity specified is used.
  • shadow_color - set an colour for a shadow to be placed behind the text added. Can be specified using any valid JCOGS Image colour format (so any hex-code, or rgb() or rgba()). If omitted the value defaults to transparent.
  • shadow_offset - sets a horizontal and vertical offset for any text shadow. Specified as a pixel offset from the text using any valid JCOGS Image dimension format (if a % is specified, it is translated into pixels using the width of the processed image as the base value). So a value of 2,1 translates to a horizontal offset of 2 pixels, and a vertical offset of 1 pixel. If this value is omitted, the values each default to 1 pixel.
  • shadow_opacity - sets the opacity of the shadow colour. Value must be an integer between 0 (transparent) and 100 (opaque).. This value will over-rule by any opacity set in the shadow_color parameter. If opacity is omitted and no shadow_color opacity is specified the value defaults to 100, otherwise the shadow_color opacity specified is used.
  • text_box_bg_color - sets a background colour for the box containing the overlaid text. Can be specified using any valid JCOGS Image colour format (so any hex-code, or rgb() or rgba()). If omitted the value defaults to transparent.
  • text_bg_color - sets a background colour for the overlaid text. Can be specified using any valid JCOGS Image colour format (so any hex-code, or rgb() or rgba()). If omitted the value defaults to transparent.
  • rotation - sets a rotation for the box containing the overlaid text. An integer value defining number of degrees to rotate text box by; positive values translate to anti-clockwise rotation. If omitted the value defaults to no rotation.

Syntax

text="<the text to add>[|min_width,[min_height[|​font_size[|​line_height[|​font_color[|​font_src[|​text_align[|​width_adjustment[|position_horizontal[,position_vertical[|​offset_horizonta[,offset_vertical[|​opacity[|​shadow_color[|​shadow_offset_x,[shadow_offset_y[|​shadow_opacity[|text_box_bg_color[|text_bg_color[|rotation]]]]]]]]]]]]]]]]]]]]"

text = “Some text”

text = "Some different text|0,0|20px|125%|#0280c2||center|70%|center,center|-50,-50|100|#eded03|2,2|60|rgba(100,100,30,0.2)|rgba(100,100,30,0.3)"

text = "Some rotated text|0,0|20px|125%|#0280c2||center|70%|center,center|-50,-50|100|#eded03|2,2|60|rgba(100,100,30,0.2)|rgba(100,100,30,0.3)||45"

Illustration

{exp:jcogs_img:image text = 'Sometimes text is worth adding to a picture|0,0|20px|125%|rgba(224, 225, 220, 1.0)||center|40%|right,top|0,0|100|#dcdcdc|1,1|60|rgba(100,100,30,0.3)' width='550'}

This tag will add a text box containing some text in colour rgba(224, 225, 220, 1.0) centered over a picture and then offset by -50px in horizontal and vertical directions. The text will use the default at 20px size, with line height of 25px within a text box with a background colour of rgba(100,100,30,0.3) limited in width to 40% of the width of the processed image it overlays.  The text will have a #dcdcdc colour shadow offset by 1px vertically and horizontally. 

Illustration

{exp:jcogs_img:image text = 'Feature!|0,0|45px|125%|#FFF|fonts/Lobster-Regular.ttf|center|60%|left,top|-60,-60|100|#000|1,1|60|rgba(205, 127, 131, 1.0)||45' width='550'}

This tag uses the font, rotation and text-offset sub-parameters to add a promotional flash to an image.

The text font is Lobster Regular a True Type font.

Usage Notes

To add more than one text block to an image (e.g. to allow for use of different font sizes / colours / fonts) you will need to nest one JCOGS Image call within another, adding text one block at a time in each call.  See separate notes on how to nest JCOGS Image tags within the Advanced Topics section of this documentation.

url_only

CE Image Compatibility: Full

If this parameter is set to yes then the source image will be processed according to the parameters set within the tag and the only output will be a URL pointing to the processed image on the host server.

Syntax + Examples

url_only="yes|no" - Default: no

url_only="yes"

url_only="no"

Usage Notes

This is one of the several ways in which JCOGS Image can be instructed to provide just a URL to the processed image.

use_image_path_prefix

CE Image Compatibility: New feature

Instructs Image to apply any image path prefix given (either as a parameter or as a default value in the Default Settings section of the Add-on Control Panel area.

Syntax

use_image_path_prefix="[yes|no]"

use_image_path_prefix="yes"

use_image_path_prefix="no"

watermark

CE Image Compatibility: Full

Overlay a watermark on an image.

This parameter allows you to specify a second image that is then overlaid on top of the primary source image, adjusting the relatively position and opacity of the image to be overlaid. It is also possible to specify for a watermark image to be repeated with a definable offset.

There is much information needed to define how to execute this requirement, and so the parameter string for it is necessarily complex. The elements that make up this parameter should be separated by the pipe character (|) and are (in the order they need to be included in the parameter): 

  • watermark_src - the image source to be used for the watermark. Can be any valid JCOGS Image source (local or remote).
  • minimum_dimensions - sets the minimum size the target image has to be for the watermark to be added - if omitted or set to zero the watermark will always be added. Values can be any valid JCOGS Image dimension: if a % value is specified it will be calculated based on the width of the processed image. If omitted, both values default to zero.
  • opacity - the opacity for the image to be overlaid. Value must be an integer between 0 (transparent) and 100 (opaque). If omitted or an invalid value supplied, the value defaults to 100.
  • position - set the horizontal and vertical position for the watermark within the image frame. Options for horizontal are left, center, right.  Options for vertical are top, center, bottom. If omitted these values default to center
    It is also possible to specify the horizontal position as repeat which triggers the generation of multiple instances of the watermark.
    If repeat is specified, it can optionally be followed by one or two dimension parameters which if specified set the spacing between repeated watermarks.  Any valid JCOGS Image dimension value can be used; if a % value is specified it will be calculated relative to the width or height of the watermark image. If values for the repeat offset are not specified, the horizontal offset defaults to 50% of the width of the watermark, the vertical offset to 0.
  • offset - set a horizontal and vertical offset from the position specified for the location of the watermark.  Values can be entered using any valid JCOGS Image dimension format, if a % value is specified it will be calculated relative to the width of the processed image. So an offset of -20px,10% would cause the watermark to be moved left by 20px, and up by 10% of the width of the image from the location defined by the position parameter. If omitted the values default to zero. In the case where horizontal position is specified to be repeat, the offset values are applied to the starting point of the first image in the repeat sequence.
  • rotation - rotate the watermark image by an integer number of degrees. Rotation direction is anti-clockwise.

Syntax

watermark='watermark_src [|min_width,min_height [|opacity [|position_horizontal,position_vertical [|offset_x,offset_y [|rotation]]]]]

watermark="image.png|0,0|100|left,top|0,0"

watermark="image.png|0,0|50|right,bottom|-10,-10"

watermark="image.png|0,0|100|repeat,30,20|20px,20px|45"

Illustration

{exp:jcogs_img:image watermark="/media/a_word_from_our_sponsor.png|0,0|50|right,bottom|0,0" width="550"}

Add a single watermark to an image.

Illustration

{exp:jcogs_img:image watermark="/media/a_word_from_our_sponsor.png|0,0|50|right,bottom|0,0|45" width="550"}

Add a single watermark to an image with watermark image rotated by 45°

Illustration

{exp:jcogs_img:image watermark="/media/a_word_from_our_sponsor.png|0,0|50|repeat,30,20|0,0|none" width="550"}

Add a repeated watermark to an image.

Usage Notes

The best watermarks have a transparent background - which can be achieved by specifying an image with either webp, png or gif format - so the background image is clearly visible around the watermark.

However a watermark can be an image of any valid JCOGS Image format, and opacity is applied to that image when overlaid even if the watermark source image is not one that supports transparency.

Usage Notes

CE Image Compatibility Note: The CE Image second sub-parameter for watermark repeat is defined as a single value and interpreted as a percentage of the width of the watermark image. So the element repeat,10 is translated as “repeat the watermark, offset the horizontal position by 10% of the watermark width on each subsequent row”.

JCOGS Image's implementation is more flexible - you can set the repeat offset in both horizontal and vertical dimensions using any valid JCOGS Image dimension format.

However, if to maintain CE Image compatibility, if only one dimension is specified for repeat and this value has no units (e.g. repeat,10) then this value will be evaluated as a percentage in a similar way to CE Image. However, if units are specified (e.g. repeat,10px or repeat,10%) or two dimensions are specified (e.g. repeat,10,20) then the value will be processed as a standard JCOGS Image Dimension.

Usage Notes

The final sub-parameter for the watermark parameter is used to specify watermark rotation. When the same sub-parameter is set to the value multiply it is used by CE Image to define a special watermark blending mode. The blending mode feature is not implemented in JCOGS Image, and this sub-parameter will be ignored by it when the value is set to multiply

Usage Notes

The CE Image equivalent parameter specifies a responsive variant - the ‘watermark waterfall’ approach - which allows for multiple versions of a watermark to be specified matched to changes in the ‘minimum_dimension' element. This method has not been implemented by JCOGS Image. If you need this, we recommend you create a <picture> HTML element and specify multiple watermarked images matched to conventional media queries there.

width

CE Image Compatibility: Full

Sets the width of the image to be produced.  The value can be given as an integer number (of pixels) with or without a trailing px suffix, or as a percentage value (an integer with a trailing %). If a percentage is specified, it is converted into a pixel value by multiplying the percentage value by the original image height.

If the value is not specified, JCOGS Image will try to impute a value for width from other parameters specified.

Syntax + Examples

width="<integer value>[px|%]" - Default value = “”

width="200px"

width="180"

width="33%"

Illustration

{exp:jcogs_img:image width='300'}

Set the width of the image to 300px.

Since no other information is given, JCOGS Image will scale the image in proportion to its original dimensions to give the height requested.

Usage Notes

Precedence

This parameter will be potentially over-ruled by any explicit settings for  min_width= or max_width= or min= or max= in a tag.

% values

If a % value is specified, JCOGS Image works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image.