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.
Value 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
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 ‘.’.
value must be single-pass URL-encoded for safe HTTP transmission. Double-encoding is required if
value is retransmitted via HTTP. This is the case when
value is substituted into a nested foreign request or into the href attribute of an SVG
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 (i.e. between the ‘=’ following the command name and the subsequent ‘&’ or the end of the request). Custom variables cannot be applied to the
effect= commands. Multiple variables are permitted in the same command value. The server substitutes each occurrence of
Variable references may not be nested. Any occurrences of
value are not substituted.
For example, the request fragment:
‘$’ 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.
*$ 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
*= 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
*$ 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.
*$ references may occur in SVG files in attribute values and in
<text> strings. Image Serving substitutes these with the matching
*= definitions known at the request nesting level at which the SVG file is specified.
Any variable value which is to be substituted into an
href attribute value must be double URL-encoded; all others must be singly encoded.
object specified in the request path is assigned to the pre-defined variable
*$’ 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
mask=, and the path of a nested/embedded request.
For example, the following request will reuse the image specified in the path as the source of a layer in a nested request:
This is equivalent to
The definition of
* can be overridden by explicitly specifying
*= with the desired value.
The predefined path variable is commonly used in conjunction with
None. Only variables which have been defined will be substituted by the server (except the pre-defined path variable $object, which will always be substituted). Any occurrences of
*$ remain literal if
*cannot be matched with an existing variable definition.
See “Example A” in Templates.