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/jbossrichface... + >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/jbossrichface... + >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/jbossrichface... + >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/jbossrichface... + >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/jbossrichface... + >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)