The String expression syntax
String expressions are used to create string values dynamically, using a syntax that is not dissimilar in principle to C# interpolated strings. It allows the creation of a string value using placeholders where dynamic values may be inserted using a path expression.
The syntax of a string expression is:
string:A string here using zero or more $placeholders
String expressions are included in the main ZptSharp package
Support for string
expressions is included in the main ZptSharp NuGet package.
Additionally, string
expressions are one of the standard expression types activated by AddStandardZptExpressions()
.
How to use placeholders
A placeholder always begins with a single dollar character $
, after which is a TALES path expression (and a path expression only) which provides the value to be inserted into the placeholder.
If the TALES expression does not evaluate to a string then it will be converted to one via Object.ToString()
unless it is null, which is interpreted as an empty string.
The expression may follow directly after the dollar character, for example $myVariable
or it may be wrapped in braces, for example ${myVariable}
.
Braces or no braces?
Whether or not braces are used impacts which characters are permitted for use in the expression. Without braces, expressions that are used in a string placeholder may only use a limited set of characters. The table below shows which characters are permitted in each scenario. If you wish to use any of the characters which are disallowed without braces, then your expression must be enclosed in braces.
Character(s) | Without braces | With braces |
---|---|---|
Alphabetic (upper & lower case) | Yes | Yes |
Numeric | Yes | Yes |
Underscore: _ |
Yes | Yes |
Forward-slash: / |
Yes | Yes |
Space | No | Yes |
Period: . |
No | Yes |
Comma: , |
No | Yes |
Tilde: ~ |
No | Yes |
Pipe (aka "Vertical bar"): \| |
No | Yes |
Question mark: ? |
No | Yes |
Hyphen-minus: - |
No | Yes |
Escaping dollar characters
If you wish your string to include a literal dollar character, it must be escaped by doubling-it up: $$
.
You must manually encode markup-reserved characters
Because string expressions are used exclusively in DOM attributes, this means that expressions must also follow the rules for the underlying markup. For example TALES itself would not raise an error for this expression:
string:He said "$greeting"
However, in practice this would not work because in context that expression would appear in an attribute like so. It will be obvious that those extra double-quote characters break the DOM because they have a special meaning within an attribute.
<p tal:content="string:He said "$greeting"">This will be replaced</p>
This problem is fixed by simply encoding the reserved characters according to the rules of the markup.
In this case those double-quote characters must be replaced with "
, meaning that the final working example would look like this:
<p tal:content="string:He said "$greeting"">This will be replaced</p>
Example
Here is an example of a string expression in use.
This makes use of the path expression alternation technique to show where braces might be required in a placeholder.
If the path expression here/username
cannot be traversed, then TALES will use the alternate guestUsername
variable instead.
This technique requires the use of a pipe character though, forcing the whole expression to be enclosed in braces.
<p tal:define="guestUsername string:a guest;
loginMessage string:You are logged in as ${here/username | guestUsername}."
tal:content="loginMessage">You are logged in as JoeBloggs.</p>