XPath in PTC Advanced Print Publisher
Introduction
The PTC Advanced Print Publisher implementation of XPath is equivalent to version 1.0 of the standard. Some extension functions are also included to simplify publishing processes and tasks. This topic describes PTC Advanced Print Publisher’s XPath coverage and provides some examples of using it with PTC Advanced Print Publisher’s JavaScript API.
|
|
Be aware of the following when working with XPath:
• XPath expressions that reference axes such as preceding:: or // have a significant performance impact. They take much longer to process than absolute location paths.
• The use of XPath is often unnecessary, for example when querying attribute values of the current element. Using other PTC Advanced Print Publisher methods saves on memory use.
|
Accessing XPath Using JavaScript
XPath can be easily accessed from JavaScript while formatting. The evaluateXPath() method of the fFormatting object takes an XPath expression as its parameter and returns the result. The current node being processed is considered the context node. For example:
formatting.evaluateXPath("count(preceding-sibling::p)");
where the XPath expression is contained within quotes.
You can then assign the returned value to a variable or output it:
formatting.write(formatting.evaluateXPath("name(..)");
PTC Advanced Print Publisher’s XPath functionality allows you to look into other XML content streams in the same document. You have access to their tree to perform any XPath expression. Use the tag name followed by a hash character # before the expression. For example:
formatting.write(formatting.evaluateXPath("myContentStream#count(/chapter)");
where myContentStream is the name of the XML content stream that has a DOM. XPath expression location paths must be absolute.
PTC Advanced Print Publisher XPath Extension Functions
The following extension functions have been added to PTC Advanced Print Publisher’s XPath support. Depending on your XML preferences, the extension functions may need to add the x3b2: namespace prefix to make them available.
Refer to
XML Document Preferences for information.
• concat-nodes() — executes a specified function against the nodes returned from a location path and returns the result as a single string
For example:
concat-nodes(.//@role, '/', 'string()')
returns a list of the role attributes on all descendents of the current element, separated by a slash character.
• if(), if-else(), and if-not() — all perform a test with their first parameter then, if the test returns a true value (or non-zero number), execute the expression in their second parameter.
The if-else() function allows a third parameter which tells PTC Advanced Print Publisher to execute an additional expression if the test fails.
For example:
if(name(..)="chapter", string(../@type))
returns the value of the parent element’s type attribute if the parent is a chapter element.
This is an example of using the if-else() expression in JavaScript:
formatting.write(formatting.evaluateXPath("x3b2:if-else(name(..)='chapter', string(../@type), name(..))"));
This returns the value of the parent element’s type attribute if that parent is a chapter element. If not, it returns the name of the parent element.
• markup() and content-markup() — return the XML content of a specified node as a string.
markup() includes the specified node, content-markup() includes just the content.
• get-context() and get-path() — return the location of the specified node as a string.
get-context() returns a simple path separated by slash characters /.
get-path() returns a full path, including predicates and namespace information, to provide a unique location path for the specified node.
• set-userdata(), get-userdata(), has-userdata(), and clear-userdata() — provide the means to manage private use information on nodes in a read-write DOM.
• add-before() and add-after(), clear–before() and clear-after() — add DOM fragments to the read-write DOMs while formatting.
Refer to
DOM Augmentation for information.
