Using XPath in Contexts
XPath expressions can be used with contexts as a way of qualifying any given node in the context selector. If an expression is used in this way it is termed in the XPath standard as a predicate. When a document is processed the expression is evaluated and the result converted to a boolean value. If that value is true, then that node of the context selector is considered to match. If that value is false, however, the context does not match. A common use of XPath predicates is to test a location path. Tests of this nature describe a path through the document, usually relative to the node for which the predicate has been defined. If the element or attribute described by the path exists, the expression is considered to be true.
Some examples of using predicates in this way are detailed below:
• Match a specified element within a specified parent, where that parent contains a specified child
The example context title in chapter will match a title whose parent is a chapter. If you then add the XPath predicate .//table to the chapter node, position matching will search for a title whose parent is a chapter that includes a table among its descendants. The context will now be shown in the Elements list as title in chapter[.//table].
• Match a specified element within a specified parent, where that parent has any value for a specified attribute
Using the example context title in chapter again, if you add the XPath predicate @role to the chapter node, position matching will search for a title whose parent is a chapter that has any value defined for the role attribute. The context will now be shown in the Elements list as title in chapter[@role].
• Match a specified element within a specified parent , where that parent has a specified value for a specified attribute
Using the example context title in chapter again, if you add the XPath predicate @role='bold' to the chapter node, position matching will search for a title whose parent is a chapter that has the value “bold” defined for the role attribute. The context will now be shown in the Elements list as title in chapter[@role=”bold”].
• Match a specified element that contains text content, where the element appears within a specified parent
Using the example context title in chapter again, if you add the XPath predicate text() to the title node, position matching will search for a title that contains text content, and whose parent is a chapter. The context will now be shown in the Elements list as title[text()] in chapter.
To include an XPath predicate for position matching in a context, select XPath predicate from the Position drop down menu in the Edit Context dialog box, and type the predicate. Note - square brackets will be added automatically when the predicate is saved so they must not be included when typing the string.
|
|
You may encounter anomalies in the display of a context defined using XPath in this way, if you are publishing with FOSI. If the source element is subsequently declared in the generated text of another element, the context of the source element defined with XPath cannot be processed by FOSI. You will be presented with a warning message. To overcome this, if it is your intention that the particular context of the source element that includes the XPath predicate is the one that should be processed in the generated text of the other element, include the XPath test in a condition of the original element, rather than a context.
For example, in your stylesheet you could define a table element with three contexts, each one of which uses an XPath predicate to set the font size of the table content based on the value of the pgwide attribute of the table (for example, the context table[@pgwide=90]) You might then decide that you want the title of your book to include a table, and set the generated text of the title in book context to always output a table, based on the > > menu option. If you then publish your document for print via FOSI you will see warning messages advising you that each of the contexts of the table element that contain the XPath predicate will be ignored for the table output in the title in book context, for example:
[A31450] ERROR: Cannot evaluate XPath expression in
stylesheet. An XPath Predicate is used in a Styler context
for an element that occurs in generated text. (The
predicate may have been generated by Styler to represent a
position qualifier on a parent or ancestor.) This context
will be ignored in FOSI-based outputs.
Element: table. XPath expression: table[@pgwide=90].
To overcome this anomaly, create conditions based on XPath tests for the table, rather than contexts. For example, the condition If XPath expression (@pgwide=90) is true for the table will provide the same output for the table based on the pgwide attribute, but will not cause errors during publishing when the table element is used in generated text for the title in the book. If, however, the context with the XPath predicate is not the one that should be output in the generated text anyway, and its omission by FOSI has no bearing on the required output of your document, you may simply ignore the error message.
|
|
|
With DITA document types, predicates should only be attached to the element defined by the context. The use of general contexts such as image anywhere in topic[@outputclass=’tpdr’] should be avoided. They will not work in Edit view, and Arbortext Styler will not indicate that the context matches when you position the cursor in the edit window inside an element that should match. They will also not match in print/PDF output generated by the FOSI print engine.
Instead, use a context such as image[ancestor::topic/@outputclass=’tpdr’].
|
To Test an XPath Predicate in Arbortext Editor
|
|
This method of testing predicates does not work if the predicate contains position(), or its shortcut form (just a number), or last(). However, these functions will function correctly when used in predicates in Arbortext Styler.
|
It often takes multiple attempts to define the correct the correct XPath expression to meet your requirements. It is much quicker to develop and test expressions Arbortext Editor than in Arbortext Styler - the steps below explain how:
1. Open your document in Arbortext Editor and place the cursor inside the element whose position you are trying to test with the XPath predicate.
2. In the Arbortext Editor command line, enter the command eval oid_xpath_boolean(oid_caret(), "self::node()[...]") - replacing ... with the expression you wish to use for the predicate.
3. Look at the resulting value in the Eval Output window - if the value is 1, the test is true. If a value of 0 returned, the test is false.
