<?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 <link linkend="process"
                              >here</link>. </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>
                              The value of <emphasis>
                              <property>&quot;rowKeyConverter&quot;</property>
                              </emphasis>  can be: 
                    </para>
                    <itemizedlist>
                              <listitem>
                                        <para><code>org.richfaces.TreeRowKeyConverter</code> - it used for the simple tree.</para>
                              </listitem>
                              <listitem>
                                        <para><code>org.richfaces.TreeAdaptorRowKeyConverter</code> used for tree with <emphasis role="bold"><property>&lt;rich:treeNodesAdaptor&gt;</property></emphasis></para>
                              </listitem>
                              <listitem>
                                        <para>The <code>org.richfaces.TreeAdaptorIntegerRowKeyConverter</code> converter used for adaptor-based tree for implementing custom converters</para>
                              </listitem>
                    </itemizedlist>
                              
          </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>
