Technical Series: Leveraging XPath Functions in OnBase 17

[Tony_Maimone]

Technical Series: Leveraging XPath Functions in OnBase 17

With OnBase 17, Document Composition has worked to improve user experience working with source XML data (see the What’s New in OnBase 17: Document Composition Enhanced XML Placeholder Creation blog post for general updates). One of the updates includes extending support for XPath functions, allowing users to leverage even more power and flexibility from XPaths.

You might already be familiar with how to refine your XPaths using operators, predicates, wildcards, and axes. For more information on XPath syntax and operators, please see:

https://www.w3schools.com/xml/xpath_syntax.asp

https://www.w3schools.com/xml/xpath_operators.asp

https://www.w3schools.com/xml/xpath_axes.asp

In addition to these XPath syntax standards, Doc Comp now supports the Core Function Library defined by the XML Path Language (XPath) Version 1.0 (W3C Recommendation 16 November 1999)*. This enhancement means that in addition to having XML Query Placeholders be composed as node values, these placeholders can also stand in for Boolean, numeric, and string values. Please note that because XPath functions can represent more than just XML nodes, we cannot always identify what content should be highlighted in the XML viewer when creating new XML Query Placeholders. With this iteration of the product, you may see inconsistent or no highlighting in the XML viewer when manually typing in XPaths that are more refined.

For more information on the Core Function Library, please refer to: http://www.w3.org/TR/xpath/#corelib

* The one exception is that we cannot support the id() function that selects elements by their unique ID. We cannot support this function because the unique IDs are declared in the DTD and we do not accept XML with a DTD.

As you continue to refine the XPath and incorporate more functions, the XPath grows longer in length. Document Composition currently has a limit of 255 characters for XPaths. If your XML structure has a large depth or if your elements have long names, you can quickly reach this limit. One solution to this problem is to use relative XPaths when possible.

Supported XPath Functions

Below is a list of the XPath Functions you can use within Doc Comp:

Node-Set Functions
count	Returns the number of nodes in the node-set argument.
last	Returns a number equal to context size of the expression evaluation context.
local-name	Returns the local part of the expanded name of the node in the node-set argument that is first in document order.
name	Returns a string containing a QName representing the expanded name of the node in the node-set argument that is first in document order.
namespace-uri	Returns the namespace Uniform Resource Identifier (URI) of the expanded name of the node in the node-set argument that is first in document order.
position	Returns the index number of the node within the parent.
Boolean Functions
boolean	Converts the argument to a Boolean.
false	Returns false.
lang	Returns true if the xml:lang attribute of the context node is the same as the argument string.
not	Returns true if the argument is false, otherwise, false.
true	Returns true.
String Functions
concat	Returns the concatenation of the arguments.
contains	Returns true if the first argument string contains the second argument string; otherwise returns false.
normalize-space	Returns the argument string with the white space stripped.
starts-with	Returns true if the first argument string starts with the second argument string; otherwise returns false.
string	Converts an object to a string.
string-length	Returns the number of characters in the string.
substring	Returns the substring of the first argument starting at the position specified in the second argument and the length specified in the third argument.
substring-after	Returns the substring of the first argument string that follows the first occurrence of the second argument string in the first argument string.
substring-before	Returns the substring of the first argument string that precedes the first occurrence of the second argument string in the first argument string.
translate	Returns the first argument string with occurrences of characters in the second argument string replaced by the character at the corresponding position in the third argument string.
Number Functions
ceiling	Returns the smallest integer that is not less than the argument.
floor	Returns the largest integer that is not greater than the argument.
number	Converts the argument to a number.
round	Returns an integer closest in value to the argument.
sum	Returns the sum of all nodes in the node-set. Each node is first converted to a number value before summing.

Function examples

Here are some examples of the information you can extract from your source XML by using XPath functions. The sample XML for the context of all of the examples in this post is included below:

Output the number of books in a bookstore:

count(/bookstore/book)

Output the total amount of money all of the books in the store are worth:

sum(/bookstore/book/price)

Output the average price of a book in the store:

sum(/bookstore/book/price/text()) div count(/bookstore/books)

Round the average price of a book in the store to a whole number:

round(sum(/bookstore/book/price) div count(/bookstore/book))

For example, you can also use the following XPath to return the same value for the average price of a book in the store to a whole number:

round(sum(//price) div count(//book))

Determine if the store contains more than 5 books:

boolean(count(//book) > 5)

Get the title of a book when you only know part of the full title:

*Tip – You can also use this function to output all of the books with titles containing a particular substring by setting the Placeholder’s Output Style to list or table.

/bookstore/book[contains(title, “Gorg”)]/title

Get a list of all of the titles of books written by a particular author by using the following XPath (to see all of the books, be sure to set the Placeholder’s Output Style to list or table):

//book[author[contains(last-name, "Melville")]]/title

Because Repeating XML Query Placeholders iterate over XML nodes, the XPaths for these Repeating Placeholders should return a set of XML nodes. If you try to use an XPath containing a function that will return a Boolean, numeric, or string value, then the composed document will not contain any data for that Repeating Placeholder. In this case, the System Warnings tab in the Diagnostics Console should notify you that the type of content returned by the XPath cannot be used for Repeating Placeholders.   

Here are some examples of XPaths that would be valid for Repeating XML Query Placeholders:

Repeat over all of the books:

/bookstore/book

Repeat over only books with the genre “Autobiography” or “novel”:

/bookstore/book[@genre="autobiography"] | /bookstore/book[@genre="novel"]

Repeat over the books that have a title but do not have a price:

/bookstore/book[title and not(price)]

XPath functions can also be used to refine the output of Nested Placeholders. You can edit the XPath of existing Nested Placeholders from the Repeating Placeholder Management Task Pane. Note that when editing the XPath of a Nested Placeholder, the scope of the Placeholder has already been defined, so we remove the base part of the XPath that is the same as the XPath of the Repeating Placeholder. Removing this duplicate information means that the base XPath is not included in the 255 character limit for Nested Placeholders.

The following example is based on the Repeating Placeholder with the XPath: /bookstore/book and its Nested Placeholder with the XPath: /author

If you insert the author Nested Placeholder as is, on the composed document you would see the author’s first name followed by the last name without any spaces between the names. Using XPath functions, we can update the XPath to output the author’s name in a more readable way. When you go to edit the author Nested Placeholder, you will see the XPath for your Repeating Placeholder serving as the base you will build upon for your Nested Placeholder’s XPath.

To output the author’s first and last name with a space between the values, the XPath of the Nested Placeholder can be updated to:  

/concat(//author/first-name, " ", //author/last-name)

If you have examples or questions regarding XPath queries within Document Composition, please let us know.

[View:/community/cfs-file/__key/communityserver-blogs-components-weblogfiles/00-00-00-95-92/4.1_5F00_XPathExpressionsSampleXML.xml:320:240]