<section role="NotInToc" id="rich_tree">
   <title>
				&lt;
				rich:tree
				&gt;
				<emphasis role="since">
         <superscript> available since <emphasis role="version">3.0.0</emphasis>
         </superscript>
      </emphasis>
   </title>
   <section>
        <title>Description</title>
        <para>The component is designed for hierarchical data presentation and is applied for building 
a tree structure with a drag-and-drop capability.  </para>
        <figure>
            <title>Expanded <emphasis role="bold">
               <property>&lt;rich:tree&gt;</property>
            </emphasis> with child elements</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/tree_init.png"/>
                </imageobject>
            </mediaobject>
        </figure>
        <!--para>On the screenshot above, there is an example of the <property>tree</property> with an expanded node. This node
            contains its own node with several leaves. Besides, it&apos;s possible to choose your own
            icons for tree nodes.</para-->
    </section>
   <section>
        <title>Key Features</title>
        <itemizedlist>

         <listitem>
            <para>Highly customizable look-and-feel</para>
         </listitem>
         <listitem>
            <para>Built-in drag and drop capability, than enable relocating tree nodes within the tree</para>
         </listitem>
         <listitem>
            <para>Built-in Ajax processing</para>
         </listitem>
         <listitem>
            <para>Possibility to define a visual representation by node type</para>
         </listitem>
         <listitem>
            <para>Support of several root elements in a tree</para>
         </listitem>
 



        </itemizedlist>
    </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>"TreeNode"</code> interface (<ulink url="&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>"TreeNode"</code> interface or use a
                              default one, which is defined with a default class
                                        <code>"TreeNodeImpl"</code> (<ulink url="&apidoc_framework;org/richfaces/model/TreeNodeImpl.html"> org.richfaces.model.TreeNodeImpl </ulink>). </para>
                    <para> The <emphasis>
                                        <property>"value"</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>"var"</property>
                              </emphasis> attribute, so if
                                        <code>var="station"</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">...
private TreeNodeImpl&lt;String&gt; stationRoot = new TreeNodeImpl&lt;String&gt;();
private TreeNodeImpl&lt;String&gt; stationNodes = new TreeNodeImpl&lt;String&gt;(); 
private String[] kickRadioFeed = { "Hall &amp; Oates - Kiss On My List",
	"David Bowie - Let's Dance", "Lyn Collins - Think (About It)",
	"Kim Carnes - Bette Davis Eyes",
	"KC &amp; the Sunshine Band - Give It Up" };
	...	
stationRoot.setData("KickRadio");
stationNodes.addChild(0, stationRoot);
for (int i = 0; i &lt; kickRadioFeed.length; i++){
	TreeNodeImpl&lt;String&gt; child = new TreeNodeImpl&lt;String&gt;();
	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>"value"</property>
                              </emphasis> attribute and define the <emphasis>
                                        <property>"var"</property>
                              </emphasis> attribute in order to refer to the data: </para>
                    <programlisting role="XML">...
&lt;rich:tree value="#{stations.stationNodes}" var="station"&gt;
	&lt;rich:treeNode&gt;
		&lt;h:outputText value="#{station}" /&gt;
	&lt;/rich:treeNode&gt;
&lt;/rich:tree&gt;
...</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>"XmlTreeDataBuilder"</code> class
                                        (<ulink url="&apidoc;org/richfaces/component/xml/XmlTreeDataBuilder.html"> org.richfaces.component.xml.XmlTreeDataBuilder </ulink>)
                              that allows to transform XML into structures of objects containing
                                        <code>"XmlNodeData"</code> (<ulink url="&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'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">&lt;?xml version="1.0"?&gt;
&lt;station name="KickRadio"&gt;
		&lt;feed date="today"&gt;
			&lt;song time="07:00"&gt;Hall &amp; Oates - Kiss On My List&lt;/song&gt;
			&lt;song time="07:03"&gt;David Bowie - Let's Dance&lt;/song&gt; 
			&lt;song time="07:06"&gt;Lyn Collins - Think (About It)&lt;/song&gt;
			&lt;song time="07:10"&gt;Kim Carnes - Bette Davis Eyes&lt;/song&gt;
			&lt;song time="07:15"&gt;KC &amp; the Sunshine Band - Give It Up&lt;/song&gt;
		&lt;/feed&gt;
&lt;/station&gt;</programlisting>
                    <para> Now you need to create a bean that holds a model nodes: </para>
                    <programlisting role="JAVA">...
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>"value"</property>
                              </emphasis> attribute to the <code>data</code> bean property and
                              define the <emphasis>
                                        <property>"var"</property>
                              </emphasis> attribute in order to refer to the data of nodes: </para>
                    <programlisting role="XML">...
&lt;rich:tree id="treeXML" value="#{stations.data}" var="vardata"&gt;
	&lt;rich:treeNode&gt;
		&lt;h:outputText value="#{vardata.attributes['name']}" /&gt;
		&lt;h:outputText value="#{vardata.attributes['date']}" /&gt;
		&lt;h:outputText value="#{vardata.attributes['time']}" /&gt;
		&lt;h:outputText value=" #{vardata.text}" /&gt;
	&lt;/rich:treeNode&gt;
&lt;/rich:tree&gt;
...</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'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>"var"</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>"nodeFace"</property>
                              </emphasis> attribute. For each tree node a value of <emphasis>
                                        <property>"nodeFace"</property>
                              </emphasis> attribute is evaluated and <emphasis role="bold">
                                        <property>&lt;rich:treeNode&gt;</property>
                              </emphasis> with a value of <emphasis>
                                        <property>"type"</property>
                              </emphasis> attribute equal to a value of <emphasis>
                                        <property>"nodeFace"</property>
                              </emphasis> is used for node representation. See an example
                              below.</para>

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

                    <programlisting role="XML">...
&lt;h:form&gt;
    &lt;rich:tree style="width:300px" value="#{library.data}" var="item" nodeFace="#{item.type}"&gt;
        &lt;rich:treeNode type="artist" iconLeaf="/images/tree/singer.png" icon="/images/tree/singer.png"&gt;
            &lt;h:outputText value="#{item.name}" /&gt;
        &lt;/rich:treeNode&gt;
        &lt;rich:treeNode type="album" iconLeaf="/images/tree/disc.png" icon="/images/tree/disc.png"&gt;
            &lt;h:outputText value="#{item.title}" /&gt;
        &lt;/rich:treeNode&gt;
        &lt;rich:treeNode type="song" iconLeaf="/images/tree/song.png" icon="/images/tree/song.png"&gt;
            &lt;h:outputText value="#{item.title}" /&gt;
        &lt;/rich:treeNode&gt;
    &lt;/rich:tree&gt;
&lt;/h:form&gt;
...</programlisting>
                    <para>This is a result: </para>
                    <figure>
                              <title>The <emphasis>
                                                  <property>"nodeFace"</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>"data"</code> property of
                                        <property>"TreeNode"</property> interface
                              is assigned to a request scope variable, which name is defined with <emphasis>
                                        <property>"var"</property>
                              </emphasis> attribute. The value of the <emphasis>
                                        <property>"nodeFace"</property>
                              </emphasis> attribute is evaluated in correspondence with the data
                              assigned to the <emphasis>
                                        <property>"var"</property>
                              </emphasis> attribute. The corresponding <emphasis role="bold">
                                        <property>&lt;rich:treeNode&gt;</property>
                              </emphasis> component (with a value of <emphasis>
                                        <property>"type"</property>
                              </emphasis> attribute equal to a value of <emphasis>
                                        <property>"nodeFace"</property>
                              </emphasis>) is used for the node representation. For example, during
                              data model processing, an object with a name "Chris
                              Rea" was inserted in the <emphasis>
                                        <property>"var"</property>
                              </emphasis> attribute. Then the value of <emphasis>
                                        <property>"nodeFace"</property>
                              </emphasis> attribute was evaluated as
                                        <code>"artist"</code>. Thus, for the node
                              representation the <emphasis role="bold">
                                        <property>&lt;rich:treeNode&gt;</property>
                              </emphasis> with <emphasis>
                                        <property>"type"</property>
                              </emphasis> equal to "<code>artist</code>" was
                              used.</para>
                    <para>You can also assign an EL-expression as value of the <emphasis>
                                        <property>"nodeFace"</property>
                              </emphasis> attribute. See an example below: </para>
                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="JAVA">
nodeFace="#{data.name != 'param-value' ? 'artist' : 'album'}"
 </programlisting>
                    <para>There are some essential points in a <emphasis>
                                        <property>"nodeFace"</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>"type"</property>
                              </emphasis> attribute and defined <emphasis>
                                        <property>"rendered"</property>
                              </emphasis> attribute. The <property>typeless node</property> is used
                              for representation when <emphasis>
                                        <property>"nodeFace"</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">...
&lt;h:outputText value="#{varAttributeName}"&gt;
...</programlisting>
                    <para>
                              <emphasis>
                                        <property>"varAttributeName"</property>
                              </emphasis> is a value for <emphasis>
                                        <property>"var"</property>
                              </emphasis> attribute. </para>
                    <para>
         <property>Default node</property> is used in the following cases:</para>
                    <itemizedlist>
                              <listitem>
                                        <para>
               <emphasis>
                                                  <property>"nodeFace"</property>
                                                  </emphasis> attribute is defined, but its value
                                                  isn't equal to any <emphasis>
                                                  <property>"type"</property>
                                                  </emphasis> attribute value from all children
                                                  nodes;</para>
                              </listitem>
                              <listitem>
                                        <para>
               <emphasis>
                                                  <property>"nodeFace"</property>
                                                  </emphasis> attribute is defined and its value is
                                                  equal to a value of some <emphasis>
                                                  <property>"type"</property>
                                                  </emphasis> attribute from all children nodes, but
                                                  the value of <emphasis>
                                                  <property>"rendered"</property>
                                                  </emphasis> attribute for this node is
                                                  <property>"false"</property>.</para>
                              </listitem>
                    </itemizedlist>
                    <para>There is also one thing that has to be remembered using <emphasis>
                                        <property>"type"</property>
                              </emphasis> and <emphasis>
                                        <property>"rendered"</property>
                              </emphasis> attributes: it's possible to define several
                                        <emphasis role="bold">
                                        <property>&lt;rich:treeNode&gt;</property>
                              </emphasis> components with equal values of <emphasis>
                                        <property>"type"</property>
                              </emphasis> attribute and different values of <emphasis>
                                        <property>"rendered"</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'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">...
&lt;h:form&gt;
    &lt;rich:tree style="width:300px" value="#{library.data}" var="item" nodeFace="#{item.type}"&gt;
    	 ...
        &lt;rich:treeNode type="album" iconLeaf="/images/tree/album.gif" icon="/images/tree/album.gif"
                      rendered="#{item.exist}"&gt;
            &lt;h:outputText value="#{item.name}" /&gt;
        &lt;/rich:treeNode&gt;
        &lt;rich:treeNode type="album" iconLeaf="/images/tree/album_absent.gif" icon="/images/tree/album_absent.gif"
                      rendered="#{not item.exist}"&gt;
            &lt;h:outputText value="#{item.name}" /&gt;
        &lt;/rich:treeNode&gt;
    	 ...
    &lt;/rich:tree&gt;
&lt;/h:form&gt;
...</programlisting>
                    <para>This is a result of the code: </para>
                    <figure>
                              <title>The <emphasis>
                                                  <property>"type"</property>
                                        </emphasis> and the <emphasis>
                                                  <property>"rendered"</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>"type"</property>
                              </emphasis> attribute. Depending on value of the <emphasis>
                                        <property>"rendered"</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>"rendered"</property>
                              </emphasis> for the first <emphasis>
                                        <property>&lt;rich:treeNode&gt;</property>
                              </emphasis> component is "true", for the second one
                              is "false". 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>"switchType"</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>"icon"</property>
                              </emphasis>, <emphasis>
                                        <property>"iconCollapsed"</property>
                              </emphasis>, <emphasis>
                                        <property>"iconExpanded"</property>
                              </emphasis>, <emphasis>
                                        <property>"iconLeaf"</property>
                              </emphasis> attributes set the icons' 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' 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">...
&lt;rich:tree value="#{library.data}" var="item"&gt;
    ...
    &lt;f:facet name="icon"&gt;
        &lt;h:graphicImage value="/images/tree/singer.png "/&gt;
    &lt;/f:facet&gt;
    &lt;f:facet name="iconCollapsed"&gt;
        &lt;h:graphicImage value="/images/tree/singer.png" /&gt;
    &lt;/f:facet&gt;
    &lt;f:facet name="iconExpanded"&gt;
        &lt;h:graphicImage value="/images/tree/singer.png" /&gt;
    &lt;/f:facet&gt;
    &lt;f:facet name="iconLeaf"&gt;
        &lt;h:graphicImage value="/images/tree/song.png" /&gt;
    &lt;/f:facet&gt;
    ...
&lt;/rich:tree&gt;
...</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>"value"</property>
                              </emphasis> and <emphasis>
                                        <property>"var"</property>
                              </emphasis>. Besides, visual representation shouldn'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>"ajaxSubmitSelection"</property>
                              </emphasis> etc. </para>
                    <para> Information about the <emphasis>
                                        <property>"process"</property>
                              </emphasis> attribute usage you can find in the <link linkend="process"> "Decide what to
                                        process" </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'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 <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis> 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 keys, the following converters
                              are provided: </para>
                    <itemizedlist>
                              <listitem>
                                        <para>
               <code>org.richfaces.TreeRowKeyConverter</code> that is
                                                  used for <property>"TreeNode"</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>"rowKeyConverter"</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">...
&lt;rich:tree value="#{treeBean.data}" var="node" switchType="ajax"    rowKeyConverter="org.richfaces.TreeRowKeyConverter"&gt;
     &lt;rich:treeNode ajaxSingle="true"&gt;
          &lt;h:outputText value="#{node}"/&gt;
     &lt;/rich:treeNode&gt;
&lt;/rich:tree&gt;
...</programlisting>
                    
                    <para>In the example the tree uses the following data model:</para>
                    
                    <programlisting role="JAVA">...
String[ ] components = {"&lt; a4j:ajaxListener &gt;", "&lt; a4j:keepAlive &gt;", "&lt; a4j:actionparam &gt;" };
String[ ][ ] attributes = {{"type"},
                                {"ajaxOnly", "beanName"},
                                {"actionListener", "assignTo", "binding", "converter", "id", "name", "noEscape", "value"}};
                               
data = new TreeNodeImpl&lt;String&gt;();
			
for (int i = 0; i &lt; components.length; i++) {
     TreeNode&lt;String&gt; child = new TreeNodeImpl&lt;String&gt;();
     child.setData(components[i]);
     data.addChild(components[i], child);
				
     for (int j = 0; j &lt; attributes[i].length; j++) {
          TreeNode&lt;String&gt; grandChild = new TreeNodeImpl&lt;String&gt;();
          grandChild.setData(attributes[i][j]);
          child.addChild(attributes[i][j], grandChild);
     }
}          
...</programlisting>
                    
         </section>
   <section id="tsebro" role="updated">
                    <title>Built-in Drag and Drop</title>
                    <para>Words "built-in" 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>"dragType"</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>"acceptedTypes"</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>"dropListener"</property>
                              </emphasis> attribute of the <emphasis role="bold">
                                        <property>&lt;rich:tree&gt;</property>
                              </emphasis>. </para>
                    <para> Chapters "<link linkend="ch1">6.40
                                        &lt;dragIndicator&gt;</link>" and
                                        "<link linkend="dndParam">6.39
                                        &lt;dndParam&gt;</link>" 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">...
&lt;h:form&gt;
     &lt;rich:tree style="width:300px" value="#{libraryAjaxTree.data}" nodeFace="#{item.type}" var="item" dragIndicator=":treeDragIndicator" dropListener="#{libraryAjaxTree.processDrop}"&gt;
          &lt;rich:treeNode type="artist" icon="/images/tree/group.png" iconLeaf="/images/tree/group.png" acceptedTypes="album"&gt;
               &lt;h:outputText value="#{item.name}" /&gt;
          &lt;/rich:treeNode&gt;
          &lt;rich:treeNode type="album" icon="/images/tree/cd.png" iconLeaf="/images/tree/cd.png" dragType="album" acceptedTypes="song"&gt;
               &lt;h:outputText value="#{item.title}" /&gt;
               &lt;rich:dndParam name="label" type="drag" value="Album: #{item.title}" /&gt;
          &lt;/rich:treeNode&gt;
          &lt;rich:treeNode type="song" icon="/images/tree/music.png" iconLeaf="/images/tree/music.png" dragType="song"&gt;
               &lt;h:outputText value="#{item.title}" /&gt;
               &lt;rich:dndParam name="label" type="drag" value="Song: #{item.title}" /&gt;
          &lt;/rich:treeNode&gt;
    &lt;/rich:tree&gt;
&lt;/h:form&gt;
...</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>"onexpand"</property>
                                                  </emphasis> is a script expression to invoke when
                                                  a node is expanded</para>
                              </listitem>
                              <listitem>
                                        <para>
               <emphasis>
                                                  <property>"oncollapse"</property>
                                                  </emphasis> is a script expression to invoke when
                                                  a node is collapsed</para>
                              </listitem>
                              <listitem>
                                        <para>
               <emphasis>
                                                  <property>"ondragexit"</property>
                                                  </emphasis> is a script expression to invoke when
                                                  an element passing out from a tree zone</para>
                              </listitem>
                              <listitem>
                                        <para>
               <emphasis>
                                                  <property>"ondragstart"</property>
                                                  </emphasis> is a script expression to invoke when
                                                  dragging starts</para>
                              </listitem>
                              <listitem>
                                        <para>
               <emphasis>
                                                  <property>"ondragend"</property>
                                                  </emphasis> is a script expression to invoke when
                                                  dragging ends (a drop event)</para>
                              </listitem>
                              <listitem>
                                        <para>
               <emphasis>
                                                  <property>"ondragenter"</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>"onclick"</property>
                              </emphasis>, <emphasis>
                                        <property>"onmousedown"</property>
                              </emphasis>, <emphasis>
                                        <property>"onmouseover"</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>Reference Data</title>
      <para>
         <ulink url="&tlddoc;rich/tree.html">Table of 
							&lt;rich:tree&gt; 
							 attributes</ulink>.
						</para>
      <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>
      <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 "icon"</entry>
                                                  </row>
                                                  <row>
                                                  <entry>iconCollapsed</entry>
                                                  <entry>Redefines the icon for collapsed node.
                                                  Related attribute is
                                                  "iconCollapsed"</entry>
                                                  </row>
                                                  <row>
                                                  <entry>iconExpanded</entry>
                                                  <entry>Redefines the icon for expanded node.
                                                  Related attribute is
                                                  "iconExpanded"</entry>
                                                  </row>
                                                  <row>
                                                  <entry>iconLeaf</entry>
                                                  <entry>Redefines the icon for component leaves.
                                                  Related attribute is
                                                  "iconLeaf"</entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table>
      <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>
							You can find all necessary information about style classes redefinition in 
						<link linkend="customstyles">Definition of Custom Style Classes</link> 
							section.
						</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>
                    <para>
						Read <ulink url="https://www.jboss.org/community/wiki/RichFacesTreeFAQ"> RichFaces Tree FAQ </ulink> to know how to avoid problem with showing only two levels of node when tree  actually contains more.                    
                    </para>
          </section>
</section>
