Custom variables custom-variables

The query portion of requests and vignette::Modifier strings may include user-defined variables.

$ name = value

name - Variable name. May consist of any combination of alpha, digit, and safe characters, excluding $.

value - Value to which the variable is to be set (string).

Variables are defined similar to other server commands, using the above syntax. Variables must be defined before they can be referenced. Variables which are defined in vignette::Modifier can be referenced in the URL request, and conversely.

value must be single-pass URL-encoded for safe HTTP transmission. Double encoding is required if value is retransmitted by way of HTTP. This situation is the case when value is substituted into a nested foreign request.

Variables are referenced by embedding the variable name (enclosed by a leading and a trailing $) anywhere in command values. For example, between the = following the command name and the subsequent & or the end of the request. The server substitutes each such occurrence of $ name$ with string. No substitutions happen on any occurrences of $ name$ in command names (before the equal sign of a command), and in the path portion of the request.

Custom variables may not be nested. Any occurrences of $ name$ within string are not substituted. For example, the request fragment $var2=apple&$var1=my$var2$tree&text=$var1$ resolves to text=my$var2$tree.

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