Using XPath in composition:builder

Owned by Thomas Staiger
Last updated: Nov 28, 2017
3 min read

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. This document demonstrates how to use XPath expressions (in the following just called "XPath") with a simple XML file. 

Before you Begin

Before you begin please download the sample files: XPath Tester.zip

XML Basics

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:

  1. Select the "data" node
  2. Select the "names" node
  3. 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.


  1. 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".
  2. Select the XML Text element in the Timeline.
  3. Open the Inspector and go to the XML URL attribute.
  4. Enter the full (!) path to the sample.xml file in this field. If you should ever move the XML file after setting the path in the composition, you need to readjust the XML UR" attribute accordingly.
  5. Press the Play button for a short period of time or change the XPath attribute. Changes should now be reflected immediately.
  6. 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.

 

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.

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

 

→ Use the sidebar to navigate.