In an XML virtual document, there are five kinds of nodes: the root node, elements, text nodes, comments, and processing instructions. The root node and any element can have child nodes of any type. The other kinds of nodes cannot have child nodes. Attributes are not nodes.
The following table lists basic DOM-style paths to get or set many of the nodes of an XML virtual document. When there are multiple nodes of the same type or with the same name, and when you do not want the first one, see the next section.
You also use these paths when you create more complex DOM-style paths as discussed in later subsections.
The value returned does not include the opening syntax (<?) or the closing syntax (?>). Similarly, do not include the opening or closing syntax when setting the value.
Ensemble removes all processing instructions when it reads in XML files. The only instructions that can be present are instructions that you add. (To add them, use setValueAt() with a path like the one shown here.)
In this case, the referenced element contains a child element (in contrast to the previous example). Note that Ensemble ignores whitespace when comparing DOM-style paths to values. That is, the value here matches the given path whether or not the document contains line breaks and indentation.
You can add the following basic path modifiers to the end of basic paths (listed in the previous section), with noted exceptions. You can use the resulting paths in the same way that you use any of the basic paths.
Refers to an item by item position. Only instances of that item are counted; items of other types are ignored.
When you get a value, this syntax returns the nth instance of the item to which the basic path refers (or an empty string otherwise).
When you set a value, this syntax either overwrites or creates the nth instance of the item to which the basic path refers.
You can substitute a hyphen (-) to access the last instance. You can also omit the square brackets.
Refers to a child element by child element position.
You can substitute a hyphen (-) to access the last child. You can also omit the square brackets.
You can use this only with a basic path that refers to an element; that is, you cannot use it with functions such as comment().
You can use this syntax only when getting a value, not when setting a value.
You can combine this path modifier with the other path modifiers, if you use the /[n] modifier as the last modifier.
Refers to an item by node position.
When you get a value, this syntax returns the nth node, if that node is an instance of the item to which the basic path refers. Otherwise the path is invalid, and an error is returned.
When you set a value, this syntax overwrites the nth node, if that node is an instance of the item to which the basic path refers. Otherwise the path is invalid, and an error is returned.
For a path that refers to an element (either a basic path or a path that uses basic modifiers), you can also obtain the opening and closing tags of the element. To do so, add full() to the end of the path.
Inserts an instance of the item to which the basic path refers, right before the nth node in the given parent. Nothing is overwritten. The path is invalid if the parent does not contain at least n nodes.
Inserts the specified element (given by the element_name argument) right before the nth child element of the given parent. This path is invalid if the given element does not have at least n child elements.
All the namespace prefixes and their corresponding URIs, in the scope of the given element. This information is returned as a comma-separated list. Each list item consists of the namespace prefix, followed by an equal signs (=), followed by the URI. The default namespace URI is listed first without a prefix. For example: =http://tempuri.org,s01=http://myns.com
If the document uses XML namespaces, for each element or attribute that is in a namespace, you must modify that section of the path to include a namespace prefix, followed by colon (:). A namespace prefix is one of the following:
You cannot use any wildcards in a path when you are setting the value for that path.
The output document of a DTL does not necessarily use the same namespace prefixes as the input document. The namespaces are the same, but the prefixes are generated. According to the XML standard, there is no significance to the choice of prefix.
It can be useful to test virtual document property paths in the Terminal before using them in business processes, data transformations, and so on, particularly when you are getting familiar with the syntax. To do so for DOM-style XML paths, do the following in the Terminal or in test code:
Create a string that contains the text of a suitable XML document.