[xmlnodes ref=...&path=...&name=...&exact=T/F] <WebDNA>[/xmlnodes]

Parameters:

· ref - Reference to an xml parsed object variable. If this parameter is not provided, then it is assumed that there is an 'outer' [xmlnodes] context from which to reference a particular XML node. (This is explained further on in this tutorial).

· path - Depending on which path method is used (see below), this will either be a path to the parent xml element (node) from which to iterate the child elements (nodes), or a path 'expression' representing a collection of XML nodes. If a path is not provided, then the child nodes of the 'ref' node will be iterated

· name - A string used to filter the resulting xml nodes. Only the xml nodes that match the 'name' string will be iterated.

· exact - Used with the 'name' parameter. Either 'T' or 'F'. Specifies whether the 'name' parameter is a 'whole' string match or a 'sub-string' match.

Context Tags available from within the [XMLNodes] Context:

· [name] - The name of the current iterated XML node.

· [value] - The value of the current iterated XML node. Will be empty if the node is a 'container' node, i.e. contains other XML nodes.

· [index] - The 'count' of the current iterated node.

· [numfound] - The total 'count' of iterated nodes.

· [content] - The 'raw' xml content of the current node.

· [iscontainer] - 'T' if the current node contains other XML nodes.

The default behavior of this context is to iterate the child XML nodes of a parent node. The location of the parent node, in the xml 'tree', is determined by the 'path' parameter. If a path parameter is not provided, then the child nodes of the ' ref 's root are iterated.

The path parameter can take three different forms: 'named:', 'indexed:', or 'xpath:'.

- The 'named:' method expresses a literal path to the parent node, i.e. 'path=named:CATALOG/CD(n)'. If there are more than one similarly named 'sibling' nodes, then the '(n)' part specifies which node to select as part of the path.

- The 'indexed:' method expresses an numerical 'step' wise path to the parent node, i.e. 'path=indexed:1/2/3'. This example could be expressed as: 'The third child node of the second child node of the first child node of the xml root'.

- The 'xpath:' method is an XPath 'expression' that evaluates to a collection of nodes in the XML tree. In this case, the iterated nodes are those of the resulting 'collection' of nodes. This is a bit different from the 'named' and 'indexed' method in that the collection of node are not the 'child' nodes of a given 'parent' node. This is the most powerful method for selecting XML nodes. There are several online 'xpath' tutorials that you can visit that will help you develop your XPath skills.

We will be using the 'named' method in the next few tutorial pages.

Now lets use the [xmlnodes] context to iterate the xml child nodes of the root xml node of the 'example1.xml' document.

The code is as follows...

[xmlparse var=xml_var1][include file=example1.xml][/xmlparse]

[xmlnodes ref=xml_var1]
[name]=[value]

[/xmlnodes]

Results....

CATALOG=

We see that the 'CATALOG' node is the only child node from the root of the xml file. Notice that the 'value' is empty. This is because the 'CATALOG' node has no value, and is actually a 'container' node for other xml nodes. So a 'value' will only be displayed for a 'leaf' xml node, i.e.

JOHN

In this case, [name] would evaluate to 'FIRSTNAME' and [value] would be 'JOHN'.

Lets dive a little deeper into the xml file and iterate the 'child' nodes of the root 'catalog' node of the example1.xml file...

We now use...

[xmlparse var=xml_var1][include file=example1.xml][/xmlparse]

[xmlnodes ref=xml_var1&path=named:Catalog]
[name]=[value]

[/xmlnodes]

Results....

CD=
CD=
CD=
CD=
CD=

We see that we have iterated all the 'CD' child nodes of the 'Catalog' parent node. Again, none of the resulting child nodes contain a value as they are all 'container' nodes.

You can embed any number of [xmlnodes] contexts within each other. Lets do this to iterate the child nodes of all the 'CD' nodes of the example1.xml file...

We use...

[xmlparse var=xml_var1][include file=example1.xml][/xmlparse]

[xmlnodes ref=xml_var1&path=named:Catalog]
[name] - [index]

[xmlnodes]
- [name]=[value]

[/xmlnodes]
[/xmlnodes]

Results....

CD - 1
- TITLE=Empire Burlesque
- ARTIST=Bob Dylan
- COUNTRY=USA
- COMPANY=Columbia
- PRICE=10.90
- YEAR=1985
CD - 2
- TITLE=Hide your heart
- ARTIST=Bonnie Tylor
- COUNTRY=UK
- COMPANY=CBS Records
- PRICE=9.90
- YEAR=1988
CD - 3
- TITLE=Greatest Hits
- ARTIST=Dolly Parton
- COUNTRY=USA
- COMPANY=RCA
- PRICE=9.90
- YEAR=1982
CD - 4
- TITLE=Still got the blues
- ARTIST=Gary More
- COUNTRY=UK
- COMPANY=Virgin records
- PRICE=10.20
- YEAR=1990

Now we are getting some interesting results. Note that the 'inner' xmlnodes context did not need a 'ref' parameter. This is because the inner xmlnodes context inherited the outer xmlnodes' current iterated node. Also notice that the inner xmlnodes context did not use a 'path' parameter. So it uses the 'root' path of the outer xmlnodes' current iterated node.

Did you also notice the use of the [index] tag in the outer xmlnodes context? As with most 'iterative' WebDNA contexts, the [index] tag resolves to the current iteration 'count'.

Lets refine the named path parameter to go directly to a particular 'CD' node.

With a minor change to the 'path' parameter, we can retrieve all the child nodes of the fifth 'CD' node of the example1.xml file...

[xmlparse var=xml_var1][include file=example1.xml][/xmlparse]

[xmlnodes ref=xml_var1&path=named:Catalog/CD(5)]
[name]=[value]

[/xmlnodes]

Results....

TITLE=Eros
ARTIST=Eros Ramazzotti
COUNTRY=EU
COMPANY=BMG
PRICE=9.90
YEAR=1997

Using the 'name' parameter we can filter the results to display only the 'TITLE' node of the fifth 'CD' node of the example1.xml file...

[xmlparse var=xml_var1][include file=example1.xml][/xmlparse]

[xmlnodes ref=xml_var1&path=named:Catalog/CD(5)&name=TITLE]
[name]=[value]

[/xmlnodes]

Results....

TITLE=Eros

Using the 'name' and 'exact' parameters, we can filter the results to display only those nodes, of the fifth 'CD' node, where the node name matches a given sub-string, 'CO' of the example1.xml file...

[xmlparse var=xml_var1][include file=example1.xml][/xmlparse]

[xmlnodes ref=xml_var1&path=named:Catalog/CD(5)&name=CO&exact=F]
[name]=[value]

[/xmlnodes]

Results....

COUNTRY=EU
COMPANY=BMG

[xmlnode ref=...&var=...&path=...]<WebDNA>[/xmlnode]

Parameters:

· ref - Reference to an xml object variable. If this parameter is not provided, then it is assumed that there is an 'outer' [xmlnode/s] context from which to reference a particular XML node.

· var - User defined name for this persisted node instance. If this parameter is not provided, then this node instance will not be persisted

· path - Path to the desired XML node. If an XPath expression is used, it should evaluate to a single node.

WebDNA Tags available from within an [xmlnode] context...
· [name] - The name of the XML node.

· [value] - The value of the XML node. Will be empty if the node is a 'container' node, i.e. contains other XML nodes.

· [content] - The 'raw' xml content of the node.

· [iscontainer] - 'T' if the current node contains other XML nodes.

This context is used to retrieve the contents of the specific node. The 'path' parameter is used to locate the node. As with the [XMLNodes] context, the 'path' parameter has three modes; 'named:', 'indexed:', and 'xpath:'. [XMLNode] can also be used to persist a 'pointer' to a specific node. This reference can then be used in subsequent calls to other XML contexts.

Lets use the XMLNode context to retrieve the TITLE information of the third CD node of the example1.xml file....

Code used...

[xmlparse var=xml_var1][include file=example1.xml][/xmlparse]

[xmlnode ref=xml_var1&path=indexed:1/3/1]
[name]=[value]

[/xmlnode]

You'll notice that we used the 'indexed' path method. This is because we have explicit knowledge of the XML file, and can there for use the indexed method to jump quickly to the desired XML node.

Results...

TITLE=Greatest Hits

Now lets use the [XMLNode] context to persist a reference to the third 'CD' node, then use that reference in an XMLNodes context to retrieve the child nodes of the example1.xml file...

Code used...

[xmlparse var=xml_var1][include file=example1.xml][/xmlparse]

[xmlnode ref=xml_var1&path=indexed:1/3&var=xml_CD3][/xmlnode]

[xmlnodes ref=xml_CD3]
[name]=[value]

[/xmlnodes]

Results...

TITLE=Greatest Hits
ARTIST=Dolly Parton
COUNTRY=USA
COMPANY=RCA
PRICE=9.90
YEAR=1982