image

Wrapper for the generation of <img> HTML tags.

Summary

[image src]

Parameter	Description	Default
src	Image file to use.	None
alt	Alternate text for the image file.	See parameter description
check_date	Rebuild the resized image file (see makesize) if it is out of date.	No
default	Default image.	See parameter description
descriptionfields	Column(s) in the DefaultTables table(s) that contain a description.	See parameter description
dir_only	Return the name of the current image directory.	No
exists_only	Return 1 if the image file exists.	No
extra	Extra attributes for the HTML <img> tag.	None
force	Skip any checks on image file's existence.	No
getsize	Determine the image size automatically.	No
imagefields	Column(s) in the DefaultTables table(s) that could contain an image filename or URI.	See parameter description
imagesubdir	Subdirectory to be searched for the image.	No
makesize	Produce a resized image file that matches the given geometry.	None
geometry	Alias for makesize.	No
resize	Alias for makesize.	No
secure	Force the use of the secure or ordinary image directory.	None
size_scratch_prefix	Save image size, determined using getsize into scratchpad variables.
sku	Specify a value that should be used to look up the alt text in the DefaultTables table(s).	None
src_only	Only return the path and filename for the image.	No
title	Text to use with the <img> HTML tag's "title" attribute.	See the alt parameter
ui	Look for the named image file in UI_IMAGE_DIR or UI_IMAGE_DIR_SECURE.	No
border, height, width, hspace, vspace and align	Ordinary HTML attributes for the resulting HTML tag.	None

Examples

Tag expansion example

[image src="foo"]

Perl example

$Tag->image({
src => $src,
});

or similarly with positional parameters:

$Tag->image($src, $attribute_hash_reference);

Description

This is a general-purpose tag for inserting <img> HTML tags, based upon various settings, with the ability to do the following and more:

Test whether an image exists.
Predetermine its pixel dimensions.
Retrieve the image name from a table in the DefaultTables list.
Automatically pull descriptions from a table in the DefaultTables list for use in the <img> tag's "alt" and "title" attributes.

A convenient use is for displaying product images on an ecommerce website. For example, on the flypage:

[image src="[item-code]"]

Assuming that the SKU is "ABC123, and assuming the DefaultTables table specifies "ABC123.gif" in its "image" column for the "ABC123" row, this tag will return HTML code along the lines of the following:

If there is no ABC123.gif, or the DefaultTables table's "image" column for the "ABC123" row was empty, this tag would check for files called "ABC123.jpg and this tag check for files called "ABC123.jpg" and "ABC123.png" etc.

You can also specify a particular image filename, but also use the sku parameter to look up the description in the database, as follows:

[image src="/images/foobar.jpg" sku="[item-code]"]

You can force the use of an image filename even if the file doesn't exist (if it's on a different server, for example). Absolute URIs beginning with "http://" or "https://" are always accepted without checking, of course, and the force parameter can be used to avoid all such checks on local files.

One peculiar use is with the dir_only parameter to return the correct prefix for images (HTTP or HTTPS/SSL), primarily for adding to image names used in JavaScript code and elsewhere.

Parameters

src

This parameter is used to specify the location of the image.

If the value starts with "http://" or "https://" then it will be used as-is, otherwise it will be assumed to be an image file, on the local filesystem.

If this parameter starts with a "/" then it will be used verbatim in the resulting HTML <img> tag. The path used for existance and getsize checks etc. will be relative from the website's home directory, as specified using the Catalog global configuration directive.

If this parameter does not start with a "/" then the value of either the ImageDir or the ImageDirSecure local configuration directive will be prepended, depending upon whether or not the current page was requested via a HTTPS/SSL link. Also see the ui parameter, which can be used to change the image directory used by this tag, and also the imagesubdir parameter.

If the named local file cannot be found then the ".jpg", ".gif", ".png" and ".jpeg" suffixes will be appended to the file, in turn, in an attempt to find the image,

If the image cannot be found on the local filesystem then the src value will be looked up in the DefaultTables table(s). If it still can't be found then the sku parameter's value will be looked up in the DefaultTables table(s).

If no image file can be found then the default value will be used instead.

alt

Alternate text for the browser to show if the image can't be displayed, for whatever reason.

If no alt parameter is provided, and the src parameter's value does not start with "http://" or "https://", then the src will be looked up in the DefaultTables table(s). If a row is found then the columns named in the descriptionfields parameter will be searched for a value instead.

Also see the sku parameter's description.

check_date

This parameter is designed to be used in combination with the makesize parameter. if set true then this tag will check the image file's modification time. If the resized image is found to be out of date then it will be rebuilt before being served.

default

Image filename, or URI, that will be used if no image file that matches the src value can be found.

If no default parameter is specified then the [scratch mv_imagedefault] value will be used, if set.

descriptionfields

Whitespace-separated list of columns in the DefaultTables table(s) to be scanned for a default alternate text value.

If this parameter is not provided then the DESCRIPTIONFIELDS Variable will be used. If that Variable is not set then the value of the DescriptionField local configuration directive will be used. The ultimate default value is "description".

dir_only

If this parameter is set true then this tag will simply return the value of either the ImageDir or the ImageDirSecure local configuration directive, depending upon whether or not the current page was requested via a HTTPS/SSL link. Also see the ui parameter, which can be used to change the image directory used by this tag.

exists_only

If this parameter is set true then this tag will return 1 if the named image file exists.

extra

Extra attributes to be passed verbatim to the resulting HTML <img> tag.

force

Skip any checks on image file's existence.

getsize

If this parameter is set true, and the

Image::Size Perl module is installed, then this tag will use it to determine the image's height and width, so that they can be added to the resulting HTML <img> tag without having to be specified.

This parameter will override the values specified using the height and width parameters.

Warning

If you call this tag from local embedded Perl then you will not be able to use this parameter without also untrapping the "require" opcode. See the SafeUntrap global configuration directive.

This parameter will be ignored if the src parameter refers to an external URI.

Also see the size_scratch_prefix parameter.

imagefields

Whitespace-separated list of columns in the DefaultTables table(s) to be scanned for an image filename or URI.

If this parameter is not provided then the IMAGEFIELDS Variable will be used. The default value is "image".

Availability

This parameter was introduced in version 5.5.0, and is therefore not available for use with any earlier Interchange version.

imagesubdir

Look for the image file in the named subdirectory of the ImageDir (or ImageDirSecure) directory.

makesize

If ImageMagick is installed then you can request an arbitrary size for your image. This tag will either create the resized image as a new file, in a subdirectory corresponding to the selected size (such as "100x100"), or will reuse an existing resized image file. If the checksize parameter is set true then pre-resized images may be rebuilt to reflect changes to the original.

This parameter's value is expected to be specified as "WIDTHxHEIGHT" or "xHEIGHT", which can optionally be followed by up to two offset specifications, the first for the X offset, and the second for the Y offset, as follows:

Specification	Description
+xoffset	The left edge of the object is to be placed xoffset pixels in from the left edge of the image.
-xoffset	The left edge of the object is to be placed outside the image, xoffset pixels out from the left edge of the image.
+yoffset	The top edge of the object is to be yoffset pixels below the top edge of the image.
-yoffset	The top edge of the object is to be yoffset pixels above the top edge of the image.

In addition to the standard X Window System's geometry specification syntax, the following qualifier tokens are accepted at the end of the parameter.

Qualifier	Description
%	Interpret width and height as a percentage of the original size.
!	Resize to width and height exactly, loosing original aspect ratio.
<	Resize only if the image is smaller than the geometry specification.
>	Resize only if the image is greater than the geometry specification.

This tag resizes images by copying the original into a size-named subdirectory and then running ImageMagick's "mogrify" command.

Note

The "mogrify" command must be present in one of the directories listed in the Interchange user's ${PATH} environment variable, or in the location specified by the "IMAGE_MOGRIFY" global (not local) Variable.

secure

Passing "0" to this parameter will force this tag to act as if the page request was made over a HTTP link. Either the ImageDir local configuration directive, or the UI_IMAGE_DIR variable will be used as the default image directory.

Passing "1" to this parameter will force this tag to act as if the page request was made over a HTTPS/SSL link. Either the ImageDirSecure local configuration directive, or the UI_IMAGE_DIR_SECURE variable will be used as the default image directory.

If this parameter is not specified at all then the [image] tag will work out for itself whether a HTTP or HTTPS/SSL link is in use.

size_scratch_prefix

If getsize is true and this parameter has a value, then the determined image size will be saved into scratchpad variables.

For example, if this parameter is set to "foobar" then two scratchpad variables will be created, named "foobar_width" and "foobar_height", each with a corresponding image size value.

sku

This parameter allows you to specify a value that should be used to look up the alt text in the DefaultTables table(s), instead of using the src value for this purpose.

If no src parameter is supplied, or the supplied src parameter doesn't point to an existing file, then the sku will also be used to try to find an image in the DefaultTables table(s).

If the provided sku doesn't yield a row in the DefaultTables table(s), then the src parameter's value will be tried.

src_only

If this parameter is set true then this tag will return the image path and filename, exactly as it would have been used in the <img> HTML tag's src attribute.

title

Text to use with the <img> HTML tag's "title" attribute. If this parameter is not specified then the value of the alt parameter, or that parameter's calculated default, will be used.

ui

If this parameter is set true then this tag will use the UI_IMAGE_DIR and UI_IMAGE_DIR_SECURE variables instead of the ImageDir the ImageDirSecure local configuration directives to determine the image directory.