XPath is a query language for selecting nodes from an XML document. It is based on a tree representation of the XML document and provides the ability to navigate around the tree, selecting nodes by a variety of criteria.
Included in this document there are two files which can be used to experiment:
- sample.xml
- XPath Tester.composition
This document demonstrates how to use XPath expressions (in the following just called "XPath") with a simple XML file. To learn some XML basics, below each important line is commented:
<?xml version="1.0" encoding="UTF-8"?> <!-- XML declaration -->> <data> <!-- root element node -->> <names format="full_names"> <!-- "names" node with "format" attribute -->> <name>John Doe</name> <!-- some random names -->> <name>Jane Hirschkuh</name> <name>Joe Sixpack</name> </names> <!-- closing tag for the "names" node -->> <numbers> <!-- "numbers" node -->> <number>32.1</number> <number>2005.28</number> </numbers> <!-- closing tag for the "numbers" node -->> </data> <!-- closing tag for the root element node -->>
In the XPath query language you select nodes by using path-like expressions. Here's a very simple XPath for the XML file seen above:
/data/names/name[2]
This XPath expression would return "Jane Hirschkuh". The XML tree is being traversed like this:
- Select the "data" node
- Select the "names" node
- Select the second element of the "names" node
Before continuing, try to remove the "[2]" at the end of the XPath used above. You will see that the output contains the 'raw' content of all "name" nodes.
For more complete tutorials on XPath you can visit http://www.w3schools.com/XPath
Using XPath expressions in composition:builder
This part contains a small introduction in using XPath expressions in ToolsOnAir's composition:builder. Please note that it is absolutely required to set the proper path to the XML file in the composition before you continue. The process is also described below.
Open the "XPath Tester" composition in composition:builder (at least version 3.7). This composition contains one element called "XML Text". Such elements can also be created by clicking on the "Text" components toolbar icon and then selecting "XML Text".
There are two variants of the "XML Text" component: The "normal" and "no caching" version. Use the cache-less version for time-critical situations where data changes frequently. Please be aware that multiple of cache-less "XML Text" elements may have a major impact on the buffer of just:out. Use a fast machine and solid-state drives if you need several cache-less elements.
| Follow these steps:
Instead of entering the full path to the XML file by hand, you could also click on the "…" button next to the "XML URL" field and directly drop the XML file into the text field which pops up. After doing so press the "OK" button. |
Notes
- The "Refresh Period" attribute can be used to define how often the content of the specified XML file is being "reloaded". By default this setting is set to 60 seconds. Lower it to achieve a faster readout of the XML file but be aware that this also can have an impact on the just:out buffer status – depending on the number of "XML Text" elements you have inside of your composition
- The "XML URL" attribute accepts local and network files. It is strongly recommended to use local files, unless you have a properly configured and mounted network location. If you should choose to access a network location, make sure to do in-depth testing of the composition (in Composition Builder as well as in the playout software). Cross-platform file sharing and network protocols are neither under control of ToolsOnAir nor Composition Builder.
- Generally the "XML Text" component reflects changes on the XPath immediately. If nothing is displayed at all it is usually due to a malformed XPath expression. Double check your XPath expression syntax. If in doubt, use some free online XPath tester like this one: http://www.freeformatter.com/xpath-tester.html