From richfaces-svn-commits at lists.jboss.org Wed Apr 29 05:14:46 2009 Content-Type: multipart/mixed; boundary="===============4330461073160628742==" MIME-Version: 1.0 From: richfaces-svn-commits at lists.jboss.org To: richfaces-svn-commits at lists.jboss.org Subject: [richfaces-svn-commits] JBoss Rich Faces SVN: r13892 - trunk/docs/userguide/en/src/main/docbook/included. Date: Wed, 29 Apr 2009 05:09:18 -0400 Message-ID: --===============4330461073160628742== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: ochikvina Date: 2009-04-29 05:09:17 -0400 (Wed, 29 Apr 2009) New Revision: 13892 Modified: trunk/docs/userguide/en/src/main/docbook/included/tree.xml Log: https://jira.jboss.org/jira/browse/RF-6582 - adding the description of the = tree converters and the example into the 'Details of usage' section. Modified: trunk/docs/userguide/en/src/main/docbook/included/tree.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/docs/userguide/en/src/main/docbook/included/tree.xml 2009-04-29 0= 8:22:23 UTC (rev 13891) +++ trunk/docs/userguide/en/src/main/docbook/included/tree.xml 2009-04-29 0= 9:09:17 UTC (rev 13892) @@ -46,13 +46,13 @@ Creating the Component with a Page Tag There are two ways to set up a tree - - Using model (org.richfaces.model.TreeN= ode or javax.swing.tree.TreeNode) - - - Example: - - + Using model (org.richf= aces.model.TreeNode + or javax.swing.tre= e.TreeNode) + + = Example: + + @@ -61,21 +61,22 @@ ...]]> = - - - - Using model tags <rich:recursiveTreeNodesAdaptor>, = - <rich:treeNod= esAdaptor>. - - - Example: - - + + Using model tags + <rich:recur= siveTreeNodesAdaptor> + , + <rich:treeN= odesAdaptor> + . + + = Example: + + ...]]> - +
@@ -89,51 +90,55 @@ HtmlTree myTree =3D new HtmlTree(); ...]]>
- = +
Details of Usage - - As it has been mentioned - above - the - - <rich:tree> component = - allows rendering any tree-like data model. - - - You can build your &l= t;rich:tree> = - using model (org.richfaces.model.TreeNode o= r javax.swing.tree.TreeNode). - In this case the <r= ich:tree> component - interacts with data model via "TreeNode"= interface = -( -org.richfaces.model.TreeNode -) that is used for the <rich:= tree> nodes representation. - - - Actually you can develop and use your own implementation o= f the "TreeNode" interface or use a - default one, which is defined with a default class= "TreeNodeImpl" = -( -org.richfaces.model.TreeNodeImpl -). - - - The "value" attribute = - of the <rich:tree&g= t; component = - contains a nodes structure defined in a bean property. = - - - When the <rich:tree&= gt; component is being rendered = - it iterates over the model nodes and renders them using o= ne of its immediate = - <rich:treeNode> children. = - Data property of the current model TreeNode = is exposed using = - "var"= attribute, = - so if var=3D"station" you can refe= r to that data using #{station} syntax. = - = - - In the following example the &= lt;rich:tree> is - built from a simple org.richfaces.model.TreeNode mo= del: - - As it has been mentioned above the + <rich:tree> + component allows rendering any t= ree-like data model. + You can build your + <rich:tree> + using model (org.richfaces= .model.TreeNode or + javax.swing.tree.TreeNode). In this case the + + <rich:tree> + component interacts with data mo= del via + "TreeNode" = interface ( org.richfaces.model.TreeNode ) that is used for + the + <rich:tree> + nodes representation. + Actually you can develop and use your own imple= mentation of the + "TreeNode" = interface or use a + default one, which is defined with a default= class + "TreeNodeImpl" ( org.richfaces.model.TreeNodeImpl= ). + The + "value" + attribute of the + <rich:tree> + component contains a nodes struc= ture defined in a bean + property. + When the + <rich:tree> + component is being rendered it i= terates over the model + nodes and renders them using one of its immediate + + <rich:treeNode> + children. Data property of the c= urrent model + TreeNode is exposed u= sing + "var" + attribute, so if + var=3D"station" you can refer + to that data using #{station} s= yntax. + In the following example the + <rich:tree> + is built from a simple + org.richfaces.model.TreeNode= model: + stationRoot =3D new TreeNodeImpl(); private TreeNodeImpl stationNodes =3D new TreeNodeImpl(); = private String[] kickRadioFeed =3D { "Hall & Oates - Kiss On My List", @@ -148,48 +153,54 @@ child.setData(kickRadioFeed[i]); stationRoot.addChild(i, child); } -...]]> = - -As it is mentioned before you need to pass #{stations.stationNodes}<= /code> property to the = -"value" attribute = -and define the "var" a= ttribute in order to refer to the data: = - - + As it is mentioned before you need to pass + #{stations.stationNodes} property to the + "value" + attribute and define the + "var" + attribute in order to refer to t= he data: + -...]]> = - - This is a result: - -
- A simple <emphasis role=3D"bold"><property><rich:tree></prop= erty></emphasis> from a <code>org.richfaces.model.TreeNode</code> - - - - - -
- = - -Implementation of the <rich:tree><= /property> component = -provides another way to build a tree. -This approach implies using a "XmlTreeDataBuilder" = class - ( - org.richfaces.component.xml.XmlTreeDataBuilder - ) that allows to transform XML into structures of objects contain= ing "XmlNodeData" = - ( - org.richfaces.component.xml.XmlNodeData - ) instances as data, which could be represented by the = - <rich:tree>= component. - - - Let's try to build a simple <ri= ch:tree> from a local XML file. - In the following example a simple XML file (stations.xml) is used as a ra= dio station playlist: - - +...]]> + This is a result: +
+ A simple <emphasis role=3D"bold"> + <property><rich:tree&= gt;</property> + </emphasis> from a + <code>org.richfaces.model.TreeNode= </code> + + + + + +
+ + Implementation of the + <rich:tree> + component provides another way t= o build a tree. This + approach implies using a + "XmlTreeDataBuilder&quo= t; class + ( org.richfaces.component.xml.XmlT= reeDataBuilder ) + that allows to transform XML into structures= of objects containing + "XmlNodeData" ( org.richfaces.component.xml.XmlN= odeData ) + instances as data, which could be represente= d by the + <rich:tree> + component. + Let's try to build a simple + <rich:tree> + from a local XML file. In the fo= llowing example a simple + XML file (stations.xml) is used as a radio s= tation playlist: + Hall & Oates - Kiss On My List @@ -199,21 +210,20 @@ KC & the Sunshine Band - Give It Up ]]> - - Now you need to create a bean that holds a model nodes: - - Now you need to create a bean that holds a mode= l nodes: + - - Finally you should set the "value" attribute to the = - data bean property and define the "= var" attribute in order to = - refer to the data of nodes: = - - Finally you should set the + "value" + attribute to the data bean property and + define the + "var" + attribute in order to refer to t= he data of nodes: + @@ -223,16 +233,18 @@ ...]]> - This is a result: -
- A simple <emphasis role=3D"bold"><property><rich:tree></pro= perty></emphasis> from a local XML file - - - - - -
- = + This is a result: +
+ A simple <emphasis role=3D"bold"> + <property><rich:tree&= gt;</property> + </emphasis> from a local XML file<= /title> + <mediaobject> + <imageobject> + <imagedata fileref=3D"im= ages/treeXML.png"/> + </imageobject> + </mediaobject> + </figure> + <para>It's possible to define a visual representa= tion of a node data model (to define a node icon) and its behavi= or in correspondence with the data contained in this node (with a valu= e of the <emphasis> @@ -250,7 +262,8 @@ <property>"type"</proper= ty> </emphasis> attribute equal to a value of <e= mphasis> <property>"nodeFace"</pr= operty> - </emphasis> is used for node representation.= See an example below.</para> + </emphasis> is used for node representation.= See an example + below.</para> = <para id=3D"example"> <emphasis role=3D"bold">Example:</emphasis> @@ -310,7 +323,8 @@ <property><rich:treeNode></p= roperty> </emphasis> with <emphasis> <property>"type"</proper= ty> - </emphasis> equal to "<code>artist</cod= e>" was used.</para> + </emphasis> equal to "<code>artist</cod= e>" was + used.</para> <para>You can also assign an EL-expression as value of= the <emphasis> <property>"nodeFace"</pr= operty> </emphasis> attribute. See an example below:= </para> @@ -324,7 +338,7 @@ <property>"nodeFace"</pr= operty> </emphasis> attribute usage: you need to def= ine notions for <property>typeless</property> and a - <property>default</property> nodes. </para> + <property>default</property> nodes= . </para> = <para>The <property>typeless node</property> is the fi= rst <emphasis role=3D"bold"> <property><rich:treeNode></p= roperty> @@ -339,7 +353,8 @@ for representation when <emphasis> <property>"nodeFace"</pr= operty> </emphasis> attribute is null.</para> - <para><property>Default node</property> has the follow= ing interior presentation:</para> + <para><property>Default node</property> has the follow= ing interior + presentation:</para> <para> <emphasis role=3D"bold">Example:</emphasis> </para> @@ -391,7 +406,8 @@ representation styles for the same node type= s. In the example with artists and their albums (see <link linkend= =3D"example">above</link>) it's possible to represent albums that = are available for sale - and albums that are not available. Please st= udy the example below:</para> + and albums that are not available. Please st= udy the example + below:</para> <para> <emphasis role=3D"bold">Example:</emphasis> </para> @@ -453,7 +469,7 @@ used performing the func= tionality. Note, that for collapse/expand operatio= ns an Ajax request is sent to the server and it can= cause a short - delay.</para> + delay.</para> </listitem> <listitem> <para><code>Server</code> - regula= r form of submission @@ -520,8 +536,9 @@ </emphasis> etc. </para> <para> Information about the <emphasis> <property>"process"</pro= perty> - </emphasis> attribute usage you can find in the = - <link linkend=3D"process"> "Decide what= to process" </link> guide section. </para> + </emphasis> attribute usage you can find in = the <link + linkend=3D"process"> "Decide = what to + process" </link> guide sectio= n. </para> <!--<tip> <title>Tip: @@ -531,23 +548,100 @@ <rich:tree&= gt; is pending! --> - - The value of - "rowKeyConverter" - can be: = - + + As it's mentioned before, the + <rich:tree> + component uses a data model to r= epresent the tree-like + nodes structure on the page. To identify a p= articular node during a + client request, the model provides a set of = unique keys for tree + nodes. The tree can use= strings as keys values + which may contain special characters not all= owed by browsers, such as + the left angle bracket (<), ampersand (&a= mp;), ant etc. Thus, to + have a possibility to use unallowed characte= rs in the + tree nodes, t= he following converters + are provided: - org.richfaces.TreeRowK= eyConverter - it used for the simple tree. + org.richfaces.TreeRowK= eyConverter that is + used for "= ;TreeNode" based trees. + The key should be of a + java.lang.String type. - org.richfaces.TreeAdap= torRowKeyConverter used for tree with <rich:treeNodesAdaptor> + org.richfaces.TreeAdap= torRowKeyConverter + that is used for adaptor= -based trees (see + + <rich:treeN= odesAdaptor> + , + <rich:recur= siveTreeNodesAdaptor> + ). The= key should be of a + java.lang.String type. - The org.richfaces.Tree= AdaptorIntegerRowKeyConverter converter used for adaptor-based tree = for implementing custom converters + org.richfaces.TreeAdap= torIntegerRowKeyConverter + which is provided for ad= aptor-based trees. The key + should be of a jav= a.lang.Integer + type. - = + + The converters can be extended in order to have = a possibility for + implementing custom converters. + To apply a converter to the + <rich:tree> + component, you should define it = as a value of the + "rowKeyConverter&qu= ot; + attribute. + + Have a look at the example of a tree which conta= ins the RichFaces + components as its nodes and the components a= ttributes as the nodes + child elements. As the components have unall= owed characters (< + and >) in their names, the org.rich= faces.TreeRowKeyConverter is used here. + + Example: + + = + + + + + +...]]> + = + In the example the tree uses the following data = model: + = + ", "< a4j:keepAlive >", "< = a4j:actionparam >" }; +String[ ][ ] attributes =3D {{"type"}, + {"ajaxOnly", "beanName"}, + {"actionListener", "assignTo", "binding", = "converter", "id", "name", "noEscape", "value"}}; + = +data =3D new TreeNodeImpl(); + = +for (int i =3D 0; i < components.length; i++) { + TreeNode child =3D new TreeNodeImpl(); + child.setData(components[i]); + data.addChild(components[i], child); + = + for (int j =3D 0; j < attributes[i].length; j++) { + TreeNode grandChild =3D new TreeNodeImpl(); + grandChild.setData(attributes[i][j]); + child.addChild(attributes[i][j], grandChild); + } +} = +...]]> + = + This is the result: + = +
+ The tree with the <code>org.richfaces= .TreeRowKeyConverter</code> usage + + + + + +
=
@@ -573,9 +667,8 @@ dragValue - Element value dra= g passed into - processing after a Drop - event + Element value dra= g passed into processing + after a Drop event dragListener @@ -584,17 +677,14 @@ dragIndicator - Id of a component= that is used as - a drag pointer during th= e drag - operation + Id of a component= that is used as a drag + pointer during the drag = operation dragType - Defines a drag zo= ne type that is - used for definition of a - dragged element, which c= an be - accepted by a drop - zone + Defines a drag zo= ne type that is used for + definition of a dragged = element, which can be + accepted by a drop zone<= /entry> @@ -612,26 +702,23 @@ dropValue - Element value dro= p passed into - processing after Drop ev= ents - + Element value dro= p passed into processing + after Drop events dropListener - A listener that p= rocesses a Drop - event. + A listener that p= rocesses a Drop event. + acceptedTypes - Drag zone names a= re allowed to be - processed with a Drop - zone + Drag zone names a= re allowed to be processed + with a Drop zone typeMapping Drag zones names = mapping on the - corresponding drop zone - parameters + corresponding drop zone = parameters @@ -644,8 +731,7 @@ these zones completely correspon= d to tree nodes. So, all dragging nodes should be marked with "dragType" - attribute. - Then, to mark zone(-s), where the dragging n= ode + attribute. Then, to mark zone(-s= ), where the dragging node could be dropped, pass the type of dragging = node to the "acceptedTypes"= ; attribute of the drop zone. It w= ould be good to itemize, @@ -664,14 +750,15 @@ <rich:tree> . Chapters "6.40 - <dragIndicator>" and "= ;6.39 - <dndParam>" describes how = to apply - visual element, that show some additional in= formation (e.g. dragging - item name) while operating with dr= ag-and-drop. + <dragIndicator>"= and + "6= .39 + <dndParam>" desc= ribes how to + apply visual element, that show some additio= nal information (e.g. + dragging item name) while operating with + drag-and-drop= . Page code, that describes a tree with built in - drag-and-drop in the wa= y it is considered, is - shown below. + drag-and-drop= in the way it is + considered, is shown below. = Example: @@ -730,7 +817,7 @@ nodeSelectListener= is called during request sending o= n a node selecting event (if request sending on t= his event is - defined) + defined) = @@ -788,46 +875,53 @@ role=3D"bold"> <rich:tree> component capture events occured= on any - tree part. But event ha= ndlers of + tree part. Bu= t event handlers of treeNode capt= ure events occured on treeNode only= , except for children events.
- = -
- Facets - - Facets - - - - Facet name - Description - - - - - icon - Redefines the icon for node. Related attribute is "icon= " - - - iconCollapsed - Redefines the icon for collapsed node. Related attribute is = "iconCollapsed" - - - iconExpanded - Redefines the icon for expanded node. Related attribute is &= quot;iconExpanded" - - - iconLeaf - Redefines the icon for component leaves. Related attribute i= s "iconLeaf" - - - -
-
- = +
+ Facets + + Facets + + + + Facet name + Description + + + + + icon + Redefines the ico= n for node. Related + attribute is "icon&= quot; + + + iconCollapsed + Redefines the ico= n for collapsed node. + Related attribute is + "iconCollapsed"= ; + + + iconExpanded + Redefines the ico= n for expanded node. + Related attribute is + "iconExpanded"= + + + iconLeaf + Redefines the ico= n for component leaves. + Related attribute is + "iconLeaf" + + + +
+
+ +
Look-and-Feel Customization = For skinnability implementation, the components = use a @@ -898,8 +992,7 @@ rich-tree Defines styles fo= r a wrapper - <div> element of - a tree + <div> element of a= tree @@ -955,7 +1048,8 @@ "highlightedClass&q= uot; attribute for <rich:tree> - is defined as it's shown in= the example below: + is defined as it's shown in= the example + below: = Example: @@ -966,7 +1060,8 @@ This is a result: =
- Redefinition styles with own classes = and styleClass attributes + Redefinition styles with own classes = and styleClass + attributes @@ -983,8 +1078,8 @@ On the component LiveDemo page you can see the example of + >On the component LiveDemo page you can see the + example of <rich:tree> usage and sources for the given = example. How to Expand/Collapse Tree Nodes from code, see= in this