Pre-TPL Syntax
Description
An explanation of the syntax of expressions and templating in earlier versions that are still supported but may be upgraded to the newer TPL Expressions and TPL Templating.
Discussion
In late 2018 a major addition was made to the TransForm system: Adding TPL. 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 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.
Some of the functionality provided by TPL was available in earlier versions of TransForm using different means and different syntax. Form type definitions created pre-TPL continue to be supported by TransForm. However, newly created form type definitions now require using the TPL syntax.
Upgrading a form type definition from pre-TPL to TPL syntax requires changing templates to use the new syntax as well as IF command tests. Form types that are assumed to use the old syntax are listed in the Form Types List with a small orange dot after the name, and the Advance Features properties include a section titled "Pre-TPL Form Definition" that explains the steps to take to upgrade. Information about the new syntax is in the TPL Expression and TPL Templating sections of this help.
As help for older forms, and to aid in understanding the older syntax when upgrading, this section has information about the pre-TPL syntax.
IF and ELSEIF Commands
The one special property for the IF and ELSE IF commands is the Test property. Pre-TPL, this is a JavaScript expression that can evaluate to "true" or "false".
The JavaScript expressions may refer to fields at the current level using "fields." followed by the field name. Top level fields may be referred to using "data." followed by the field name. You can refer to the current status ID with "statusID" and you can refer to a true/false value indicating if any problems were detected in the commands preceding (above) this one with "problems.missingRequired" and "problems.hasErrors".
Note: JavaScript uses "==" to test equality and "!=" for inequality. The characters "&&" and "||" may be used for "and" and "or", respectively, and parenthesis may be used for grouping. The words "true" and "false" may be used to manually set a true or false result for testing.
To make it easier to create the tests, there is an "Append Field Name" button under the Test property textbox. Clicking it will display a list of fields at the current and top levels. Click on a row in the list to append the appropriate text for referring to that field.
For testing through use of Preview, either use Form Preview Data (defined in JSON on the Form Properties Screen) or the Preview Value property radio buttons above the Comment property. Preview values of other fields are not used.
Examples of tests are:
fields.casingIntact=="Yes" data.quantity>20 !data.array1 || data.array1.length==0
The first example is true if the field "casingIntact" has the value "Yes". The second example is true if the top level field "quantity" has a value greater than 20. The last example is true if the top level data group with field name "array1" has not been created or exits but has no items.
Templating
As a special advanced feature, in pre-TPL form types, Alpha Anywhere Templating may be used to insert special values. This templating is done through special expressions enclosed in "{" and "}". Data values are accessible through special names. Names that start with "fields." can refer to fields at the current level of the form instance JSON data. Names that start with "data." can refer to fields that start at the top level of the JSON. The special name "thisGroup.count" is the 0-based index in the current Data Group. The special name "thisGroup.text" is the current Data Group Name property. You can refer to the current status ID with "statusID" and you can refer to a true/false value indicating if any problems were detected in the commands preceding (above) this one with "problems.missingRequired" and "problems.hasErrors".
An example of using the templating feature would be this text for a section-type heading:
Child #{thisGroup.count+1} for {data.parent}It might result in the heading:
Child #2 for John Doe
HTML Command
The pre-TPL HTML command allowed any HTML to be used for display. Starting when TPL became available, the HTML that may be used has been restricted for various security and other reasons.
These are some of the new restrictions: Opening tags, (like <div>) without a matching closing tag (like </div>) are no longer allowed. A few tag types (including <a> and <input>) and attributes are not allowed. Most references to URLs and data URIs require special account-level settings and special syntax, including in <img /> tags. Void tags need to include the closing "/" (such as <br/>, <img src="..." />, and some of the SVG tags). Only double-quotes (") are allowed for attribute quoting (e.g., style="color:red;" and not style='color:red;'). Attribute names (like "style") must be immediately followed by equal and double quote. You can test HTML text using the Preview of the form to check if a desired construct is allowed.