JavaScript APIThe XML tree is mapped into the JavaScript environment as a hierarchy of JavaScript
objects. Full details of the API are documented
here. This
section provides a very simple overview. The core class is the
XmlParser. An instance of this
is used to build the Presentation Page itself - and is available as
rb.xml. So - for example - you can find the root of the
Presentation Page XML tree as rb.xml.root - which is an instance of
XmlTag. You can create your own parser in JavaScript and then use that parser to build an XML tree from
a source XML document. Example:
// Create a parser.
var aParser = new XmlParser;
// Load some XML from - in this case - a file.
var data = new Binary;
data.load("finename.xml");
// Build the XML tree. If there are no errors then the method
// returns the root of the tree. If there are errors then
// null is returned and the errors are available as
// 'aParser.errors[]'.
if (aParser.build(data)) {
// If the XML built with no errors then you get to this point.
}
else {
// If there are errors in the XML - you get here
// and you can look at the errors in aParser.errors.
}
Once the tree has been built - you can execute it - or investigate the basic structure. Usually you would execute the
tree once - but at times you would execute a subtree - say that satisfies some specific request
such as displaying a section of a document. The XmlTag class is the most important to the structure of the document - since it basically is responsible for
building that structure! The class itself has a set of named properties and a set of numbered properties. The
numbered properties allw the object to be treated as a numeric array - each numeric subscript is a child
XML element ofthe tag. So - conside the following simple XML document:
<html>
<head>
<title>My Title</title>
</head>
<body>
<h1>Hello World</h1>
<p align="left">Text</h1>
<p align="right" name="fred">Text</h1>
</body>
</html>
If this is compiled with aParser then 'aParser.root' is a virtual XmlTag - it is NOT one of the elements
in the document. Instead it is an un-named tag that contains as it's children the contents of the document.
So in this example aParser.root[0] will be the <html> tag. The structure is recursive and so
aParser.root[0][0] is the <head> tag, aParser.root[0][1] is the body tag. The Whitebeam environment provides several powerful mechanism for searching the XML tree
to find sub-trees of interest. The simples is to simply search for an element with a specific tag-name.
For example:
var bodyTag = aParser.root.find("body");
Will return a JavaScript array of all the tags with this name 'body'. In this example this
will yield an array with a single element - the body tag from the sample document. Whitebeam also allows much more sophisticated searching using the
XPath query mechanism
as defined by the W3C. This allows both the searching
and extraction of data from the tree. So for a simple example - conside the following query:
var tagSet = aParser.root.xpath("//p[@align='left']");
Will return all XML tags with an align attribute - the value of which is 'left'. Again - in this example this will
return a set of nodes comprising the simgle matching element in the document. Note that the xpath method
represents sets of XML elements as a instance of an
XmlNodeSet class.
XmlNodeSets are specialisations of the basic JavaScript Array - with the added benefit that yo can do do
XPath queries on the result. See the separate XPath tutorial for more information. |