<?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 cases for a tree definition: together with <emphasis role="bold">
        <property>&lt;rich:recursiveTreeNodesAdaptor&gt;</property>
      </emphasis> or <emphasis role="bold">
        <property>&lt;rich:treeNodesAdaptor&gt;</property>
      </emphasis> and without them. In the first case, it&apos;s possible to define it without <emphasis>
        <property>&quot;value&quot;</property>
      </emphasis> and <emphasis>
        <property>&quot;var&quot;</property>
      </emphasis> attributes 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> In the second case, it&apos;s necessary to define it with these attributes as
      it&apos;s shown below: </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="JAVA"><![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 through
      <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 implement <property>&quot;TreeNode&quot;</property>
      interface.</para>
    <para><property>&quot;TreeNode&quot;</property> 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 are 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 implementation for 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 <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 data model node (to define a
      node icon) and its behavior in a compliance with data contained in this node (with a value of
      the <emphasis>
        <property>&quot;var&quot;</property>
      </emphasis> attribute). The node behavior is defined by components nested to the <emphasis
        role="bold">
        <property>&lt;rich:treeNode&gt;</property>
      </emphasis> (it could be links or buttons, for example). 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. An example is placed below.</para>

    <para id="example">
      <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>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 when each node of data model is processed, data contained in the property
        <property>&quot;data&quot;</property> of
      <property>&quot;TreeNode&quot;</property> interface are placed in 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 compliance with data placed in the <emphasis>
        <property>&quot;var&quot;</property>
      </emphasis> attribute. And for the node representation is used 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>). For example, during processing of data model an object with name &quot;Chris
      Rea&quot; was placed in the <emphasis>
        <property>&quot;var&quot;</property>
      </emphasis> attribute. Then value of <emphasis>
        <property>&quot;nodeFace&quot;</property>
      </emphasis> attribute is evaluated as &quot;artist&quot;. Thus, for 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; is used.</para>
    <para>Also you can define 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 moments in a <emphasis>
        <property>&quot;nodeFace&quot;</property>
      </emphasis> attribute usage. For their description it&apos;s necessary to define notions
      of a <property>&quot;typeless node&quot;</property> and a <property>&quot;default
        node&quot;</property>.</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="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><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 especial moment in the <emphasis>
        <property>&quot;type&quot;</property>
      </emphasis> and <emphasis>
        <property>&quot;rendered&quot;</property>
      </emphasis> attributes usage. 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 representation for the
      same nodes type. 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. 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="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: </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. In a compliance with value of the <emphasis>
        <property>&quot;rendered&quot;</property>
      </emphasis> attribute 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>Switching on tree nodes could be performed in three modes. Modes could 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 for switching. Note, that for
        collapse/expand operations it is sent an Ajax request to the server. It could be seen a
        short delay in this case.</listitem>
      <listitem>Server - regular form submission request is used. Note, that all nodes actually
        render up-front and expanding/collapsing do not require server call.</listitem>
      <listitem>Client - switching is done as a whole on a client, no interaction with a server
        presents. Full page content is reloaded after every click.</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 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="JAVA"><![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>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 the same as for RichFaces DnD wrapper components. Hence, to get
      additional information on the topic, 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>. As <property>treeNodes</property> could be
      Drag, Drop or DnD elements, a <property>tree</property> can include the following attributes
      groups.</para>
    <table>
      <title>Drag attributes group</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>dragValue</entry>
            <entry>Element value drag passing into processing after a Drop event</entry>
          </row>
        </thead>
        <tbody>
          <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 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 attributes group</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>dropValue</entry>
            <entry>Element value drop passed into processing after Drop events .</entry>
          </row>
        </thead>
        <tbody>
          <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>An example of usage is placed below.</para>

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

    <programlisting role="JAVA"><![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 example a song from one album can be dragged into other because for the second
        <property>treeNode</property> with <emphasis>
        <property>&quot;type&quot;</property>
      </emphasis>=&quot;album&quot; was defined attribute <emphasis>
        <property>&quot;acceptedTypes&quot;</property>
      </emphasis>=&quot;song&quot;. Its value is equal to the value of the<emphasis>
        <property>&quot;type&quot;</property>
      </emphasis>attribute defined for the third treeNode (see picture below). Also an album can be
      dragged into <property>treeNode</property> with <emphasis>
        <property>&quot;type&quot;</property>
      </emphasis>=&quot;artist&quot;.</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>nodeSelectListener is called during request sending on a node selecting event (if
        request sending on this event is defined)</listitem>
      <listitem>dropListener processes a Drop event</listitem>
      <listitem>dragListener processes a Drug event</listitem>
      <listitem>changeExpandListener processes expand/collapse event of a
        <property>treeNode</property></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 - expands a node event</listitem>
      <listitem>oncollapse - collapses a node event</listitem>
      <listitem>ondragexit - element passing out from a tree zone event</listitem>
      <listitem>ondragstart - drags a start event</listitem>
      <listitem>ondragend - drags an end event (a drop event)</listitem>
      <listitem>ondragenter - drags an element appearing on a tree event</listitem>
    </itemizedlist>

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

    <para> Also 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> and etc. could be 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>
      <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 a class with the
      same names and define necessary properties in them.</para>

    <para>To change styles of particular <emphasis role="bold">
        <property>&lt;rich:tree&gt;</property>
      </emphasis> components define your own style class in the corresponding <emphasis role="bold">
        <property>&lt;rich:tree&gt;</property>
      </emphasis>attribute.</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>
