[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><rich:tree></property>
@@ -307,7 +307,298 @@
<property>"ajaxSubmitSelection"</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><rich:tree></property>
+ </emphasis> component allows rendering any tree-like data model.</para>
+ <para>The component interacts with data model through
+ <property>"TreeNode"</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>"value"</property>
+ </emphasis> attribute of the <emphasis role="bold">
+ <property><rich:tree></property>
+ </emphasis> component contains a nodes structure defined in a bean property. The property
+ keeps a structure of objects that implement <property>"TreeNode"</property>
+ interface.</para>
+ <para><property>"TreeNode"</property> has a property
+ <property>"data"</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>"var"</property>
+ </emphasis> attribute for the <emphasis role="bold">
+ <property><rich:tree></property>
+ </emphasis> component.</para>
+ <para>You can develop and use your own implementation for the
+ <property>"TreeNode"</property> interface or use a default implementation,
+ which is defined with a default class <property>"TreeNodeImpl"</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>"XmlTreeDataBuilder"</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>"XmlNodeData"</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><rich:tree></property>
+ </emphasis> component.</para>
+ <para>It'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>"var"</property>
+ </emphasis> attribute). The node behavior is defined by components nested to the <emphasis
+ role="bold">
+ <property><rich:treeNode></property>
+ </emphasis> (it could be links or buttons, for example). For these purposes you should use <emphasis>
+ <property>"nodeFace"</property>
+ </emphasis> attribute. For each tree node a value of <emphasis>
+ <property>"nodeFace"</property>
+ </emphasis> attribute is evaluated and <emphasis role="bold">
+ <property><rich:treeNode></property>
+ </emphasis> with a value of <emphasis>
+ <property>"type"</property>
+ </emphasis> attribute equal to a value of <emphasis>
+ <property>"nodeFace"</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>"nodeFace"</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>"data"</property> of
+ <property>"TreeNode"</property> interface are placed in a request scope
+ variable, which name is defined with <emphasis>
+ <property>"var"</property>
+ </emphasis> attribute. The value of the <emphasis>
+ <property>"nodeFace"</property>
+ </emphasis> attribute is evaluated in compliance with data placed in the <emphasis>
+ <property>"var"</property>
+ </emphasis> attribute. And for the node representation is used corresponding <emphasis
+ role="bold">
+ <property><rich:treeNode></property>
+ </emphasis> component (with a value of <emphasis>
+ <property>"type"</property>
+ </emphasis> attribute equal to a value of <emphasis>
+ <property>"nodeFace"</property>
+ </emphasis>). For example, during processing of data model an object with name "Chris
+ Rea" was placed in the <emphasis>
+ <property>"var"</property>
+ </emphasis> attribute. Then value of <emphasis>
+ <property>"nodeFace"</property>
+ </emphasis> attribute is evaluated as "artist". Thus, for node
+ representation the <emphasis role="bold">
+ <property><rich:treeNode></property>
+ </emphasis> with <emphasis>
+ <property>"type"</property>
+ </emphasis> equal to "artist" is used.</para>
+ <para>Also you can define an EL-expression as value of the <emphasis>
+ <property>"nodeFace"</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>"nodeFace"</property>
+ </emphasis> attribute usage. For their description it's necessary to define notions
+ of a <property>"typeless node"</property> and a <property>"default
+ node"</property>.</para>
+ <para>The <property>typeless node</property> is the first <emphasis role="bold">
+ <property><rich:treeNode></property>
+ </emphasis> component (from all children nodes nested to the <emphasis role="bold">
+ <property><rich:tree></property>
+ </emphasis> component) with not defined <emphasis>
+ <property>"type"</property>
+ </emphasis> attribute and defined <emphasis>
+ <property>"rendered"</property>
+ </emphasis> attribute. The <property>typeless node</property> is used for representation when <emphasis>
+ <property>"nodeFace"</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>"varAttributeName"</property> is a value for <emphasis>
+ <property>"var"</property>
+ </emphasis> attribute. </para>
+ <para><property>Default node</property> is used in the following cases:</para>
+ <itemizedlist>
+ <listitem><emphasis>
+ <property>"nodeFace"</property>
+ </emphasis> attribute is defined, but its value isn't equal to any <emphasis>
+ <property>"type"</property>
+ </emphasis> attribute value from all children nodes;</listitem>
+ <listitem><emphasis>
+ <property>"nodeFace"</property>
+ </emphasis> attribute is defined and its value is equal to a value of some <emphasis>
+ <property>"type"</property>
+ </emphasis> attribute from all children nodes , but the value of <emphasis>
+ <property>"rendered"</property>
+ </emphasis> attribute for this node is
+ <property>"false"</property>.</listitem>
+ </itemizedlist>
+ <para>There is also one especial moment in the <emphasis>
+ <property>"type"</property>
+ </emphasis> and <emphasis>
+ <property>"rendered"</property>
+ </emphasis> attributes usage. It's possible to define several <emphasis role="bold">
+ <property><rich:treeNode></property>
+ </emphasis> components with the equal values of <emphasis>
+ <property>"type"</property>
+ </emphasis> attribute and different values of <emphasis>
+ <property>"rendered"</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'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>"type"</property>
+ </emphasis> and the <emphasis>
+ <property>"rendered"</property>
+ </emphasis> attributes usage</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/tree4.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>In the example the <emphasis role="bold">
+ <property><rich:treeNode></property>
+ </emphasis> components has equal values of the <emphasis>
+ <property>"type"</property>
+ </emphasis> attribute. In a compliance with value of the <emphasis>
+ <property>"rendered"</property>
+ </emphasis> attribute corresponding <emphasis role="bold">
+ <property><rich:treeNode></property>
+ </emphasis> component is selected for node representation. If an album is available for sale
+ the value of the <emphasis>
+ <property>"rendered"</property>
+ </emphasis> for the first <emphasis>
+ <property><rich:treeNode></property>
+ </emphasis> component is <property>"true"</property>, for the second one is
+ <property>"false"</property>. Thus, the first <emphasis role="bold">
+ <property><rich:treeNode></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>"switchType"</property>
+ </emphasis> attribute for<emphasis role="bold">
+ <property><rich:tree></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>"icon"</property>
+ </emphasis>, <emphasis>
+ <property>"iconCollapsed"</property>
+ </emphasis>, <emphasis>
+ <property>"iconExpanded"</property>
+ </emphasis>, <emphasis>
+ <property>"iconLeaf"</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><rich: tree></property>
+ </emphasis> component can be used together with <emphasis role="bold">
+ <property><rich: treeNodeAdaptor></property>
+ </emphasis>. In this case there is no need to specify the attributes <emphasis>
+ <property>"value"</property>
+ </emphasis> and <emphasis>
+ <property>"var"</property>
+ </emphasis>. Besides, visual representation shouldn'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>"ajaxSubmitSelection"</property>
+ </emphasis>, for instance. </para>
</section>
+
<section>
<title>Built-In Drag and Drop</title>
<para>The <emphasis role="bold">
@@ -404,8 +695,8 @@
<property>"acceptedTypes"</property>
</emphasis>="song". Its value is equal to the value of the<emphasis>
<property>"type"</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>"type"</property>
</emphasis>="artist".</para>
Modified: trunk/docs/userguide/en/src/main/resources/images/tree4.png
===================================================================
(Binary files differ)
More information about the richfaces-svn-commits
mailing list