XPath Expression Builder

www.altova.com Expand/Collapse All Print this Topic Previous Page Up One Level Next page

Home >  User Reference > Edit XPath Expression Dialog >

XPath Expression Builder

When the Builder button in the Edit XPath Expression dialog is clicked (see screenshot below), entry helper panes to help you build an XPath expression become visible. Double-click an entry in any of these entry helpers to enter it at the current cursor point in the XPath expression. The X in the text above the text box—XPath X Expression—indicates the XPath version. The XPath version depends upon the XSLT version that has been selected for the SPS being currently edited (XPath 1.0 for XSLT 1.0, XPath 2.0 for XSLT 2.0, and XPath 3.0 for XSLT 3.0). To switch the XPath version, switch the XSLT version of the SPS.


There are three entry helper panes:


A schema tree for entering element and attribute nodes in the XPath expression. If the Absolute XPath check box is unchecked, then the location path to the selected node is entered relative to the context node (the node in the design within which the XPath expression is being built). An absolute XPath expression starts at the document root, and is used for the selected node if the Absolute XPath check box is checked.
An entry helper pane for: (i) axes (ancestor::, parent::, etc), (ii) operators (for example eq and div), and (iii) expressions (for # in  # return #, etc). This pane displays the axes, operators, and expressions either listed alphabetically or grouped by functional category. Select the option you want by clicking the appropriate icon above the pane.
An entry helper with the functions of the active XPath version either listed alphabetically or grouped by functional category.  Select the option you want by clicking the appropriate icon above the pane. The  n  and  t  buttons above the pane display the arguments of functions, respectively as names and datatypes.



Click to expand/collapse


Features of the Builder:


To view a text description of an item in either 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).
Signatures are listed using either the names or datatypes of the function's arguments and output. Select the  n  or  t  button above the pane to toggle between the two display options.
Double-clicking an item in any of the panes(operator, expression, or function), inserts 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, 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 placeholder.


After you have entered a function in the expression, hovering over the function name displays the function's signature and a text description of the function. If different signatures exist for a function having the same name, these are indicated with an overload factor at the bottom of the display. If you place the cursor within the parentheses of the function and press Ctrl+Shift+Spacebar, you can view the signatures of the various overloads of that function name.  


Building XPath expressions

The Edit XPath Expression dialog helps you to build XPath expressions in the following ways.


Context node and schema tree

The Selection text box in the Select Schema Attribute or Element pane immediately shows you the context node. Place the cursor over the text box to see the full path of the context node. In the schema tree below the Selection text box, you can see where the context node occurs and quickly build the XPath expression by referring to the schema tree. The Condition, Auto-Calculation, etc, for which the expression is being created, will be inserted at a location within this context node, and the XPath expression will be evaluated with this node as its context.


Inserting a node from the schema tree

In the Select Schema Attribute or Element pane, the entire schema is displayed. Double-click a node in the schema tree to insert that node in the XPath expression. If the Absolute XPath check box is not checked, the selected node will be inserted with a location path expression that is relative to the context node. For example, in the screenshot above, the Newsitem element, which is a child of the Newsitems element (the context node), has been inserted with a location path that is relative to the context node (that is, as Newsitem). If the Absolute XPath check box were checked, the Newsitem node would have been inserted as $XML/presswatch/newsitems/newsitem.


Namespace information

The schema tree in the Select Schema Attribute or Element pane contains a Namespace item. Expanding this item displays all the namespaces declared in the stylesheet. This information can be useful for checking the prefixes of a namespace you might want to use in an XPath expression.


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) for the XPath version selected as the XSLT version for the SPS. The display can be toggled between an alphabetical listing and a hierarchical listing (which groups the items according to functionality). To insert an axis, operator, or axis in the XPath expression, double-click the required item.


Inserting XPath functions

The Select Function pane lists XPath functions alphabetically or grouped according to functionality (click the respective icon 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 (? indicates a sequence of zero or one items of the specified type; * indicates a sequence of zero or more items of the specified type). The arguments can be displayed as names or as datatypes; select the  n  or  t  button above 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 none or one date item. Placing the mouse over a function pops up a brief description of the function.




To insert a function in the XPath expression, double-click the required function.


Java and .NET extension functions can be used in XPath expressions, enabling you to access the functions of these programming languages. The Java and .NET buttons at the bottom of the dialog, pop up info boxes with explanations about how to use Java and .NET extension functions in XPath expressions. For more information about this, see the Extension Functions section of this documentation.


Intelligent editing during direct text entry

If you type an expression directly in the Expression text box, options that are available at that point are displayed in a popup (see screenshot below).




These include elements (such as presswatch in the screenshot above), descendant nodes (presswatch/selection in the screenshot above), XPath functions (fn:upper-case above) and XPath axes (ancestor-or-self above). The list of available options becomes more restricted as the expression is entered in the Expression text box. 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.


The Otherwise check box

The Otherwise check box (see screenshot below) adds an Otherwise branch to a conditional template as its last branch. Only one Otherwise branch may be present in a conditional template. When a conditional template is evaluated, the first branch to evaluate to true is executed. If no branch evaluates to true, then, the Otherwise branch is executed if present, otherwise the conditional template is exited without any of its branches being executed. Since the Otherwise branch is triggered only in the event that no preceding branch evaluates to true, it does not need to have a condition defined for it. As a result, when the Otherwise check box is selected, the entry field of the XPath expression is disabled.




For details of how to use the Otherwise condition, see Conditional Templates.




© 2019 Altova GmbH