<?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
                                        <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 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
                                        <code>&quot;TreeNode&quot;</code> 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
                                        <code>&quot;TreeNode&quot;</code> interface or use a
                              default implementation, 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>There is 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 transforming 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>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>
          </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>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"
                                        >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>
