TPL Templating
Description
An explanation of the syntax of templates that make use of TPL.
Discussion
TPL Templating is a special advanced feature that facilitates the creation of displayed text that is dynamically assembled each time it is displayed. This functionality lets a form display headings, titles, and messages that include the current value of form fields and even be the results of calculations based on field values. TPL Templating is supported in many places within the TransForm system.
For example, a heading might use the value of a field (customername) and the number of items in a data group (photos) to display:
4 photos from customer "Western Market"
A TPL Template consists of normal text interspersed with special placeholders that start with "{" and end with "}" characters. Processing a TPL Template consists of going through the normal text and placeholders to assemble the resulting text. The normal text is inserted in the result without change. The placeholders themselves are not inserted but rather either insert computed text or control skipping the insertion of some of the normal text.
For example, the above example could be the result of the TPL Template:
{len(#photos)} photo{*if len(#photos)!=1}s{*endif} from customer "{#customername}"The first placeholder is replaced with the number of items in the data group "photos" which is calculated using a TPL Expression that makes use of the "len" function. The next two placeholders control adding the letter "s" when appropriate. The final placeholder is replaced with the value of the top-level form field named "customername".
The computed type of placeholder consists of a TPL Expression enclosed in "{" and "}". (The first and last placeholders are computed placeholders in the example above.) The expression is evaluated and the computed value is added to the result. The context of the evaluation is determined by where the TPL Expression is found. If the TPL Expression is in a normal command in a form type definition, such as the text of a Heading command, the context will be the form instance being displayed including data group information if the command is in a data group. (Technically, this means setting the Global, Metadata, and System Data values and correct values for "##" references. The Local Data will be empty.) If the TPL Expression is in a Heading Template or Listing Template, the context will be the top level of that particular form instance (without first executing "ON_LOAD" to set any Global Data).
The skipping type of placeholder are also enclosed in "{" and "}". They start with the "*" character followed by "if", "elseif", "else", or "endif". (The second and third placeholders are skipping placeholders in the example above.) Skipping placeholders that start with "{*if " or "{*elseif " include a TPL Expression after the starting part. The expression is evaluated and the computed value determines which action to take.
If an "{*if " expression value is true (that is, non-blank) then the text that follows the placeholder is inserted in the result up to the next "{*elseif ", "{*else}", or "{*endif}" placeholder. If this following placeholder is "{*elseif " or "{*else}", then that placeholder and all text and placeholders until the next "{*endif}" is skipped. Normal processing of the TPL Template text then continues after the "{*endif}".
If the expression value is false ("") then the text that follows the placeholder up until the next "{*elseif ", "{*else}", or "{*endif}" is skipped. If the next skipping placeholder is "{*elseif ", then its TPL Expression is evaluated and the process continues as if it was an "{*if " placeholder. If the next skipping placeholder is "{*else}" then the text after it up until the "{*endif}" placeholder is inserted and normal processing continues after the "{*endif}".
While inserting text, computed placeholders are treated normally, resulting in inserted text when not being skipped.
{*if} sequences may be nested as you might expect.
For example this results in "Empty", "1 item", or "2 items" depending up if the nitems field is 0, 1, or 2:
{*if #nitems==0}Empty{*else}{#nitems} item{*if #nitems!=1}s{*endif}{*endif}If you need to include a "{", "}", or "\" character in normal TPL Template text, precede it with "\". For example:
Please choose one of \{A, B, C\}