Author: artdaw Date: 2009-02-11 09:25:56 -0500 (Wed, 11 Feb 2009) New Revision: 12630 Added: trunk/docs/userguide/en/src/main/resources/images/treeXML.png Modified: trunk/docs/userguide/en/src/main/docbook/included/tree.xml Log: https://jira.jboss.org/jira/browse/RF-5083 - Information about XmlTreeDataBuilder class was added to the Guide Modified: trunk/docs/userguide/en/src/main/docbook/included/tree.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/tree.xml 2009-02-11 14:24:11 UTC (rev 12629) +++ trunk/docs/userguide/en/src/main/docbook/included/tree.xml 2009-02-11 14:25:56 UTC (rev 12630) @@ -44,33 +44,15 @@ <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>There are two ways to set up a tree</para> + <itemizedlist> + <listitem> + <para>Using model (<code>org.richfaces.model.TreeNode</code> or <code>javax.swing.tree.TreeNode</code>) +</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}" /> @@ -78,6 +60,23 @@ ... </rich:tree> ...]]></programlisting> + + </listitem> + <listitem> + <para> + Using model tags <emphasis role="bold"><property>&lt;rich:recursiveTreeNodesAdaptor&gt;</property></emphasis>, + <emphasis role="bold"><property>&lt;rich:treeNodesAdaptor&gt;</property></emphasis>. + </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> + </listitem> + </itemizedlist> </section> <section> <title>Creating the Component Dynamically Using Java</title> @@ -90,271 +89,103 @@ 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/jbossrichface... - >&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> + + <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> + You can build your <emphasis role="bold"><property>&lt;rich:tree&gt;</property></emphasis> + using model (<code>org.richfaces.model.TreeNode</code> or <code>javax.swing.tree.TreeNode</code>). + In this case the <emphasis role="bold"><property>&lt;rich:tree&gt;</property></emphasis> component + interacts with data model via <code>&quot;TreeNode&quot;</code> interface +(<ulink url="http://labs.jboss.com/file-access/default/members/jbossrichface... +org.richfaces.model.TreeNode +</ulink>) that is used for the <emphasis role="bold"><property>&lt;rich:tree&gt;</property></emphasis> nodes representation. + </para> + <para> + Actually you can develop and use your own implementation of the <code>&quot;TreeNode&quot;</code> interface or use a + default one, which is defined with a default class <code>&quot;TreeNodeImpl&quot;</code> +(<ulink url="http://labs.jboss.com/file-access/default/members/jbossrichface... +org.richfaces.model.TreeNodeImpl +</ulink>). + </para> + <para> + 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. + </para> + <para> + When the <emphasis role="bold"><property>&lt;rich:tree&gt;</property></emphasis> component is being rendered + it iterates through model nodes and renders them using one of its <property>immediate</property> + <emphasis role="bold"><property>&lt;rich:treeNode&gt;</property></emphasis> children. + Data property of the current model <code>TreeNode</code> is exposed using + <emphasis><property>&quot;var&quot;</property></emphasis> attribute, + so if <code>var=&quot;itemData&quot;</code> you can refer to that data using <code>#{itemData}</code> syntax. + </para> +<para>There is a <code>&quot;XmlTreeDataBuilder&quot;</code> 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 <code>&quot;XmlNodeData&quot;</code> + (<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> + Let&apos;s try to build a simple <emphasis role="bold"><property>&lt;rich:tree&gt;</property></emphasis> from a local XML file. + In the following example a simple XML file (stations.xml) is used as a radio station playlist: +</para> + <programlisting role="XML"><![CDATA[<?xml version="1.0"?> +<station name="KickRadio"> + <feed date="today"> + <song time="07:00">Hall & Oates - Kiss On My List</song> + <song time="07:03">David Bowie - Let's Dance</song> + <song time="07:06">Lyn Collins - Think (About It)</song> + <song time="07:10">Kim Carnes - Bette Davis Eyes</song> + <song time="07:15">KC & the Sunshine Band - Give It Up</song> + </feed> +</station>]]></programlisting> +<para> + Now you need a bean that holds a model nodes: +</para> +<programlisting role="JAVA"><![CDATA[... +private TreeNode data; ... - </rich:tree> -</h:form> +FacesContext context = FacesContext.getCurrentInstance(); +data = XmlTreeDataBuilder.build(new InputSource(getClass().getResourceAsStream("stations.xml"))); ...]]></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> +<para> + Finally you should set the <emphasis><property>&quot;value&quot;</property></emphasis> attribute to the + <code>data</code> bean property and define the <emphasis><property>&quot;var&quot;</property></emphasis> attribute in order to + refer to the data of nodes: +</para> +<programlisting role="XML"><![CDATA[... +<rich:tree id="treeXML" value="#{stations.data}" var="vardata"> + <rich:treeNode> + <h:outputText value="#{vardata.attributes['name']}" /> + <h:outputText value="#{vardata.attributes['date']}" /> + <h:outputText value="#{vardata.attributes['time']}" /> + <h:outputText value=" #{vardata.text}" /> + </rich:treeNode> +</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/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 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/jbossrichface... - >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/jbossrichface... - >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/jbossrichface... - >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/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>This is a result:</para> + <figure> + <title>A simple <emphasis role="bold"><property>&lt;rich:tree&gt;</property></emphasis> from a local XML file</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/treeXML.png"/> + </imageobject> + </mediaobject> + </figure> + <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> Added: trunk/docs/userguide/en/src/main/resources/images/treeXML.png =================================================================== (Binary files differ) Property changes on: trunk/docs/userguide/en/src/main/resources/images/treeXML.png ___________________________________________________________________ Name: svn:executable + * Name: svn:mime-type + application/octet-stream