Expression Builder
The Expression Builder enables you to build correct XPath expressions with respect to the current context node. It enables you to enter correct node locator paths, select nodes in the schema tree, and enter operators and functions that are syntactically correct. Switch to Expression Builder by clicking the Builder button (see screenshot below). When the Builder button is clicked, entry helper panes to help you build an XPath expression become visible. Double-click an entry in the entry helpers to enter it at the current cursor location in the Expression pane. On clicking OK, the expression is entered at the current location in the design.
There are three entry helper panes:
•A schema tree for selecting and entering element and attribute nodes. If the Relative XPath check box is checked (as in the screenshot above), then the path to the selected node is entered relative to the context node—which is the node in the design within which the XPath expression is being built. The context node is shown below the schema tree pane. You can see in the screenshot above that the context node is the Customer element. You can also see, from the title bar of the window, that this XPath expression is being built for the Text property of the Label3 control. If the Relative XPath check box is unchecked, then an absolute XPath expression to locate the selected node is entered; such an expression would start at the document root, for example: $CUSTOMERS/Customers/Customer/Name.
•An entry helper pane for operators and expressions. These include: (i) axes (ancestor::, parent::, etc), (ii) operators (for example eq and div), and (iii) expressions (for # in # return #, etc). The items of the pane can be either listed alphabetically or grouped by functional category. Select Hierarchical (for the grouped option) or Flat (for an alphabetical listing) from the dropdown menu in the title bar of the pane.
•An entry helper with XPath functions either listed alphabetically or grouped by functional category. Select Hierarchical (for the grouped option) or Flat (for an alphabetical listing) from the dropdown menu in the title bar of the pane. The Names/Types option enables you to choose whether the function's arguments are displayed as names or datatypes. Note that the list of available functions includes MobileTogether extension functions and Altova extension functions.
Features of the Builder
•To view a text description of an item in the Operators pane and Functions pane, hover over the item.
•Each function is listed with its signature (that is, with its arguments, the datatypes of the arguments, and the datatype of the function's output).
•The signatures of functions are given with either the names or the datatypes of the function's arguments and output. Select Names or Types from the dropdown menu in the title bar of the pane for the respective option.
•Double-click an item in any of the three entry helper panes (operator, expression, or function) to insert that item at the cursor location in the expression. Functions are inserted with their arguments indicated by placeholders (the # symbol).
•If (i) text is selected in the XPath expression's edit field (for example Name in the screenshot above), and (ii) an expression or function that contains a placeholder is double-clicked to insert it, then the text that was selected is inserted instead of the first placeholder.
•After you have entered a function in the expression, hovering over the function name displays a popup containing the function's signature and a text description of the function. If additional signatures exist for a function, then this is indicated by an overload factor at the bottom of the popup. (Note: If multiple functions have the same name but each takes a different set of arguments, then, this set of functions is considered, more correctly, to be a single function with multiple signatures.)
•If, in the Expression pane, you place the cursor within the parentheses of a function and press Ctrl+Shift+Spacebar, you can view the different signatures of that function.
Building XPath expressions
The Edit XPath Expression dialog helps you to build XPath expressions in the following ways.
•Title bar of window displays
The title bar of the XPath/XQuery window displays information about the context (such as the design component (project, page, control, etc) and property) for which the expression is being built. For example, in the screenshot above, the expression is being built for the Text property of the Label3 control on a page named Customers.
•Context node and schema tree
The Context text box immediately below the Schema Tree pane shows you the context node of the expression. In the schema tree itself, you can see where the context node occurs and quickly build the XPath expression by referring to the schema tree.
•Inserting a node from the schema tree
Double-click a node in the schema tree to insert it in the XPath expression. If the Relative XPath check box is checked, then the node is inserted with a location path that is relative to the context node. For example, in the screenshot above, the Name element, which is a child of the Customer element (the context node), has been inserted with a path that is relative to the Customer element. If the Relative XPath check box is not checked, then the Name node would be inserted as $CUSTOMERS/Customers/Customer/Name.
•Inserting XPath axes, operators and expressions
The Select Operator/Expression pane lists the XPath axes (ancestor::, parent::, etc), operators (for example, eq and div), and expressions (for # in # return #, etc). The display can be toggled between an alphabetical listing and a hierarchical listing (which groups the items according to functionality). To insert an axis or operator in the XPath expression, double-click the required item. Placing the mouse cursor over an axis/operator/expression displays a brief description of that item.
•Inserting XPath functions
The Select Function pane lists XPath functions alphabetically or grouped according to functionality (select Hierarchical or Flat at the top of the pane to switch between the two arrangements). Each function is listed with its signature. If a function has more than one signature, that function is listed as many times as the number of signatures. Arguments in a signature are separated by commas, and each argument can have an occurrence indicator. The symbol ? indicates a sequence of zero or one items of the specified type; * indicates a sequence of zero or more items of the specified type; + indicates a sequence of one or more items of the specified type. The arguments can be displayed as names or as datatypes. Select the appropriate option (Names or Types) at the top of the pane to toggle between the two display options. Each function also specifies the return type of that function. For example: => date ? indicates that the expected return datatype is a sequence of zero or one date items. Placing the mouse cursor over a function displays a brief description of the function.
Intelligent editing during direct text entry
If you type an expression directly in the Expression text box, a list of options that are available at that point are displayed in a popup (see screenshot below).
These include the following components:
•elements (such as presswatch in the screenshot above)
•descendant nodes (presswatch/selection in the screenshot above), and parent node of the context node
•XPath functions (fn:upper-case above) and XPath axes (ancestor-or-self above)
•a list of the global variables defined for the project (displayed when a $ character is entered in the expression)
•a list of the custom strings defined in the Localization dialog (displayed when the mt-load-string function is entered in the expression; see the description of mt-load-string)
Go up and down the list of options using the Up and Down keys, and press Enter if you wish to select an option and enter it in the expression.