Flash 8 has delivered the ability to do simple searches for node names and attribute values in an XML file with its new XPathAPI class. Kris Hadlock shows how to use the XPathAPI in Flash 8 to simplify and give power to your XML parsing.

XML has bridged the gap between technologies and added a lot of power to Flash, allowing it to be more dynamic and flexible for building large applications. XML in Flash has been a possibility since Flash 5 with ActionScript 1, and significantly improved when it became a native object in Flash Player 6 with the introduction of ActionScript 2. But along with all of this power came certain limitations that don't exist in more complete programming languages. One huge difference was that there had been no implementation of the XPath in Flash, but this situation finally changed with the release of Flash 8. The native XPathAPI object in Flash 8 provides the capabilities to do simple searches for node names and attribute values in an XML file.

This article explains how to use the XPathAPI in Flash 8 to make your XML parsing extremely easy. We'll explore the available methods and the many different ways to search your XML files. Let's get started with an understanding of the methods available through the XPathAPI.

Introduction to the XPathAPI Object

Perhaps the most interesting thing about the XPathAPI is that it has been available since Flash version, but it was undocumented and could only be accessed through the DataBindingClass by adding the component to your movie. This also happens to be the way that the help documentation in Flash 8 explains how to use the class, but you no longer have to add the DataBindingClass to your file; all you have to do is add an import statement for the XPathAPI as follows:Or you could call specific methods with the full path to the object plus the method name, like so:Because the XPath methods have been available since version 6 of Flash, the code is compatible with Flash Player 6 (6.0.79.0). This means that you can create backwardly compatible projects and still make use of the XPathAPI methods, a small set that packs quite a bit of power:

• XPathAPI.getEvalString(node, path);
• XPathAPI.selectNodeList(node, path);
• XPathAPI.selectSingleNode(node, path);
• XPathAPI.setNodeValue(node, path, nodeValue)
  

The getEvalString method takes two parameters, a node and a path, and returns code as a string that would be required to target this node using standard XML parsing. It's useful when you're uncertain of the depth of a node and you want to see where it is in relationship to other nodes in an XML file.

The selectNodeList and selectSingleNode methods take the same two parameters, a node and a path. The path is used to search from the node location that was passed as the first parameter. For selectNodeList, it will return all the matching nodes as an array, whereas selectSingleNode returns the first matching node on its own. These methods are very powerful and can be manipulated to search for many different elements in an XML file, as we'll see in the next section.

The setNodeValue method takes the same two parameters, a node and a path, with the addition of a nodeValue parameter that replaces the value of the node once it's found. As you can imagine, these methods make XML parsing extremely easy and can be used to create more advanced searches, which we'll learn about shortly.

Example

The following example is a very small XML file that I wrote so that we could spend our time parsing it with XPath:Before we start parsing this XML, we need to create a Flash file that will import the XPathAPI class and load the XML. Once you have a Flash movie created, write the following code:Now that we have the code in place, we can start parsing with the XPathAPI. Let's get started!

Search Examples

There are many ways to search for elements with the methods that are provided by the XPathAPI class. There are also many ways to combine search strings to do more advanced searches in your XML files. The most common way to search for elements is with an absolute path. Following are examples of each method using an absolute path:
As a shortcut to retrieve the value of an item using the selectSingleNode method, you could append code to the end, like so:To retrieve an attribute's value, you could use the following:To use a relative path, you have to start at the parent node of the element that you're searching for. The following two examples could accomplish this functionality:A great way to find all the matching node names without worrying about the path or the parent node is by adding a wildcard. This can be achieved by using the following code:The wildcard is useful if you want to change the values of all the nodes with the name that you're searching. In the example, we would change all of the node elements values to "new value". Another use for the wildcard is in the selectNodeList method: You can retrieve all of the elements by name without knowing the path or parent.

For advanced searches, you can combine different search methods. For example, wildcards can be combined with an attribute search:

Conclusion

As you can see, the XPathAPI is an extremely useful class and is a great addition to the existing XML functionality in Flash. Take the samples provided in this article and combine them to create any search that you need to accomplish. They'll make your XML parsing extremely easy.