[richfaces-svn-commits] JBoss Rich Faces SVN: r3486 - trunk/docs/userguide/en/src/main/docbook/included.

Author: afedosik Date: 2007-10-23 07:56:58 -0400 (Tue, 23 Oct 2007) New Revision: 3486 Modified: trunk/docs/userguide/en/src/main/docbook/included/tree.desc.xml trunk/docs/userguide/en/src/main/docbook/included/tree.xml Log: tree component description made by O Chikvina Modified: trunk/docs/userguide/en/src/main/docbook/included/tree.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/tree.desc.xml 2007-10-23 10:44:35 UTC (rev 3485) +++ trunk/docs/userguide/en/src/main/docbook/included/tree.desc.xml 2007-10-23 11:56:58 UTC (rev 3486) @@ -1,45 +1,48 @@ <?xml version="1.0" encoding="UTF-8"?> <section> -<sectioninfo> -<keywordset> -<keyword>tree</keyword> -</keywordset> -</sectioninfo> -<section> -<title>Description</title> - <para>A component for a tree-like presentation of data. It includes built-in drag and drop - support for its child elements.</para> - <figure> - <title>Expanded tree with child elements</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/tree1.gif"/> - </imageobject> - </mediaobject> - </figure> + <sectioninfo> + <keywordset> + <keyword>tree</keyword> + </keywordset> + </sectioninfo> + <section> + <title>Description</title> + <para>A component for a tree-like presentation of data. It includes built-in drag and drop + support for its child elements.</para> + <figure> + <title>Expanded tree with child elements</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/tree1.gif"/> + </imageobject> + </mediaobject> + </figure> + <para>On the screenshot above there is an example of the tree with expanded node. This node + contains its own node with several leaves. Besides, it&apos;s possible to choose different + icons for tree nodes.</para> </section> <section> - <title>Key Features</title> + <title>Key Features</title> <itemizedlist> <listitem> <para>Highly customizable look-and-feel</para> </listitem> - + <para>This feature provides rich possibilities to change an appearance of a component to different corresponding modern styles.</para> <listitem> <para>Built-in drag and drop support</para> </listitem> - + <para>This feature allows changing a sequence order of nodes in a tree simply by dragging a certain node from one place to another.</para> <listitem> <para>Built-in Ajax processing</para> </listitem> - + <listitem> - <para>Support of template sets for different node types</para> + <para>Support of a visual representation for different node types</para> </listitem> - + <listitem> <para>Support of several root elements in a tree</para> </listitem> </itemizedlist> + </section> </section> -</section> Modified: trunk/docs/userguide/en/src/main/docbook/included/tree.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/tree.xml 2007-10-23 10:44:35 UTC (rev 3485) +++ trunk/docs/userguide/en/src/main/docbook/included/tree.xml 2007-10-23 11:56:58 UTC (rev 3486) @@ -44,17 +44,36 @@ <section> <title>Creating the Component with a Page Tag</title> - <para>Here is a simple example as it could be used in a page: </para> + <para>There are two cases for a tree definition: without adapters and with adapters. In the + first case, it&apos;s necessary to define it with <emphasis> + <property>&quot;value&quot;</property> + </emphasis> and <emphasis> + <property>&quot;var&quot;</property> + </emphasis> attributes as follows: </para> <para> <emphasis role="bold">Example:</emphasis> </para> <programlisting role="XML"><![CDATA[... - <rich:tree> + <rich:tree value="#{library.data}" var="item" > <!--Set of the Tree nodes--> </rich:tree> ... ]]></programlisting> + + <para>In the second case, it’s possible to define it without these attributes as it’s shown + below. </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> </section> <section> <title>Creating the Component Dynamically Using Java</title> @@ -70,18 +89,60 @@ </section> <section> <title>Details of Usage</title> - <para>As it has been mentioned <link linkend="tree">above</link> the tree component allows to render any tree-like structure + <para>As it has been mentioned above the tree component allows rendering any tree-like structure of data.</para> - <para>A bean property is passed into a tree <property>&quot;value&quot;</property> attribute. The property - keeps the structure of a org.richfaces.component.TreeNode type (you could have a look at this - interface description in the <ulink + <para>A bean property is passed into a tree <property>&quot;value&quot;</property> + attribute. The property keeps a structure of an<ulink url="http://labs.jboss.com/file-access/default/members/jbossrichface... - >API document</ulink>). The default classes for lists building of a TreeNodeImpl type (it - implements a TreeNode interface) for an XML structure XmlNodeData and XmlTreeDataBuilder are - implemented in the tree component. Hence, in order to provide your own class for TreeNode, - it&apos;s necessary only to implement this interface, i.e. the <emphasis> - <property>&quot;var&quot;</property> - </emphasis> attribute contains a name providing an access to data defined with a value. </para> + >org.richfaces.component.TreeNode</ulink> type.</para> + <para>There is a default class TreeNodeImpl which is used for treeNode interface implementation. + XmlTreeDataBuilder class allows transforming XML into structures of objects with XmlNodeData + type which could be represented by the tree component. </para> + <para><emphasis role="bold"> + <property>&lt;rich:treeNode&gt;</property> + </emphasis> has getValue method which is available in a request scope variable with name that + is defined by <property>&quot;var&quot;</property> attribute of tree component. </para> + + <para>For particular visual representation of data <emphasis role="bold"> + <property>&lt;rich:tree&gt;</property> + </emphasis> selects by type one of the children treeNode components. The type is defined with + the <property>&quot;nodeFace&quot;</property> attribute that contains value of + <property>&quot;type&quot;</property> attribute for treeNode. 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.gif" icon="/images/tree/singer.gif"> + <h:outputText value="#{item.name}" /> + </rich:treeNode> + <rich:treeNode type="album" iconLeaf="/images/tree/disc.gif" icon="/images/tree/disc.gif"> + <h:outputText value="#{item.title}" /> + </rich:treeNode> + <rich:treeNode type="song" iconLeaf="/images/tree/song.gif" icon="/images/tree/song.gif"> + <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 of different types</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/tree3.png"/> + </imageobject> + </mediaobject> + </figure> + <para>For data output, named <property>tree</property> nodes elements are used. Each element, for example depending on its definition, could be rendered with markup defined in one of <property>tree</property> nodes. It&apos;s defined with the <emphasis> @@ -91,8 +152,11 @@ <property>&quot;nodeFace&quot;</property> </emphasis> attribute. In case when <emphasis> <property>&quot;nodeFace&quot;</property> - </emphasis> is undefined the first node inside the tree will be use by default (attributes <emphasis><property>&quot;rendered</property></emphasis> and - <emphasis><property>&quot;type&quot;</property></emphasis> for this node should not be defined). </para> + </emphasis> is undefined the first node inside the tree will be use by default (attributes <emphasis> + <property>&quot;rendered</property> + </emphasis> and <emphasis> + <property>&quot;type&quot;</property> + </emphasis> for this node should not be defined). </para> <para> <emphasis role="bold">Example:</emphasis> @@ -140,10 +204,9 @@ <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. The width of a rendered facet area is 16px. - </para> + facets contents are used as icons. The width of a rendered facet area is 16px. </para> - <programlisting role="JAVA"><![CDATA[... + <programlisting role="JAVA"><![CDATA[... <rich:tree ....> ... <f:facet name="icon"> @@ -166,10 +229,10 @@ </section> <section> <title>Built-In Drag and Drop</title> - <para>The tree component functionality provides a built-in support for Drag and Drop - operations. The main usage principles are the same as for Rich Faces Drag and Drop wrapper - components. Hence, to get additional information on the topic, read the corresponding - chapters:<link linkend="dndParam">&quot;rich:dndParam&quot;</link> + <para>The tree component functionality provides a built-in support for Drag and Drop operations. + The main usage principles are the same as for Rich Faces Drag and Drop wrapper components. + Hence, to get additional information on the topic, read the corresponding chapters:<link + linkend="dndParam">&quot;rich:dndParam&quot;</link> <link linkend="dragSupport">&quot;rich:dragSupport&quot;</link> <link linkend="dragIndicator">&quot;rich:dragIndicator&quot;</link> <link linkend="dropSupport">&quot;rich:dropSupport&quot;</link> @@ -307,25 +370,25 @@ </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 class with the - same names and define necessary properties in them.</para> - + <property>&lt;rich:tree&gt;</property> + </emphasis> components on a page using CSS, it&apos;s enough to create class with the same + names and define necessary properties in them.</para> + <para>To change styles of particular <emphasis role="bold"> - <property>&lt;rich:tree&gt;</property> - </emphasis> components define your own style class in the corresponding <emphasis - role="bold"> - <property>&lt;rich:tree&gt;</property> - </emphasis>attribute.</para> + <property>&lt;rich:tree&gt;</property> + </emphasis> components define your own style class in the corresponding <emphasis role="bold"> + <property>&lt;rich:tree&gt;</property> + </emphasis>attribute.</para> </section> <section> <title>Relevant Resources Links</title> <para> <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/tree.jsf?c=... - you can see the example of <emphasis role="bold"><property>&lt;rich:tree&gt;</property></emphasis> usage - and sources for the given example. </para> + 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">her...;. </para> </section>