<?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:  1) with <emphasis role="bold">
        <property>&lt;rich:recursiveTreeNodesAdaptor&gt;</property>
      </emphasis> or <emphasis role="bold">
        <property>&lt;rich:treeNodesAdaptor&gt;</property>
      </emphasis> 2) and without them. The first method allows to omit<emphasis>
        <property>&quot;value&quot;</property>
      </emphasis> and <emphasis>
        <property>&quot;var&quot;</property>
      </emphasis> attributes definition as follows: </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>

    <para> The second way requires defining  some attributes,  as
      it&apos;s shown in the example: </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>
  </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 structure of data.</para>
    <para>A bean property is passed into a tree <emphasis>
        <property>&quot;value&quot;</property>
      </emphasis> attribute. The property keeps a structure of
        <property>&quot;TreeNode&quot;</property> type instances.</para>
    <para>There is a default class <property>&quot;TreeNodeImpl&quot;</property>, which is a
      default implementation for TreeNode interface. TreeNode has attribute <emphasis>
        <property>&quot;data&quot;</property>
      </emphasis> which value is available as a request scope variable with a name that is defined
      by <emphasis>
        <property>&quot;var&quot;</property>
      </emphasis> attribute of a <property>tree</property> component. <ulink
        url="http://labs.jboss.com/file-access/default/members/jbossrichfaces/freezone/docs/apidoc/org/richfaces/component/xml/XmlTreeDataBuilder.html"
        >&quot;XmlTreeDataBuilder&quot; class</ulink> allows transforming XML into
      structures of objects containing <property>&quot;XmlNodeData&quot;</property>
      instances as data, which could be represented by the <property>tree</property> component. </para>

    <para>For particular visual representation of data <emphasis role="bold">
        <property>&lt;rich:tree&gt;</property>
      </emphasis> selects one of the children <emphasis role="bold">
        <property>&lt;rich:treeNode&gt;</property>
      </emphasis> components by type. The type is defined with the <emphasis>
        <property>&quot;nodeFace&quot;</property>
      </emphasis> attribute that corresponds to a value of <emphasis>
        <property>&quot;type&quot;</property>
      </emphasis> attribute for <property>treeNode</property>. An example of definition is placed
      below: </para>

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

    <programlisting role="JAVA"><![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>Expanded tree with child elements</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/tree2.png"/>
        </imageobject>
      </mediaobject>
    </figure>

    <para>In case when <emphasis>
        <property>&quot;nodeFace&quot;</property>
      </emphasis> attribute isn&apos;t defined or defined but its value isn&apos;t equal to
      any type of all children <property>treeNode</property> components or this value is equal to
      some type, but the value of <emphasis>
        <property>&quot;rendered&quot;</property>
      </emphasis> attribute for this <property>treeNode</property> is
        <property>&quot;false&quot;</property> then default <property>treeNode</property> is
      used. </para>

    <para>Default <property>treeNode</property> is the first node (with not defined <emphasis>
        <property>&quot;type&quot;</property>
      </emphasis> attribute and defined <emphasis>
        <property>&quot;rendered&quot;</property>
      </emphasis> attribute) from all children nodes of the tree component. If such
        <property>treeNode</property> wasn&apos;t found, the following default interior
      presentation is used: </para>

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

    <programlisting role="JAVA"><![CDATA[<h: outputText value="#{varAttributeName}">]]></programlisting>

    <para>
      <property>&quot;varAttributeName&quot;</property> is a value for <emphasis>
        <property>&quot;var&quot;</property>
      </emphasis> attribute. </para>

    <para> It&apos;s possible to define several <emphasis role="bold">
        <property>&lt;rich:treeNode&gt;</property>
      </emphasis> components with the 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 the possibility to define different markup for the same
        <emphasis role="bold">
        <property>&lt;rich:treeNode&gt;</property>
      </emphasis> components type. An example is placed below. </para>

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

    <programlisting role="JAVA"><![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"
                      rendered="#{item.exist}">
                <h:outputText value="#{item.name}" />
            </rich:treeNode>
          <rich:treeNode type="artist" iconLeaf="/images/tree/singer.png" icon="/images/tree/singer_absent.png"
                      rendered="#{not item.exist}">
                <h:outputText value="#{item.name}" />
            </rich:treeNode>
	...
        </rich:tree>
</h:form>
...]]></programlisting>

    <para> The example represents definition of two different <emphasis role="bold">
        <property> &lt;rich:treeNode&gt;</property>
      </emphasis> components. The first specifies the album that&apos;s available for sale, the
      other specifies the album that is not available. The result is shown on the following
      screenshot: </para>

    <figure>
      <title> Using the <emphasis>
          <property>&quot;type&quot;</property>
        </emphasis> and the <emphasis>
          <property>&quot;rendered&quot;</property>
        </emphasis> attributes</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/tree4.png"/>
        </imageobject>
      </mediaobject>
    </figure>

    <para>You can define an EL-expression for <emphasis>
        <property>&quot;nodeFace&quot;</property>
      </emphasis> attribute. See an example: </para>

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

    <programlisting role="JAVA"><![CDATA[nodeFace="#{data.name != 'param-value' ? 'artist' : 'album'}" ]]></programlisting>

    <para>Switching on treeNode could be performed in three modes. Modes could be specified with <emphasis>
        <property>&quot;switchType&quot;</property>
      </emphasis> attribute. </para>

    <itemizedlist>
      <listitem>Ajax - Ajax submission is used for switching </listitem>
      <listitem>Server - regular form submission request is used</listitem>
      <listitem>Client - switching is done as a whole on a client, no interaction with the server
        presents</listitem>
    </itemizedlist>

    <para>If <emphasis>
        <property>&quot;ajaxSubmitSelection&quot;</property>
      </emphasis> attribute value set to <emphasis>
        <property>&quot;true&quot;</property>
      </emphasis> than any change in selection initiates an Ajax request to the server.</para>

    <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 define icons for the component. Also you can define icons using facets
      with the same names. If the facets are defined, the corresponding attributes are ignored and
      facets contents are 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 ....>
        ...
        <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 tree tag is intended mainly for defining common
      attributes such as <emphasis>
        <property>&quot;ajaxSubmitSelection&quot;</property>
      </emphasis>, for instance. </para>

  </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>The component interacts with data model via
      <property>&quot;TreeNode&quot;</property> 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 tree nodes representation. 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. The property
      keeps a structure of objects that implements <property>&quot;TreeNode&quot;</property>
      interface.</para>
    <para><emphasis role="bold">
      <property>&lt;rich:treeNode&gt;</property>
    </emphasis> has a property
        <property>&quot;data&quot;</property> (see <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>). Data contained in the property is placed in a
      request scope variable, which name is defined with <emphasis>
        <property>&quot;var&quot;</property>
      </emphasis> attribute for the <emphasis role="bold">
        <property>&lt;rich:tree&gt;</property>
      </emphasis> component.</para>
    <para>You can develop and use your own pattern of the
        <property>&quot;TreeNode&quot;</property> interface or use a default implementation,
      which is defined with a default class <property>&quot;TreeNodeImpl&quot;</property>
        (<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>There is a <property>&quot;XmlTreeDataBuilder&quot;</property> 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 transforming XML into
      structures of objects containing <property>&quot;XmlNodeData&quot;</property> (<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>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    <property>&quot;data&quot;</property> 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 &quot;artist&quot;. 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;artist&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><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;</listitem>
      <listitem><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>.</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 <property>&quot;true&quot;</property>, for the second one is
        <property>&quot;false&quot;</property>. 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>Ajax (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.</listitem>
      <listitem>Server - regular form of submission request is used.</listitem>
      <listitem>Client – all operations are performed totally on the client; no interaction with a server is involved. Full page content is reloaded after every action.</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 <property>&lt;rich: tree&gt;</property> tag is applied mainly for defining common
      attributes such as <emphasis>
        <property>&quot;ajaxSubmitSelection&quot;</property>
      </emphasis> etc. </para>
  </section>

  <section>
    <title>Built-In Drag and Drop</title>
    <para>The <emphasis role="bold">
        <property>&lt;rich: tree&gt;</property>
      </emphasis> component functionality provides a built-in support for Drag and Drop operations.
      The main usage principles are similar to RichFaces DnD wrapper components.  Hence, to get
      additional information on the issue, read the corresponding chapters:<link linkend="dndParam"
        >&quot;rich:dndParam&quot;</link>, <link linkend="dragSupport"
        >&quot;rich:dragSupport&quot;</link>, <link linkend="dragIndicator"
        >&quot;rich:dragIndicator&quot;</link>, <link linkend="dropSupport"
        >&quot;rich:dropSupport&quot;</link>. Since <property>treeNodes</property>can be assigned as 
      Drag, Drop or Drag-and-Drop elements, a <property>tree</property> can include the following
      groups of attributes.</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>Please see an example below.</para>

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

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

   <para>

In the shown example a song from one album can be dragged into another because attribute 
 <emphasis><property>&quot;acceptedTypes&quot;</property> </emphasis>=&quot;song&quot; defined in the second <property>treeNode</property>
 with <emphasis><property>&quot;type&quot;</property></emphasis>=&quot;album&quot;. Its value is equal to the value of the<emphasis>
        <property>&quot;type&quot;</property></emphasis>attribute defined  in the third <property>treeNode</property> (see picture below).  An album can be also
      dragged into <property>treeNode</property> with <emphasis>
        <property>&quot;type&quot;</property>
      </emphasis>=&quot;artist&quot; property.

</para>

    <figure>
      <title>DnD 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>changeExpandListener processes expand/collapse event of a <property>treeNode</property></listitem>
      <listitem>dropListener processes a Drop event</listitem>
      <listitem>dragListener processes a Drag event</listitem>
      <listitem>nodeSelectListener is called during request sending on a node selecting event (if request sending on this event is defined)</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>onexpand is a script expression to invoke when a node is expanded</listitem>
      <listitem>oncollapse is a script expression to invoke when a node is collapsed</listitem>
      <listitem>ondragexit is a script expression to invoke when an element passing out from a tree zone</listitem>
      <listitem>ondragstart is a script expression to invoke when dragging starts</listitem>
      <listitem>ondragend is a script expression to invoke when dragging ends (a drop event)</listitem>
      <listitem>ondragenter is a script expression to invoke when a dragged element appears on a tree</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>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_CS1.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’s shown in the example below:</para>
    
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="CSS"><![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_CS2.png"/>
        </imageobject>
      </mediaobject>
    </figure>  
    
    <para>As it&apos;s shown on the picture above, font weight of highlighted text node of a tree 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">Here</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 <ulink
        url="http://labs.jboss.com/wiki/ExpandCollapseTreeNodes">here</ulink>. </para>
  </section>

</section>
