TPL Expressions
Description
An explanation of the syntax and semantics of TPL expressions.
Discussion
The TransForm Programming Language (TPL) is a means by which a form designer can specify the behavior of a TransForm form as the user fills it in. TPL is a traditional programming language turned to the needs of TransForm forms. While not identical to any other programming language, its syntax and semantics should be familiar and easily learned by developers familiar with languages such as Basic, JavaScript, Java, and C.
TPL code is used in TransForm in two main ways: Standalone expressions to calculate values for display or condition testing, and multi-line functions to respond to events such as field value changes or to be called in expressions or other functions.
The specifics of TPL expression syntax are more completely described in the full TPL documentation, some of which is available in the TPL Editing and Testing Screen's Reference tab. The TPL Editing and Testing Screen is described in this help and is accessed using the Edit Custom Code button on the Form Type Properties Screen.
Like most computer languages, expressions are a combination of explicit constant values, references to variable values, operators, and functions. An expression is evaluated by applying the operators and functions to the values and any intermediate values, resulting in the value of the expression itself. The order of execution of the operators is determined by certain rules which include the use of parenthesis to override the defaults. An expression may consist of a single value, such as just the number "5" or a reference to a field like "field1", and not involve any operators or functions.
Most data used by TPL code is either text data, including text representations of numeric and date/time values, or JSON-style objects (including arrays). Operators and built-in functions are provided for working with this data. For example "+" is a binary operator that results in a text representation of the numeric sum of two values that are, or can be converted to, numbers, and "&" is a binary operator that results in a text value that is the concatenation of two values that are accessed as text strings. In expressions, numeric constants are represented as integers or decimal values. Text constants are enclosed in double-quote (") characters. Within the double-quotes, a double-quote may be represented by a backslash ("\") followed by a double-quote. Other escapes are "\n" for embedded newline, "\t" for a tab character, and "\\" for a backslash.
True/False values in TPL calculations are usually represented by a blank value ("") for false, and "1" or any other non-blank value for true. The IF and ELSEIF commands, and the "!" (not), "||" (or), and "&&" (and) operators, all treat "" as false and all other values as true. The expression "4 < 5" results in "1" and "4 > 5" results in "". Note that the values of some form fields may need to be interpreted differently and they may require explicit text value testing, such as checking for "Yes" for true and "No" for false, or setting to those values as appropriate for the results of a calculation.
Here are two examples, first an expression that compares the value of the top-level field with the field name "field1" to a particular text value and another that extracts the first 5 characters of another field and adds the suffix "...":
#field1 == "Yes" substr(#field2, 0, 5) & "..."
The main operators are:
- Operator
- Description
- + - !
unary plus, minus, not
- * /
multiply, divide
- + - &
add, subtract, concatenate
- < <= >= >
numeric and text comparisons
- == !=
numeric and text comparisons
- === !==
case-sensitive text comparisons
- && ||
and, or
There are several classes of data that TPL code needs to access. These include the data fields of the form being edited, information about the form (such as its status), and temporary data to be used as part of computing various results. TPL provides means for explicitly referring to each of the different classes of data.
Form Data is the JSON object that contains the current values of all of the form's fields. The fields are referenced by prefixing the field name with the "#" character. Items within Data Groups (items in arrays) may be addressed with an array index in "[]" characters.
For example:
#field1 #array1[2].name
Group Data is a JSON object that contains the current values of just a single item within a Data Group. The fields are referenced by prefixing the field name with "##".
The IF and ELSEIF commands' Properties Screen include an "Insert Field Name" button that brings up a a list of fields to insert in the expression being entered. Each row shows the title and field name of a field, including fields at top level in the form and in the same data group. Clicking one of those rows will insert the appropriate syntax for that field.
Metadata about the current form, such as the current status of the form and the date/time the form instance was created, are referenced with names prefixed with "$#". System data relating to the current state of the app, such as the display name of the logged in user, are referenced with names prefixed with "$".
Examples of metadata and system data are:
$#status $#created $userdisplayname
Temporary data used while displaying a single form is referenced with names prefixed with "^".