sunlabs.brazil.sunlabs
Class XmlTreeTemplate

java.lang.Object
  extended by sunlabs.brazil.template.Template
      extended by sunlabs.brazil.sunlabs.XmlTreeTemplate (view source)
All Implemented Interfaces:
TemplateInterface

public class XmlTreeTemplate
extends Template

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.
   ignoreUnknown:
                if true, all unknown tags will be completely ignored, 
                and treated as "cdata" tacked on to the previous tag.

 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
 


Field Summary
 
Fields inherited from class sunlabs.brazil.template.Template
debug
 
Constructor Summary
XmlTreeTemplate()
           
 
Method Summary
 void tag_xmltree(RewriteContext hr)
           
 
Methods inherited from class sunlabs.brazil.template.Template
done, init
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XmlTreeTemplate

public XmlTreeTemplate()
Method Detail

tag_xmltree

public void tag_xmltree(RewriteContext hr)

Version Kenai-svn-r24, Generated 08/18/09
Copyright (c) 2001-2009, Sun Microsystems.