Manage a tree representation of an XML document.
The xml document is manipulated via the "xmltree" tag. the "content"
of the tree is retrieved by "flattening" the tree and accessing its contents
as name/value pairs.
Attributes:
src: the source file for this template, relative to the doc root
eval: process source file through subst()
root: where to lookup the template file
xml: The source xml, if "src" is not specified
This may be used if the "xml" resides in a property
name: the name (and prefix) of the tree thingy
delim: which delimeter to use (defaults to ".")
default: what to use as the default "suffix" (defaults to "cdata")
attribute: If not "", it specifies an attribute to use to name a
particular node. If an attribute is specified, and multiple
nodes have the same name, then all nodes in the tree may not
be uniquly identifiable.
dflt: The value to use if attribute is specified, but the node doesn't
have one (defaults to "unknown").
namespace: which namespace to use. If not specified,
the property [prefix].namespace is used, where [prefix]
is RewriteContext.templatePrefix. Otherwise the sessionID is
used.
tags: The list of xml tags to be processed. All tags not on this
list are considered to be "singletons". tags="" clears the
list, and all tags will be processed.
Portions of the tree are accessed using ordinary BSL variable, whos names
map to elements of the tree. The variables have the form:
name.path.suffix, where:
- name is the name of the tree
- path is the path name of a particular node
- suffix indicates which aspect of the node is returned. See below
for the list of suffixes.
The "." which separates the name, path, and suffix, as well as
the elements within the path may be changed to another character
with the "delim" attribute.
Nodes are identified by their path name, which is the "delim" separated
list of node names, starting from the root node. The node names, which
identify a particular node in the tree, are configurable using
"attribute" attribute. By default, a node is named by:
tag(index), where "tag" is the xml tag, and "index" is the index of
that tag witin its parent, starting from 0.
The suffix may be one of:
- cdata Returns the plain text between this tag and the next
one. Since closing tags (e.g. ) are not
considered nodes in the tree, any "cdata" after
a closing tag is associated with the previous tag.
- tag The name of the current tag
- index The index of this tag within its parent.
- attributes A space delimited list of attribute names associated
with this node
- children A space delimited list of direct child node names
for this node.
- childCount The number of direct child nodes
- [attribute].value The value of [attribute], if it exists
- all A space delimited list of all decendants of this
node (including this node)
- glob A space delimited list of all nodes whos names match
the supplied glob pattern [broken]
Examples:
Consider the following XML snippet in the file called sample.xml:
<sample name="main" a="1" b="2">
<part name="shoe" price="17">hard soles</part>
<part name="hat" price="11">Green, with feathers</part>
</sample>
<order name="joe">
<description>
This is a description of the order
</description>
<payment name="ante up" method="cash" amount="28" />
</order>
The following tags should cause the indicated variables to "exist" with
the values shown:
<xmltree name=tree src=sample.xml>
tree.all= tree.sample(0) tree.sample(0).part(0) tree.sample(0).part(1) tree.order(0) tree.order(0).description(0)
tree.order(0).payment(0)
tree.order(0).description(0).cdata = This is a description of the order
tree.order(0).description(0) = This is a description of the order
[the default suffix is "cdata"]
tree.sample(0).children = part(0) part(1)
sample(0).all = tree.sample(0) tree.sample(0).part(0) tree.sample(0).part(1)
sample(0).part(0) = hard soles
sample(0).part(0).attributes = name price
sample(0).part(0).price.value = "17"
sample(0).childCount = 2
<xmltree name=tree delim=: attribute=name>
[ since src=sample.xml is already defined, it isn't required]
all = tree:"main" tree:"main":"shoe" tree:"main":"hat" tree:"joe" tree:"joe":unknown tree:"joe":"ante up"
"main":"shoe" = hard soles
"main":"shoe":price:value) = "17"
<xmltree name=tree delim=. attribute=name default=children>
sample(0) = part(0) part(1)
When combined with the BSLTemplate, the "foreach" tag may be used
to iterate through all the node names, in which case the default
value (e.g. cdata) is used.
If the XML is invalid, the property "name".error is set to a hopefully
useful error message