What is included?

·                XPATH XML search extension to Flash XML object

·                XMLScope tool for interactive learning & testing of XPATH expressions

·                Sample application [.fla] illustrating usage of XMPower

·                Utilities for XML debug, manipulation & conversion to string and number arrays

·                Advanced string manipulation routines

·                Sample XML file

Why do I need this?

·                Searching and unpacking information from an XML tree into Flash (Action Script [AS]) friendly data structures is cumbersome work.

·                Deep complex XML structures require lengthy complex AS functions to extract the relevant data. XPATH expressions allow one to use a single statement to extract the data you want.

·                AS script writers should realize major savings from decreased time debugging AS scripts and faster development cycles.

Simple XPATH examples

Given the following XML document:

<book style="novel">

    <author>Fred Smith</author>

</book>

The search: book/author executed from the document root will result in: Fred Smith

The search: @style executed from the document root will result in: novel

The search: author executed from the book node will result in: Fred Smith

For more information on XML see: W3Schools.com and For more information on XPATH see: ZVON.org or visit the W3.org site.

Purchase information            

This software is provided as shareware. Please support the out-of-work Ph.D. who wrote this tool by paying for it. XMPower is available in two forms:

Developer

Purchase now

$25

Unlimited usage by one developer to use for internal exploration on non-public intranet sites. However, a production license is required if the intranet application is being used to support internal operations

Production

Purchase now

$100

Allows unlimited usage in one internal, external, or client funded application. This means that if a client contracts you for $10K to build a flash front end to an xml-powered eBiz site, you will be able to add XMPower for less than 0.1% of the total cost. We believe that you will find that using XMPower is much cheaper than writing the XML extraction code yourself.

Client Requirements

Flash Client (Player or ActiveX control) must be version 6.0 or greater.

Action script API

XMPower.onLoad()

When the XMPower .swf movie is fully loaded it will call _root.boot() to indicate that XMPower is ready. You may also specify the load callback to be something other that _root.boot(). For example, the following code snippet shows how to do a load that will call myMovie.xmlReady():

aMovie.loadMovie("xmpower.swf?LoadCallback="+escape("myMovie.xmlReady"));

XMLNode.selectNodes(xpath)

Returns a list [1-D Array] of XML nodes from the XML tree that match the XPATH expression [String]. XMLNode can either be an XML document (created by new XML())  or an child node of the XML tree. If the XPATH search is for a XML attribute (e.g. @style) then the search will return a string array, since this is how Flash represents attributes.

If there is an error in parsing the XPATH expression then a single String object with the error message is returned. Apply the following test to see if an error occurred in the .selectNodes() method:

if (returnedNodeList instanceof String) {…}

XMPower.asText(nodeList)

This method can be used to convert the node list returned by the selectNodes() call. It takes the 1-D nodeList Array and returns a 1-D Array of strings. It assumes that the nodeList consists of leaf XML nodes. That is, each element in nodeList has no children except for text nodes.

XMPower.asNumber(nodeList)

This method can be used to convert the node list returned by the selectNodes() call. It takes the 1-D nodeList Array and returns a 1-D Array of Numbers [Float,Int]. It assumes that the nodeList consists of leaf XML nodes. That is, each element in nodeList has no children except for text nodes which contain only numeric values.

XMPower.dumpNode(node)

This method retuns a printable string which contains information about the XML node. Information includes: nodeName, nodeValue, attributes, children, and XML string.

XMPower.replace(source, pattern, newString, occurrences)

String replace utility. Searches for pattern string in source string, and if found, replaces it with the newString. Replace is non-destructive. The optional occurrences parameter can be used to limit how many replacements to do.

XMLNode.replaceNode(node)

This method can be used to do an in-place replacement of a node. The target XML node is removed and the new node is placed in the same location in the tree.

XMLScope Application

Notes: bookstore.xml is pre-loaded at application start but you may load new XML files at any time.

Support

We encourage bug reports and we will do our best to fix them, however the software is provided on an "as-is" basis with no obligation to provide support. Email: Kesser Tech Support.

Special XMPower Features

·                Makes searching in XML in Flash easy.

·                Fully compiles XPATH expressions for rapid searching.

·                Turbo-charged for speedy simple searches.

·                Handles 80% of normal XPATH expressions

Usage Tips

To improve performance: limit wildcard (*) & recursive (//) search terms and increase use of simple expressions (/xxx)

If searching very large (>10MB) XML documents and you get "Flash is running slowly" messages, try breaking the search into two or more parts.

Modify the XML tree by first searching for the desired node(s), then use .replaceNode() to change the XML tree in place.

Example usage of XMPower

this.loadMovie("XMPower.swf");

// after _root.boot() is called then ...

new xdoc = nex XML();

xdoc.onLoad = loadDone;

xdoc.load("myfile.xml");

// after loadDone()

nodeList = xdoc.selectNodes("/bookstore/book");

if (nodeList instanceof String) {

 ... showError(nodeList)

} else{

    for (var i=0; i<nodeList.length; i++)

       { ... }

}

Example supported XPATH expressions:

All the below examples use the sample bookstore.xml file at the bottom of this page.

Find all book elements starting from current node:

book

Find all author elements starting from current node:

book/author

Find all author elements starting from the document root:

/bookstore/book/author

Find all author elements that are children (at any level) of the current node:

//author

Find all bookstores where the value of the specialty attribute is equal to "textbooks":

/bookstore[@specialty = "textbooks"]

Find all first-name elements within an author element:

author/first-name

In the above example, note that the author children of the current node are found, and then first-name children are found relative to the current node of the author elements.

Find all title elements one or more levels deep in the bookstore (arbitrary descendants):

bookstore//title

Note that the above is different from the following pattern, which finds all title elements that are grandchildren of bookstore elements:

bookstore/*/title

Find emph elements anywhere inside book excerpts, anywhere inside the bookstore:

bookstore//book/excerpt//emph

Find all element children of author elements:

author/*

Find all last names that are grandchildren of books:

book/*/last-name

Find the grandchildren elements of the current node:

*/*

Find the book element from the "my" namespace:

my:book

Find all elements with the specialty attribute:

*[@specialty]

Find the style attribute of the current element node:

@style

Find the exchange attribute on price elements within the current node:

price/@exchange

The following example does not return anything, because attributes do not contain element children. It is allowed by the XML Path Language (XPATH) grammar, but is not strictly valid:

price/@exchange/total

Find all books with style attributes:

book[@style]

Find the style attribute for all book elements:

book/@style

Find all attributes of the current element node:

@*

Find all books that contain at least one excerpt element:

book[excerpt]

Find all titles of books that contain at least one excerpt element:

book[excerpt]/title

Find all authors of books where the book contains at least one excerpt and the author has at least one degree:

book[excerpt]/author[degree]

Find all author elements that contain a last-name element with the value Bob:

author[last-name = "Bob"]

Find all authors whose text is "Matthew Bob":

author[. = "Matthew Bob"]

Find all authors whose style attribute is "novel":

author[@style = "novel"]

Find all elements which contain the text “novel":

//*[. = "novel"]

Find all author elements containing any child element whose text is "Bob":

author[* = "Bob"]

Find all children elements regardless of depth

//*

Example unsupported XPATH expressions:

Most of these unsupported expressions can be accomplished by either one or a sequence of supported XPATH expressions.

author[1]

XMPower alternative solution: First search for author, then select the first item in the nodeList array.

book[last()]

XMPower alternative solution: Search for book, and get nodeList[nodeList.length-1]

book[excerpt][title]

XMPower alternative solution: Concatenate the result nodeList arrays of book[excerpt] with book[title]

author[degree and award]

degree[@from != "Harvard"]

author[last-name = /guest/last-name]

author[last-name &gt; "M"]

author[last-name = "Bob" and first-name = "Joe"]

degree[position() &lt; 3]

ancestor::book[1]

Sample bookstore.xml file

<?xml version="1.0"?>

<bookstore specialty="novel">

     <book style="autobiography">

           <author>

                <first-name>Joe</first-name>

                <last-name>Bob</last-name>

                <award>Trenton Literary Review Honorable Mention</award>

           </author>

           <price>12</price>

     </book>

     <book style="textbook">

           <author>

                <first-name>Mary</first-name>

                <last-name>Bob</last-name>

                <publication>Selected Short Stories of

        <first-name>Mary</first-name>

                      <last-name>Bob</last-name>

                </publication>

           </author>

           <price>55</price>

     </book>

     <magazine style="glossy" frequency="monthly">

           <price>2.50</price>

           <subscription price="24" per="year"/>

     </magazine>

     <book style="novel" id="myfave">

           <author>

                <first-name>Toni</first-name>

                <last-name>Bob</last-name>

                <degree from="Trenton U">B.A.</degree>

                <degree from="Harvard">Ph.D.</degree>

                <award>Pulitzer</award>

                <publication>Still in Trenton</publication>

                <publication>Trenton Forever</publication>

           </author>

           <price intl="Canada" exchange="0.7">6.50</price>

           <excerpt>

                <p>It was a dark and stormy night.</p>

                <p>But then all nights in Trenton seem dark and

      stormy to someone who has gone through what

      <emph>I</emph> have.</p>

                <definition-list>

                      <term>Trenton</term>

                      <definition>misery</definition>

                </definition-list>

           </excerpt>

     </book>

     <my:book xmlns:my="uri:mynamespace" style="leather" price="29.50">

           <my:title>Who's Who in Trenton</my:title>

           <my:author>Robert Bob</my:author>

     </my:book>

     <book xmlns="uri:realspace.org" style="leather" price="29.50">

           <title>Who's Who in Trenton</title>

           <author>Robert Bob</author>

           BookTextTest

           <first.name>Robert</first.name>

     </book>

</bookstore>