Substitution variables

Last update: November 3, 2023

CREATED FOR:

  • Developer
  • User

Substitution variables are used to transfer values from the request URL to compositing templates stored in image catalogs. Variables can also be used to convey the same value to different places in a complex request.

$ *var*= *value*

varVariable name.
valueValue to which the variable is to be set (string).

Variable definitions and references may occur in the query portion of the request, in catalog::Modifier, and in catalog::PostModifier.

Variables are defined as above, similar to other IS commands; the leading ‘$’ identifies the command as a variable definition. Variables must be defined before they are referenced.

The variable name var is not case-sensitive and may consist of any combination of ASCII letters, numbers, ‘-’, ‘_’, and ‘.’.

NOTE
value must be single-pass URL-encoded for safe HTTP transmission. Double-encoding is required if value is retransmitted by way of HTTP. This is the case when value is substituted into a nested foreign request or into the href attribute of an SVG <image> element.

Variable references consist of the variable name delimited by leading and trailing ‘$’ ($var$). References may occur anywhere in the value portion of any IS commands (that is, between the ‘=’ following the command name and the subsequent ‘&’ or the end of the request). Custom variables cannot be applied to the layer= and effect= commands. Multiple variables are permitted in the same command value. The server substitutes each occurrence of $ *var*$ with value.

Variable references may not be nested. Any occurrences of $ *var*$ within value are not substituted.

For example, the request fragment:

$var2=apple&$var1=my$var2$tree&text=$var1$

resolves to:

text=my$var2$tree

NOTE
‘$’ is not a reserved character; it may occur otherwise in the request. For example, src=my$image$file.tif is a valid command (assuming that a catalog entry or image file named my$image$file.tif exists), while wid=$number$ is not, because wid requires a numeric argument.

Variable processing in nested requests

$ *var*$ references may occur anywhere within the curly braces of a nested Image Serving or Image Rendering request, including to the left of the ‘?’ separating the path from the query. The server substitutes these references with values (either from the url or from catalog::Modifier of the main image catalog) before further parsing and processing of the nested request.

In addition, all $ *var*= definitions from the url or catalog::Modifier are forwarded to all nested Image Serving and Image Rendering requests. This ensures that all variable definitions are available to all templates, regardless of nesting level.

Regardless of the nesting level, only single-pass HTTP-encoding must be applied to variable values which are to be substituted anywhere in nested Image Rendering or Image Serving requests or their associated catalog::Modifier strings.

Variable processing in embedded foreign requests

$ *var*$ references occurring anywhere within the curly braces of an embedded foreign request are substituted with matching variable definition values. This allows embedded foreign requests to be placed in a template in an image catalog.

Variable values which are to be substituted into foreign requests typically must be double-encoded, since no re-encoding is applied before the server attempts to transmit the final foreign url.

Variable processing in SVG files

$ *var*$ references may occur in SVG files in attribute values and in <text> strings. Image Serving substitutes these with the matching $ *var*= definitions known at the request nesting level at which the SVG file is specified.

NOTE
Any variable value which is to be substituted into an href attribute value must be double URL-encoded; all others must be singly encoded.

Pre-defined path variable

The object specified in the request path is assigned to the pre-defined variable *$object*. ’ $ *object*$’ may be placed anywhere in the request, in the template referenced by the request, or in a nested/embedded request where such object is permitted, including the value of src= and mask=, and the path of a nested/embedded request.

For example, the following request reuses the image specified in the path as the source of a layer in a nested request:

/is/image/a/b?…&layer=3&src=is{…&src=$object$}&…

This is equivalent to

/is/image/a/b?…&layer=3&src=is{…&src=a/b}&…

The definition of *$object* can be overridden by explicitly specifying $ *object*= with the desired value.

The predefined path variable is commonly used in conjunction with template=.

Default

None. Only variables which have been defined are substituted by the server (except the pre-defined path variable $object, which is always substituted). Any occurrences of $ *var*$ remain literal if *var*cannot be matched with an existing variable definition.