[richfaces-svn-commits] JBoss Rich Faces SVN: r5455 - in trunk/docs/userguide/en/src/main: resources/images and 1 other directory.

richfaces-svn-commits at lists.jboss.org richfaces-svn-commits at lists.jboss.org
Thu Jan 17 11:48:10 EST 2008


Author: vkorluzhenko
Date: 2008-01-17 11:48:09 -0500 (Thu, 17 Jan 2008)
New Revision: 5455

Modified:
   trunk/docs/userguide/en/src/main/docbook/included/tree.xml
   trunk/docs/userguide/en/src/main/resources/images/tree4.png
Log:
http://jira.jboss.com/jira/browse/RF-1137 - rewrote description for tree.

Modified: trunk/docs/userguide/en/src/main/docbook/included/tree.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/included/tree.xml	2008-01-17 15:59:45 UTC (rev 5454)
+++ trunk/docs/userguide/en/src/main/docbook/included/tree.xml	2008-01-17 16:48:09 UTC (rev 5455)
@@ -90,7 +90,7 @@
 HtmlTree myTree = new HtmlTree();
 ...]]></programlisting>
   </section>
-  <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>
@@ -307,7 +307,298 @@
         <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">
@@ -404,8 +695,8 @@
         <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>
+      </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>
 

Modified: trunk/docs/userguide/en/src/main/resources/images/tree4.png
===================================================================
(Binary files differ)




More information about the richfaces-svn-commits mailing list