<?xml version="1.0" encoding="UTF-8"?>
<section>
          <sectioninfo>
                    <keywordset>
                              <keyword>presentation of data</keyword>
                              <keyword>rich:tree</keyword>
                              <keyword>HtmlTree</keyword>
                    </keywordset>
          </sectioninfo>

          <table>
                    <title>Component identification parameters </title>
                    <tgroup cols="2">
                              <thead>
                                        <row>
                                                  <entry>Name</entry>
                                                  <entry>Value</entry>
                                        </row>
                              </thead>
                              <tbody>
                                        <row>
                                                  <entry>component-type</entry>
                                                  <entry>org.richfaces.Tree</entry>
                                        </row>
                                        <row>
                                                  <entry>component-class</entry>
                                                  <entry>org.richfaces.component.html.HtmlTree</entry>
                                        </row>
                                        <row>
                                                  <entry>component-family</entry>
                                                  <entry>org.richfaces.Tree</entry>
                                        </row>
                                        <row>
                                                  <entry>renderer-type</entry>
                                                  <entry>org.richfaces.TreeRenderer</entry>
                                        </row>
                                        <row>
                                                  <entry>tag-class</entry>
                                                  <entry>org.richfaces.taglib.TreeTag</entry>
                                        </row>
                              </tbody>
                    </tgroup>
          </table>

          <section>
                    <title>Creating the Component with a Page Tag</title>
                    <para>There are two ways to set up a tree</para>
                    <itemizedlist>
                              <listitem>
                                        <para>Using model (<code>org.richfaces.model.TreeNode</code>
                                                  or <code>javax.swing.tree.TreeNode</code>) </para>
                                        <para>
                                                  <emphasis role="bold">Example:</emphasis>
                                        </para>
                                        <programlisting role="XML"><![CDATA[...
<rich:tree value="#{library.data}" var="item" >
    <rich:treeNode  icon="/images/tree/singer.png" >
        <h:outputText value="#{item.name}" />
    </rich:treeNode>
    ...
</rich:tree>
...]]></programlisting>

                              </listitem>
                              <listitem>
                                        <para> Using model tags <emphasis role="bold">
                                                  <property>&lt;rich:recursiveTreeNodesAdaptor&gt;</property>
                                                  </emphasis>, <emphasis role="bold">
                                                  <property>&lt;rich:treeNodesAdaptor&gt;</property>
                                                  </emphasis>. </para>
                                        <para>
                                                  <emphasis role="bold">Example:</emphasis>
                                        </para>
                                        <programlisting role="XML"><![CDATA[...
<rich:tree>
    <rich:recursiveTreeNodesAdaptor roots="#{fileSystemBean.sourceRoots}" var="item" nodes="#{item.nodes}" />
</rich:tree>
...]]></programlisting>
                              </listitem>
                    </itemizedlist>
          </section>
          <section>
                    <title>Creating the Component Dynamically Using Java</title>

                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="JAVA"><![CDATA[import org.richfaces.component.html.HtmlTree;
...
HtmlTree myTree = new HtmlTree();
...]]></programlisting>
          </section>

          <section>
                    <title>Details of Usage</title>
                    <para> As it has been mentioned <link linkend="tree">above</link> the <emphasis
                                        role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> component allows rendering any tree-like data model. </para>
                    <para> You can build your <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> using model (<code>org.richfaces.model.TreeNode</code> or
                                        <code>javax.swing.tree.TreeNode</code>). In this case the
                                        <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> component interacts with data model via
                                        <code>&quot;TreeNode&quot;</code> interface (<ulink
                                        url="http://labs.jboss.com/file-access/default/members/jbossrichfaces/freezone/docs/apidoc_framework/org/richfaces/model/TreeNode.html"
                                        > org.richfaces.model.TreeNode </ulink>) that is used for
                              the <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> nodes representation. </para>
                    <para> Actually you can develop and use your own implementation of the
                                        <code>&quot;TreeNode&quot;</code> interface or use a
                              default one, which is defined with a default class
                                        <code>&quot;TreeNodeImpl&quot;</code> (<ulink
                                        url="http://labs.jboss.com/file-access/default/members/jbossrichfaces/freezone/docs/apidoc_framework/org/richfaces/model/TreeNodeImpl.html"
                                        > org.richfaces.model.TreeNodeImpl </ulink>). </para>
                    <para> The <emphasis>
                                        <property>&quot;value&quot;</property>
                              </emphasis> attribute of the <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> component contains a nodes structure defined in a bean
                              property. </para>
                    <para> When the <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> component is being rendered it iterates over the model
                              nodes and renders them using one of its <property>immediate</property>
                              <emphasis role="bold">
                                        <property>&lt;rich:treeNode&gt;</property>
                              </emphasis> children. Data property of the current model
                                        <code>TreeNode</code> is exposed using <emphasis>
                                        <property>&quot;var&quot;</property>
                              </emphasis> attribute, so if
                                        <code>var=&quot;station&quot;</code> you can refer
                              to that data using <code>#{station}</code> syntax. </para>
                    <para> In the following example the <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> is built from a simple
                                        <code>org.richfaces.model.TreeNode</code> model: </para>
                    <programlisting role="JAVA"><![CDATA[...
private TreeNodeImpl<String> stationRoot = new TreeNodeImpl<String>();
private TreeNodeImpl<String> stationNodes = new TreeNodeImpl<String>(); 
private String[] kickRadioFeed = { "Hall & Oates - Kiss On My List",
	"David Bowie - Let's Dance", "Lyn Collins - Think (About It)",
	"Kim Carnes - Bette Davis Eyes",
	"KC & the Sunshine Band - Give It Up" };
	...	
stationRoot.setData("KickRadio");
stationNodes.addChild(0, stationRoot);
for (int i = 0; i < kickRadioFeed.length; i++){
	TreeNodeImpl<String> child = new TreeNodeImpl<String>();
	child.setData(kickRadioFeed[i]);
	stationRoot.addChild(i, child);
}
...]]></programlisting>
                    <para> As it is mentioned before you need to pass
                                        <code>#{stations.stationNodes}</code> property to the <emphasis>
                                        <property>&quot;value&quot;</property>
                              </emphasis> attribute and define the <emphasis>
                                        <property>&quot;var&quot;</property>
                              </emphasis> attribute in order to refer to the data: </para>
                    <programlisting role="XML"><![CDATA[...
<rich:tree value="#{stations.stationNodes}" var="station">
	<rich:treeNode>
		<h:outputText value="#{station}" />
	</rich:treeNode>
</rich:tree>
...]]></programlisting>
                    <para> This is a result: </para>
                    <figure>
                              <title>A simple <emphasis role="bold">
                                                  <property>&lt;rich:tree&gt;</property>
                                        </emphasis> from a
                                        <code>org.richfaces.model.TreeNode</code></title>
                              <mediaobject>
                                        <imageobject>
                                                  <imagedata fileref="images/treeModel.png"/>
                                        </imageobject>
                              </mediaobject>
                    </figure>

                    <para> Implementation of the <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> component provides another way to build a tree. This
                              approach implies using a
                                        <code>&quot;XmlTreeDataBuilder&quot;</code> class
                                        (<ulink
                                        url="http://labs.jboss.com/file-access/default/members/jbossrichfaces/freezone/docs/apidoc/org/richfaces/component/xml/XmlTreeDataBuilder.html"
                                        > org.richfaces.component.xml.XmlTreeDataBuilder </ulink>)
                              that allows to transform XML into structures of objects containing
                                        <code>&quot;XmlNodeData&quot;</code> (<ulink
                                        url="http://labs.jboss.com/file-access/default/members/jbossrichfaces/freezone/docs/apidoc_framework/org/richfaces/component/xml/XmlNodeData.html"
                                        > org.richfaces.component.xml.XmlNodeData </ulink>)
                              instances as data, which could be represented by the <emphasis
                                        role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> component. </para>
                    <para> Let&apos;s try to build a simple <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> from a local XML file. In the following example a simple
                              XML file (stations.xml) is used as a radio station playlist: </para>
                    <programlisting role="XML"><![CDATA[<?xml version="1.0"?>
<station name="KickRadio">
		<feed date="today">
			<song time="07:00">Hall & Oates - Kiss On My List</song>
			<song time="07:03">David Bowie - Let's Dance</song> 
			<song time="07:06">Lyn Collins - Think (About It)</song>
			<song time="07:10">Kim Carnes - Bette Davis Eyes</song>
			<song time="07:15">KC & the Sunshine Band - Give It Up</song>
		</feed>
</station>]]></programlisting>
                    <para> Now you need to create a bean that holds a model nodes: </para>
                    <programlisting role="JAVA"><![CDATA[...
private TreeNode data;
	...
FacesContext context = FacesContext.getCurrentInstance();
data = XmlTreeDataBuilder.build(new InputSource(getClass().getResourceAsStream("stations.xml")));
...]]></programlisting>
                    <para> Finally you should set the <emphasis>
                                        <property>&quot;value&quot;</property>
                              </emphasis> attribute to the <code>data</code> bean property and
                              define the <emphasis>
                                        <property>&quot;var&quot;</property>
                              </emphasis> attribute in order to refer to the data of nodes: </para>
                    <programlisting role="XML"><![CDATA[...
<rich:tree id="treeXML" value="#{stations.data}" var="vardata">
	<rich:treeNode>
		<h:outputText value="#{vardata.attributes['name']}" />
		<h:outputText value="#{vardata.attributes['date']}" />
		<h:outputText value="#{vardata.attributes['time']}" />
		<h:outputText value=" #{vardata.text}" />
	</rich:treeNode>
</rich:tree>
...]]></programlisting>
                    <para>This is a result:</para>
                    <figure>
                              <title>A simple <emphasis role="bold">
                                                  <property>&lt;rich:tree&gt;</property>
                                        </emphasis> from a local XML file</title>
                              <mediaobject>
                                        <imageobject>
                                                  <imagedata fileref="images/treeXML.png"/>
                                        </imageobject>
                              </mediaobject>
                    </figure>

                    <para>It&apos;s possible to define a visual representation of a node data
                              model (to define a node icon) and its behavior in correspondence with
                              the data contained in this node (with a value of the <emphasis>
                                        <property>&quot;var&quot;</property>
                              </emphasis> attribute). The node behavior is defined by the components
                              nested into the <emphasis role="bold">
                                        <property>&lt;rich:treeNode&gt;</property>
                              </emphasis> (e.g. links or buttons). For these purposes you should use <emphasis>
                                        <property>&quot;nodeFace&quot;</property>
                              </emphasis> attribute. For each tree node a value of <emphasis>
                                        <property>&quot;nodeFace&quot;</property>
                              </emphasis> attribute is evaluated and <emphasis role="bold">
                                        <property>&lt;rich:treeNode&gt;</property>
                              </emphasis> with a value of <emphasis>
                                        <property>&quot;type&quot;</property>
                              </emphasis> attribute equal to a value of <emphasis>
                                        <property>&quot;nodeFace&quot;</property>
                              </emphasis> is used for node representation. See an example
                              below.</para>

                    <para id="example">
                              <emphasis role="bold">Example:</emphasis>
                    </para>

                    <programlisting role="XML"><![CDATA[...
<h:form>
    <rich:tree style="width:300px" value="#{library.data}" var="item" nodeFace="#{item.type}">
        <rich:treeNode type="artist" iconLeaf="/images/tree/singer.png" icon="/images/tree/singer.png">
            <h:outputText value="#{item.name}" />
        </rich:treeNode>
        <rich:treeNode type="album" iconLeaf="/images/tree/disc.png" icon="/images/tree/disc.png">
            <h:outputText value="#{item.title}" />
        </rich:treeNode>
        <rich:treeNode type="song" iconLeaf="/images/tree/song.png" icon="/images/tree/song.png">
            <h:outputText value="#{item.title}" />
        </rich:treeNode>
    </rich:tree>
</h:form>
...]]></programlisting>
                    <para>This is a result: </para>
                    <figure>
                              <title>The <emphasis>
                                                  <property>&quot;nodeFace&quot;</property>
                                        </emphasis> attribute usage</title>
                              <mediaobject>
                                        <imageobject>
                                                  <imagedata fileref="images/tree2.png"/>
                                        </imageobject>
                              </mediaobject>
                    </figure>
                    <para>In the example above, when each node of data model is processed, data
                              contained in the <code>&quot;data&quot;</code> property of
                                        <property>&quot;TreeNode&quot;</property> interface
                              is assigned to a request scope variable, which name is defined with <emphasis>
                                        <property>&quot;var&quot;</property>
                              </emphasis> attribute. The value of the <emphasis>
                                        <property>&quot;nodeFace&quot;</property>
                              </emphasis> attribute is evaluated in correspondence with the data
                              assigned to the <emphasis>
                                        <property>&quot;var&quot;</property>
                              </emphasis> attribute. The corresponding <emphasis role="bold">
                                        <property>&lt;rich:treeNode&gt;</property>
                              </emphasis> component (with a value of <emphasis>
                                        <property>&quot;type&quot;</property>
                              </emphasis> attribute equal to a value of <emphasis>
                                        <property>&quot;nodeFace&quot;</property>
                              </emphasis>) is used for the node representation. For example, during
                              data model processing, an object with a name &quot;Chris
                              Rea&quot; was inserted in the <emphasis>
                                        <property>&quot;var&quot;</property>
                              </emphasis> attribute. Then the value of <emphasis>
                                        <property>&quot;nodeFace&quot;</property>
                              </emphasis> attribute was evaluated as
                                        <code>&quot;artist&quot;</code>. Thus, for the node
                              representation the <emphasis role="bold">
                                        <property>&lt;rich:treeNode&gt;</property>
                              </emphasis> with <emphasis>
                                        <property>&quot;type&quot;</property>
                              </emphasis> equal to &quot;<code>artist</code>&quot; was
                              used.</para>
                    <para>You can also assign an EL-expression as value of the <emphasis>
                                        <property>&quot;nodeFace&quot;</property>
                              </emphasis> attribute. See an example below: </para>
                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="JAVA"><![CDATA[
nodeFace="#{data.name != 'param-value' ? 'artist' : 'album'}"
 ]]></programlisting>
                    <para>There are some essential points in a <emphasis>
                                        <property>&quot;nodeFace&quot;</property>
                              </emphasis> attribute usage: you need to define notions for
                                        <property>typeless</property> and a
                                        <property>default</property> nodes. </para>

                    <para>The <property>typeless node</property> is the first <emphasis role="bold">
                                        <property>&lt;rich:treeNode&gt;</property>
                              </emphasis> component (from all children nodes nested to the <emphasis
                                        role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> component) with not defined <emphasis>
                                        <property>&quot;type&quot;</property>
                              </emphasis> attribute and defined <emphasis>
                                        <property>&quot;rendered&quot;</property>
                              </emphasis> attribute. The <property>typeless node</property> is used
                              for representation when <emphasis>
                                        <property>&quot;nodeFace&quot;</property>
                              </emphasis> attribute is null.</para>
                    <para><property>Default node</property> has the following interior
                              presentation:</para>
                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="XML"><![CDATA[...
<h:outputText value="#{varAttributeName}">
...]]></programlisting>
                    <para>
                              <emphasis>
                                        <property>&quot;varAttributeName&quot;</property>
                              </emphasis> is a value for <emphasis>
                                        <property>&quot;var&quot;</property>
                              </emphasis> attribute. </para>
                    <para><property>Default node</property> is used in the following cases:</para>
                    <itemizedlist>
                              <listitem>
                                        <para><emphasis>
                                                  <property>&quot;nodeFace&quot;</property>
                                                  </emphasis> attribute is defined, but its value
                                                  isn&apos;t equal to any <emphasis>
                                                  <property>&quot;type&quot;</property>
                                                  </emphasis> attribute value from all children
                                                  nodes;</para>
                              </listitem>
                              <listitem>
                                        <para><emphasis>
                                                  <property>&quot;nodeFace&quot;</property>
                                                  </emphasis> attribute is defined and its value is
                                                  equal to a value of some <emphasis>
                                                  <property>&quot;type&quot;</property>
                                                  </emphasis> attribute from all children nodes, but
                                                  the value of <emphasis>
                                                  <property>&quot;rendered&quot;</property>
                                                  </emphasis> attribute for this node is
                                                  <property>&quot;false&quot;</property>.</para>
                              </listitem>
                    </itemizedlist>
                    <para>There is also one thing that has to be remembered using <emphasis>
                                        <property>&quot;type&quot;</property>
                              </emphasis> and <emphasis>
                                        <property>&quot;rendered&quot;</property>
                              </emphasis> attributes: it&apos;s possible to define several
                                        <emphasis role="bold">
                                        <property>&lt;rich:treeNode&gt;</property>
                              </emphasis> components with equal values of <emphasis>
                                        <property>&quot;type&quot;</property>
                              </emphasis> attribute and different values of <emphasis>
                                        <property>&quot;rendered&quot;</property>
                              </emphasis> attribute. It provides a possibility to define different
                              representation styles for the same node types. In the example with
                              artists and their albums (see <link linkend="example">above</link>)
                              it&apos;s possible to represent albums that are available for sale
                              and albums that are not available. Please study the example
                              below:</para>
                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>

                    <programlisting role="XML"><![CDATA[...
<h:form>
    <rich:tree style="width:300px" value="#{library.data}" var="item" nodeFace="#{item.type}">
    ...
        <rich:treeNode type="album" iconLeaf="/images/tree/album.gif" icon="/images/tree/album.gif"
                      rendered="#{item.exist}">
            <h:outputText value="#{item.name}" />
        </rich:treeNode>
        <rich:treeNode type="album" iconLeaf="/images/tree/album_absent.gif" icon="/images/tree/album_absent.gif"
                      rendered="#{not item.exist}">
            <h:outputText value="#{item.name}" />
        </rich:treeNode>
    ...
    </rich:tree>
</h:form>
...]]></programlisting>
                    <para>This is a result of the code: </para>
                    <figure>
                              <title>The <emphasis>
                                                  <property>&quot;type&quot;</property>
                                        </emphasis> and the <emphasis>
                                                  <property>&quot;rendered&quot;</property>
                                        </emphasis> attributes usage</title>
                              <mediaobject>
                                        <imageobject>
                                                  <imagedata fileref="images/tree4.png"/>
                                        </imageobject>
                              </mediaobject>
                    </figure>
                    <para>In the example the <emphasis role="bold">
                                        <property>&lt;rich:treeNode&gt;</property>
                              </emphasis> components has equal values of the <emphasis>
                                        <property>&quot;type&quot;</property>
                              </emphasis> attribute. Depending on value of the <emphasis>
                                        <property>&quot;rendered&quot;</property>
                              </emphasis> attribute the corresponding <emphasis role="bold">
                                        <property>&lt;rich:treeNode&gt;</property>
                              </emphasis> component is selected for node representation. If an album
                              is available for sale the value of the <emphasis>
                                        <property>&quot;rendered&quot;</property>
                              </emphasis> for the first <emphasis>
                                        <property>&lt;rich:treeNode&gt;</property>
                              </emphasis> component is &quot;true&quot;, for the second one
                              is &quot;false&quot;. Thus, the first <emphasis role="bold">
                                        <property>&lt;rich:treeNode&gt;</property>
                              </emphasis> is selected for node representation. </para>
                    <para>Tree node can be run in tree modes. Modes can be specified with <emphasis>
                                        <property>&quot;switchType&quot;</property>
                              </emphasis> attribute for<emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> component.</para>
                    <itemizedlist>
                              <listitem>
                                        <para><code>Ajax</code> (default value) - Ajax submission is
                                                  used performing the functionality. Note, that for
                                                  collapse/expand operations an Ajax request is sent
                                                  to the server and it can cause a short
                                                  delay.</para>
                              </listitem>
                              <listitem>
                                        <para><code>Server</code> - regular form of submission
                                                  request is used.</para>
                              </listitem>
                              <listitem>
                                        <para><code>Client</code> – all operations are performed
                                                  totally on the client; no interaction with a
                                                  server is involved. Full page content is reloaded
                                                  after every action.</para>
                              </listitem>
                    </itemizedlist>
                    <para> The <emphasis>
                                        <property>&quot;icon&quot;</property>
                              </emphasis>, <emphasis>
                                        <property>&quot;iconCollapsed&quot;</property>
                              </emphasis>, <emphasis>
                                        <property>&quot;iconExpanded&quot;</property>
                              </emphasis>, <emphasis>
                                        <property>&quot;iconLeaf&quot;</property>
                              </emphasis> attributes set the icons&apos; images for the
                              component. You can also define icons using facets with the same names.
                              If the facets are defined, the corresponding attributes are ignored
                              and facets&apos; content is used as icons. By default the width of
                              a rendered facet area is 16px. </para>
                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>

                    <programlisting role="XML"><![CDATA[...
<rich:tree value="#{library.data}" var="item">
    ...
    <f:facet name="icon">
        <h:graphicImage value="/images/tree/singer.png "/>
    </f:facet>
    <f:facet name="iconCollapsed">
        <h:graphicImage value="/images/tree/singer.png" />
    </f:facet>
    <f:facet name="iconExpanded">
        <h:graphicImage value="/images/tree/singer.png" />
    </f:facet>
    <f:facet name="iconLeaf">
        <h:graphicImage value="/images/tree/song.png" />
    </f:facet>
    ...
</rich:tree>
...]]></programlisting>

                    <para> The <emphasis role="bold">
                                        <property>&lt;rich: tree&gt;</property>
                              </emphasis> component can be used together with <emphasis role="bold">
                                        <property>&lt;rich: treeNodeAdaptor&gt;</property>
                              </emphasis>. In this case there is no need to specify the attributes <emphasis>
                                        <property>&quot;value&quot;</property>
                              </emphasis> and <emphasis>
                                        <property>&quot;var&quot;</property>
                              </emphasis>. Besides, visual representation shouldn&apos;t be
                              defined right in the <property>tree</property>. In this case a
                                        <emphasis role="bold">
                                        <property>&lt;rich: tree&gt;</property>
                              </emphasis> tag is applied mainly for defining common attributes such
                              as <emphasis>
                                        <property>&quot;ajaxSubmitSelection&quot;</property>
                              </emphasis> etc. </para>
                    <para> Information about the <emphasis>
                                        <property>&quot;process&quot;</property>
                              </emphasis> attribute usage you can find in the <link
                                        linkend="process"> &quot;Decide what to
                                        process&quot; </link> guide section. </para>
                    <!--<tip>
                              <title>Tip:</title>
                              <para>
                                        <emphasis>
                                                  <property>&quot;rowKeyConverter&quot;</property>
                                        </emphasis> support for the <emphasis role="bold">
                                                  <property>&lt;rich:tree&gt;</property>
                                        </emphasis> is pending! </para>
                                        </tip>-->

                    <para>As it&apos;s mentioned before, the <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> component uses a data model to represent the tree-like
                              nodes structure on the page. To identify a particular node during a
                              client request, the model provides a set of unique keys for tree
                              nodes. The <property>tree</property> can use strings as keys values
                              which may contain special characters not allowed by browsers, such as
                              the left angle bracket (&lt;), ampersand (&amp;), ant etc. Thus, to
                              have a possibility to use unallowed characters in the
                                        <property>tree</property> nodes, the following converters
                              are provided: </para>
                    <itemizedlist>
                              <listitem>
                                        <para><code>org.richfaces.TreeRowKeyConverter</code> that is
                                                  used for <property>&quot;TreeNode&quot;</property> based trees.
                                                  The key should be of a
                                                  <code>java.lang.String</code> type.</para>
                              </listitem>
                              <listitem>
                                        <para><code>org.richfaces.TreeAdaptorRowKeyConverter</code>
                                                  that is used for adaptor-based trees (see
                                                  <link linkend="rich_treeNodesAdaptor"><emphasis role="bold">
                                                  <property>&lt;rich:treeNodesAdaptor&gt;</property>
                                                  </emphasis></link>, <link linkend="rich_recursiveTreeNodesAdaptor"><emphasis role="bold">
                                                  <property>&lt;rich:recursiveTreeNodesAdaptor&gt;</property>
                                                  </emphasis></link>). The key should be of a
                                                  <code>java.lang.String</code> type.</para>
                              </listitem>
                              <listitem>
                                        <para><code>org.richfaces.TreeAdaptorIntegerRowKeyConverter</code>
                                                  which is provided for adaptor-based trees. The key
                                                  should be of a <code>java.lang.Integer</code>
                                                  type.</para>
                              </listitem>
                    </itemizedlist>

                    <para>The converters can be extended in order to have a possibility for
                              implementing custom converters.</para>
                    <para>To apply a converter to the <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> component, you should define it as a value of the <emphasis>
                                        <property>&quot;rowKeyConverter&quot;</property>
                              </emphasis> attribute.</para>

                    <para>Have a look at the example of a tree which contains the RichFaces
                              components as its nodes and the components attributes as the nodes
                              child elements. As the components have unallowed characters (&lt;
                              and &gt;) in their names, the <code>org.richfaces.TreeRowKeyConverter</code> is used here.</para>
                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    
                    <programlisting role="XML"><![CDATA[...
<rich:tree value="#{treeBean.data}" var="node" switchType="ajax"    rowKeyConverter="org.richfaces.TreeRowKeyConverter">
     <rich:treeNode ajaxSingle="true">
          <h:outputText value="#{node}"/>
     </rich:treeNode>
</rich:tree>
...]]></programlisting>
                    
                    <para>In the example the tree uses the following data model:</para>
                    
                    <programlisting role="JAVA"><![CDATA[...
String[ ] components = {"< a4j:ajaxListener >", "< a4j:keepAlive >", "< a4j:actionparam >" };
String[ ][ ] attributes = {{"type"},
                                {"ajaxOnly", "beanName"},
                                {"actionListener", "assignTo", "binding", "converter", "id", "name", "noEscape", "value"}};
                               
data = new TreeNodeImpl<String>();
			
for (int i = 0; i < components.length; i++) {
     TreeNode<String> child = new TreeNodeImpl<String>();
     child.setData(components[i]);
     data.addChild(components[i], child);
				
     for (int j = 0; j < attributes[i].length; j++) {
          TreeNode<String> grandChild = new TreeNodeImpl<String>();
          grandChild.setData(attributes[i][j]);
          child.addChild(attributes[i][j], grandChild);
     }
}          
...]]></programlisting>
                    
                    <para>This is the result:</para>
                    
                    <figure>
                              <title>The tree with the <code>org.richfaces.TreeRowKeyConverter</code> usage</title>
                              <mediaobject>
                                        <imageobject>
                                                  <imagedata fileref="images/treeRowKeyConverter.png"/>
                                        </imageobject>
                              </mediaobject>
                    </figure>
          </section>

          <section id="tsebro" role="updated">
                    <title>Built-In Drag and Drop</title>
                    <para>Words &quot;built-in&quot; in this context mean, that <emphasis
                                        role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> component has its own attributes, that provide
                                        <property>drag-and-drop</property> capability. These
                              attributes can be divided into two groups: those ones which provide
                                        <property>drag</property> and those which provide
                                        <property>drop</property> operations (see the tables below). </para>

                    <table>
                              <title>Drag group</title>
                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Attribute Name</entry>
                                                  <entry>Description</entry>
                                                  </row>
                                        </thead>
                                        <tbody>
                                                  <row>
                                                  <entry>dragValue</entry>
                                                  <entry>Element value drag passed into processing
                                                  after a Drop event</entry>
                                                  </row>
                                                  <row>
                                                  <entry>dragListener</entry>
                                                  <entry>A listener that processes a Drag
                                                  event</entry>
                                                  </row>
                                                  <row>
                                                  <entry>dragIndicator</entry>
                                                  <entry>Id of a component that is used as a drag
                                                  pointer during the drag operation</entry>
                                                  </row>
                                                  <row>
                                                  <entry>dragType</entry>
                                                  <entry>Defines a drag zone type that is used for
                                                  definition of a dragged element, which can be
                                                  accepted by a drop zone</entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table>

                    <table>
                              <title>Drop group</title>
                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Attribute Name</entry>
                                                  <entry>Description</entry>
                                                  </row>
                                        </thead>
                                        <tbody>
                                                  <row>
                                                  <entry>dropValue</entry>
                                                  <entry>Element value drop passed into processing
                                                  after Drop events </entry>
                                                  </row>
                                                  <row>
                                                  <entry>dropListener</entry>
                                                  <entry>A listener that processes a Drop event.
                                                  </entry>
                                                  </row>
                                                  <row>
                                                  <entry>acceptedTypes</entry>
                                                  <entry>Drag zone names are allowed to be processed
                                                  with a Drop zone</entry>
                                                  </row>
                                                  <row>
                                                  <entry>typeMapping</entry>
                                                  <entry>Drag zones names mapping on the
                                                  corresponding drop zone parameters</entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table>

                    <para>Consider <property>drag-and-drop</property> inside a tree. All zones,
                              which are assumed to be dragged, must be marked. In terms of <emphasis
                                        role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> these zones completely correspond to tree nodes. So, all
                              dragging nodes should be marked with <emphasis>
                                        <property>&quot;dragType&quot;</property>
                              </emphasis> attribute. Then, to mark zone(-s), where the dragging node
                              could be dropped, pass the type of dragging node to the <emphasis>
                                        <property>&quot;acceptedTypes&quot;</property>
                              </emphasis> attribute of the drop zone. It would be good to itemize,
                              that each tree node in the <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> component’s structure has its own
                              <emphasis>key</emphasis>. Depending on how the component is used,
                              these keys can be generated by the component itself or can be taken
                              from the component’s data model. Keys help to identify each node in a
                              tree; key is what exactly being passing from one node to another in
                                        <property>drag-and-drop</property> operations. Finally, the
                              method binding, that will process <property>drag-and-drop</property>
                              operation, should be pointed via <emphasis>
                                        <property>&quot;dropListener&quot;</property>
                              </emphasis> attribute of the <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis>. </para>
                    <para> Chapters &quot;<link linkend="ch1">6.40
                                        &lt;dragIndicator&gt;</link>&quot; and
                                        &quot;<link linkend="dndParam">6.39
                                        &lt;dndParam&gt;</link>&quot; describes how to
                              apply visual element, that show some additional information (e.g.
                              dragging item name) while operating with
                                        <property>drag-and-drop</property>. </para>
                    <para> Page code, that describes a tree with built in
                                        <property>drag-and-drop</property> in the way it is
                              considered, is shown below. </para>

                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>

                    <programlisting role="XML"><![CDATA[...
<h:form>
     <rich:tree style="width:300px" value="#{libraryAjaxTree.data}" nodeFace="#{item.type}" var="item" dragIndicator=":treeDragIndicator" dropListener="#{libraryAjaxTree.processDrop}">
          <rich:treeNode type="artist" icon="/images/tree/group.png" iconLeaf="/images/tree/group.png" acceptedTypes="album">
               <h:outputText value="#{item.name}" />
          </rich:treeNode>
          <rich:treeNode type="album" icon="/images/tree/cd.png" iconLeaf="/images/tree/cd.png" dragType="album" acceptedTypes="song">
               <h:outputText value="#{item.title}" />
               <rich:dndParam name="label" type="drag" value="Album: #{item.title}" />
          </rich:treeNode>
          <rich:treeNode type="song" icon="/images/tree/music.png" iconLeaf="/images/tree/music.png" dragType="song">
               <h:outputText value="#{item.title}" />
               <rich:dndParam name="label" type="drag" value="Song: #{item.title}" />
          </rich:treeNode>
    </rich:tree>
</h:form>
...]]></programlisting>

                    <para>This code renders following tree:</para>

                    <figure>
                              <title>Drag-and-drop operations</title>
                              <mediaobject>
                                        <imageobject>
                                                  <imagedata fileref="images/tree5.png"/>
                                        </imageobject>
                              </mediaobject>
                    </figure>

          </section>

          <section>
                    <title>Events handling</title>
                    <para>Listeners classes that process events on the server side are defined with
                              the help of:</para>
                    <itemizedlist>
                              <listitem>
                                        <para><property>changeExpandListener</property> processes
                                                  expand/collapse event of a
                                                  <property>treeNode</property></para>
                              </listitem>
                              <listitem>
                                        <para><property>dropListener</property> processes a Drop
                                                  event</para>
                              </listitem>
                              <listitem>
                                        <para><property>dragListener</property> processes a Drag
                                                  event</para>
                              </listitem>
                              <listitem>
                                        <para><property>nodeSelectListener</property> is called
                                                  during request sending on a node selecting event
                                                  (if request sending on this event is
                                                  defined)</para>
                              </listitem>
                    </itemizedlist>

                    <para>Listener methods can be defined using the <link linkend="treeNodeKF"
                                        >following attributes</link> or using nested tags.</para>
                    <para>Client event attributes are:</para>
                    <itemizedlist>
                              <listitem>
                                        <para><emphasis>
                                                  <property>&quot;onexpand&quot;</property>
                                                  </emphasis> is a script expression to invoke when
                                                  a node is expanded</para>
                              </listitem>
                              <listitem>
                                        <para><emphasis>
                                                  <property>&quot;oncollapse&quot;</property>
                                                  </emphasis> is a script expression to invoke when
                                                  a node is collapsed</para>
                              </listitem>
                              <listitem>
                                        <para><emphasis>
                                                  <property>&quot;ondragexit&quot;</property>
                                                  </emphasis> is a script expression to invoke when
                                                  an element passing out from a tree zone</para>
                              </listitem>
                              <listitem>
                                        <para><emphasis>
                                                  <property>&quot;ondragstart&quot;</property>
                                                  </emphasis> is a script expression to invoke when
                                                  dragging starts</para>
                              </listitem>
                              <listitem>
                                        <para><emphasis>
                                                  <property>&quot;ondragend&quot;</property>
                                                  </emphasis> is a script expression to invoke when
                                                  dragging ends (a drop event)</para>
                              </listitem>
                              <listitem>
                                        <para><emphasis>
                                                  <property>&quot;ondragenter&quot;</property>
                                                  </emphasis>is a script expression to invoke when a
                                                  dragged element appears on a tree</para>
                              </listitem>
                    </itemizedlist>

                    <para>They can be used to add some JavaScript effects.</para>

                    <para> Standart HTML event attributes like<emphasis>
                                        <property>&quot;onclick&quot;</property>
                              </emphasis>, <emphasis>
                                        <property>&quot;onmousedown&quot;</property>
                              </emphasis>, <emphasis>
                                        <property>&quot;onmouseover&quot;</property>
                              </emphasis> etc. can be also used. Event handlers of a <emphasis
                                        role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> component capture events occured on any
                                        <property>tree</property> part. But event handlers of
                                        <property>treeNode</property> capture events occured on
                                        <property>treeNode</property> only, except for children
                              events. </para>
          </section>

          <section>
                    <title>Facets</title>
                    <table>
                              <title>Facets</title>
                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Facet name</entry>
                                                  <entry>Description</entry>
                                                  </row>
                                        </thead>
                                        <tbody>
                                                  <row>
                                                  <entry>icon</entry>
                                                  <entry>Redefines the icon for node. Related
                                                  attribute is &quot;icon&quot;</entry>
                                                  </row>
                                                  <row>
                                                  <entry>iconCollapsed</entry>
                                                  <entry>Redefines the icon for collapsed node.
                                                  Related attribute is
                                                  &quot;iconCollapsed&quot;</entry>
                                                  </row>
                                                  <row>
                                                  <entry>iconExpanded</entry>
                                                  <entry>Redefines the icon for expanded node.
                                                  Related attribute is
                                                  &quot;iconExpanded&quot;</entry>
                                                  </row>
                                                  <row>
                                                  <entry>iconLeaf</entry>
                                                  <entry>Redefines the icon for component leaves.
                                                  Related attribute is
                                                  &quot;iconLeaf&quot;</entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table>
          </section>

          <section>
                    <title>Look-and-Feel Customization</title>

                    <para>For skinnability implementation, the components use a <emphasis>
                                        <property>style class redefinition method.</property>
                              </emphasis> Default style classes are mapped on <emphasis>
                                        <property>skin parameters.</property>
                              </emphasis></para>

                    <para>There are two ways to redefine the appearance of all <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> components at once:</para>

                    <itemizedlist>
                              <listitem>
                                        <para>Redefine the corresponding skin parameters</para>
                              </listitem>

                              <listitem>
                                        <para>Add to your style sheets <emphasis>
                                                  <property>style classes</property>
                                                  </emphasis> used by a <emphasis role="bold">
                                                  <property>&lt;rich:tree&gt;</property>
                                                  </emphasis> component</para>
                              </listitem>
                    </itemizedlist>
          </section>

          <section>
                    <title>Skin Parameters Redefinition:</title>
                    <para>There is only one skin parameter for <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis>. As it&apos;s a wrapper component for <emphasis
                                        role="bold">
                                        <property>&lt;rich:treeNode&gt;</property>
                              </emphasis> components, look and feel customization is described in
                              the <link linkend="SPRofTN">corresponding section</link>.</para>
                    <table>
                              <title>Skin parameters for a wrapper element</title>
                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Skin parameters</entry>
                                                  <entry>CSS properties</entry>
                                                  </row>
                                        </thead>
                                        <tbody>
                                                  <row>
                                                  <entry>overAllBackground</entry>
                                                  <entry>background-color </entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table>
          </section>
          <section>
                    <title>Definition of Custom Style Classes</title>

                    <table id="tab_cn7">
                              <title>Classes names that define a component appearance</title>
                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Class name</entry>
                                                  <entry>Description</entry>
                                                  </row>
                                        </thead>
                                        <tbody>
                                                  <row>
                                                  <entry>rich-tree</entry>
                                                  <entry>Defines styles for a wrapper
                                                  &lt;div&gt; element of a tree</entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table>

                    <para>In order to redefine styles for all <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> components on a page using CSS, it&apos;s enough to
                              create classes with the same names (possible classes could be found in
                              the table <link linkend="tab_cn7">above</link>) and define necessary
                              properties in them. An example is placed below:</para>

                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="CSS"><![CDATA[...
 .rich-tree{
    font-weight:bold;
}
...]]></programlisting>

                    <para>This is a result:</para>

                    <figure>
                              <title>Redefinition styles with predefined classes</title>
                              <mediaobject>
                                        <imageobject>
                                                  <imagedata fileref="images/tree_pc.png"/>
                                        </imageobject>
                              </mediaobject>
                    </figure>

                    <para>In the example a tree font weight was changed to bold.</para>
                    <para>Also it&apos;s possible to change styles of a particular <emphasis
                                        role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> component. In this case you should create own style
                              classes and use them in corresponding <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis>
                              <property>styleClass</property> attributes. An example is placed
                              below:</para>

                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="CSS"><![CDATA[...
.myClass{
    font-weight:bold;
}
...]]></programlisting>
                    <para>The <emphasis>
                                        <property>&quot;highlightedClass&quot;</property>
                              </emphasis> attribute for <emphasis role="bold">
                                        <property>&lt;rich:tree&gt; </property>
                              </emphasis> is defined as it&apos;s shown in the example
                              below:</para>

                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="XML"><![CDATA[<rich:tree ... styleClass="myClass"/>
]]></programlisting>

                    <para>This is a result:</para>

                    <figure>
                              <title>Redefinition styles with own classes and styleClass
                                        attributes</title>
                              <mediaobject>
                                        <imageobject>
                                                  <imagedata fileref="images/tree_oc.png"/>
                                        </imageobject>
                              </mediaobject>
                    </figure>

                    <para>As it&apos;s shown on the picture above, font weight of highlighted
                              text node of a <property>tree</property> was changed to bold.</para>
          </section>

          <section>
                    <title>Relevant Resources Links</title>
                    <para>
                              <ulink
                                        url="http://livedemo.exadel.com/richfaces-demo/richfaces/tree.jsf?c=tree"
                                        >On the component LiveDemo page</ulink> you can see the
                              example of <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> usage and sources for the given example. </para>
                    <para>How to Expand/Collapse Tree Nodes from code, see in this<ulink
                                        url="http://labs.jboss.com/wiki/ExpandCollapseTreeNodes"
                                        >wiki article</ulink>. </para>
          </section>

</section>
