Expression Editor - User Guide

The expression editor is a dialog that edits expressions. It is used in several places, including the Scribe app using the "Templates" tab, and the Automate app when editing template (*.xsl) and pipeline (*.xpl) files.

Related topics and links
Automate app a no-code editor for task pipelines and content generation
Scribe app a no-code editor specifically designed for rich text content generation
Data setup Data setup files and no-code editor

Expressions are incredibly useful. They are used to calculate values, make decisions, generate content and more. Expressions are based on XPath, which is a W3C-backed open standard that is widely used.

To make it easy to work with expressions, Tag offers three different point and click editing panels. These are described below along with a raw syntax panel.

When most logic instructions are inserted or edited, an expression editor dialog is opened. You can move between editing panels using radios buttons at the top.

Sometimes, moving to a different panel may cause part of an expression to be lost. When that happens Tag prevents you from selecting the other panel. You need to delete the existing expression before selecting an incompatible editing panel.

Quick values panel

The Quick values panel displays all visible data fields in a tree. You select the field you want, optionally choose a format, and click Insert. This creates a simple expression that copies a data value.

Quick values expression editing panel

If the data type supports formatting, additional branches are added to the tree to select common formats. This is shown above under the Date of birth branch.

If variables are visible to the logic or pipeline instruction being edited (i.e., the instruction which stores an expression like xsl:if, or p:if), they will be included in the quick values tree. This is true for xsl:param and p:option instructions as well.

Basic panel

The Basic panel is ideal for creating true/false expressions used to control if and choose/when instructions. It creates conditions, which have left and right parts joined by a comparison. An expression in this panel consists of one or more conditions (joined by and/or).

Basic expression editing panel

Each of the words shown above are touch-sensitive and will display a popup menu when clicked.

The left and right words represent data fields or literal (manually entered) values. The center word displays a list of comparisons that are appropriate for the type of data being compared.

  • true/false - equals, does not equal
  • numeric - equals, does not equal, <, <=, >, >=
  • characters - equals, does not equal, contains, starts-with, ends-with, matches-pattern

This is how two conditions look. If you click on the 'and' you can change it to 'or'.

Basic expression editing panel with 2 conditions

The above example shows data fields using names that contain a colon (e.g., assessInfo:program). The part before the colon is called a namespace prefix, and usually corresponds to a data setup file where the prefix matches the base file name (e.g., assessInfo:program refers to the program data field defined in the assessInfo.rng data setup file). Using prefixes makes it possible to use multiple data setup files together in one report.

Advanced panel

The Advanced panel is similar to the basic panel, but with much more functionality. It is a full-featured touch-sensitive expression editing panel that can handle most XPath syntax.

Advanced expression editing panel

Each part of the expression in the advanced expression editing panel is clickable and presents a popup menu with available options. Expression parts can be nested and grouped within brackets.

Literal values are manually-entered strings, numbers or true/false values. Named values and Source data contain parts of the quick values tree.

The Path menu lets you refer to the context item or insert a path step. The Compare / combine menu handles >, <, =, >>, <<, and/or and similar expression operators. The Math menu handles add, subtract, multiply and divide for number values.

The Function... menu item opens a dialog with dozens of functions to choose from. This is described further in the next section.

The Sequence / collection menu supports sequences, ranges, arrays and maps. The Logic menu handles compound expression parts like if, for, let, every and some expressions. The Type utility supports castable as, cast as, treat as and instance of expressions.

Finally, the Add filter menu item lets you add one or more predicates (filters) to narrow the currently selected sequence of values.

Functions

The functions dialog displays a tree of all available functions. Most are defined by the open XPath standard. These are supplemented with 1-2 dozen that are only supported in Tag.

Functions dialog opened from the Advanced expression editing panel

Each function accepts zero or more arguments. In the advanced panel, each argument is edited using its own specific popup menu. Links to more information about each XPath function are provided in the functions dialog.

The following screenshot shows how a format-date function looks in the advanced panel.

Advanced panel displaying the format-date function

Raw syntax panel

The Raw syntax panel is a text area that accepts raw XPath syntax. In rare cases where the advanced panel does not support what you need, this panel can handle 100% of XPath syntax.

Raw syntax expression editing panel

If errors are detected, a message is displayed beneath the text area to describe the issue.