From richfaces-svn-commits at lists.jboss.org Mon Apr 4 02:50:07 2011 Content-Type: multipart/mixed; boundary="===============8298854180358446110==" 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: r22359 - in modules/docs/trunk/Component_Reference/src/main/docbook/en-US: extras and 1 other directory. Date: Mon, 04 Apr 2011 02:50:06 -0400 Message-ID: <201104040650.p346o66B028302@svn01.web.mwc.hst.phx2.redhat.com> --===============8298854180358446110== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: SeanRogers Date: 2011-04-04 02:50:06 -0400 (Mon, 04 Apr 2011) New Revision: 22359 Added: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exa= m-Component_Reference-a4jrepeat-Update_a_single_component.xml_sample Modified: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Compo= nent_Reference-Tables_and_grids.xml Log: Revised Tables and Grids chapter according to Engineering review: RFPL-1380 Modified: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/cha= p-Component_Reference-Tables_and_grids.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 --- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Comp= onent_Reference-Tables_and_grids.xml 2011-04-04 00:05:53 UTC (rev 22358) +++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Comp= onent_Reference-Tables_and_grids.xml 2011-04-04 06:50:06 UTC (rev 22359) @@ -11,8 +11,11 @@
<sgmltag><a4j:repeat></sgmltag> - The <a4j:repeat> component is used to iterate = changes through a repeated collection of components. It allows specific row= s of items to be updated without sending Ajax requests for the entire colle= ction. The <a4j:repeat> component forms the basis = for many of the tabular components detailed in . + The non-visual <a4j:repeat> component is used = to iterate through a data model. The component renders child content for ev= ery iteration according to the current object data. + + The <a4j:repeat> component extends the standar= d UIRepeat component to allow partial updates within= iterations while sending Ajax requests. The component acts as a base for a= ll the data iteration components detailed in this chapter. + =
Basic usage @@ -34,43 +37,42 @@ The <a4j:repeat> component uses other attribu= tes common to iteration components, such as the first at= tribute for specifying the first item for iteration, and the rows<= /varname> attribute for specifying the number of rows of items to display. - Specific cells, rows, and columns can be updated without sending Ajax = requests for the entire collection. Components that cause the change can sp= ecify which part of the table to update through the render attribute. The render attribute specifies which part = of a table to update: + Specific cells, rows, and columns can be updated without sending Ajax = requests for the entire collection. Components that cause the change can sp= ecify which part of the table to update through the render attribute. The render attribute specifies which part = of a table to update. The updated parts relate to where the action componen= t is placed relative to the table: - render=3DcellId + Action components inside the table - Update the cell with an identifier of cellId within the row that contains the current component. + Use render=3DcomponentID where the component identified by componentID= is in the same row as the action component. The action compo= nent updates the single specified component, as demonstrated in . - - Instead of a specific identifier, the cellId reference could be a variable: render=3D#{bean.cellToUpdate}. - + + Update a single component + + - render=3DtableId:rowId + Action components outside the table - Update the row with an identifier of rowId within the table with an identifier of tableId. Alternatively, if the current component is contained within the table, u= se render=3DrowId. + Use render=3DtableId:rowId:cellId to specify the cell to update. The action component updates the cell w= ith an identifier of cellId, which is within the= row with an identifier of rowId, which is withi= n the table with an identifier of tableId. - Instead of a specific identifier, the tableId of rowId references could be variables: render=3DtableId:#{bean.rowToUpdate}. + Instead of a specific identifier, any of the references could be va= riables, as demonstrated in . + + Use variables to specify references + render=3DtableId:#{@rows(bean.rowToUpdate)}:cellId + + The @rows function accepts a collection of ro= w keys to be updated. + + - - render=3DtableId:rowId:cellId - - - Update the cell with an identifier of cellId, within the row with and identifier of rowId, within the table with an identifier of tableId. - - - Instead of a specific identifier, any of the references could be va= riables: render=3DtableId:#{bean.rowToUpdate}:cellId. - - - + = +
=
@@ -149,12 +152,12 @@
<sgmltag><rich:dataTable></sgmltag> - The <rich:dataTable> component is used to rend= er a table, including the table's header and footer. It works in conjunctio= n with the <rich:column> and <rich:col= umnGroup> components to list the contents of a data model. + The <rich:dataTable> component is used to rend= er a table, including the table's caption. It works in conjunction with the= <rich:column> and <rich:columnGroup&g= t; components to list the contents of a data model. <sgmltag><rich:extendedDataTable></sgmltag> - The <rich:dataTable> component does not inclu= de extended table features, such as data scrolling, row selection, and colu= mn reordering. These features are available as part of the <ric= h:extendedDataTable> component; refer to for further= details. + The <rich:dataTable> component does not inclu= de extended table features, such as data scrolling (including lazy Ajax loa= ding), row selection, and column reordering. These features are available a= s part of the <rich:extendedDataTable> component; = refer to for further details. = @@ -163,6 +166,9 @@ The value attribute points to the data model, and t= he var attribute specifies a variable to use when iterat= ing through the data model. + + In addition, the table requires a set of <rich:column><= /sgmltag> components to define the content of the table. +
=
@@ -201,6 +207,12 @@ As <rich:dataTable> the component is based on= the <a4j:repeat> component, it can be partially u= pdated with Ajax. Refer to for details on partially updating= the <rich:dataTable> component. + + The <rich:dataTable> component supports maste= r-detail markup with collapsible sub-table sections. Refer to f= or full details on using the <rich:collapsibleSubTable> component. + + + Use the rows attribute to specify the number of row= s to show at a time. The table is then presented in pages of rows. Pages ca= n be navigated by using a control such as the <rich:dataScrolle= r> component. Refer to for full details on using the <rich:dataScroller> component. +
=
@@ -226,7 +238,7 @@ - switchSubTables() + switchSubTable(subtableId) Switch the expanded or collapsed state of any sub-tables = contained in the data table. @@ -561,8 +573,11 @@
<sgmltag><rich:collapsibleSubTable></sgmltag> - The <rich:collapsibleSubTable> component acts = as a child element to a <rich:dataTable> component= . It allows sections of a table to be grouped into collapsible sections. Th= e <rich:collapsibleSubTable> component works with = the <rich:collapsibleSubTableToggler> component, w= hich allows the user to expand and collapse the sub tables. + The <rich:collapsibleSubTable> component acts = as a child element to a <rich:dataTable> component= . The <rich:collapsibleSubTable> component iterate= s through the child collections in the currently iterated object to create = master-detail tables. + + Additionally, the detail part of the table can be collapsed or expanded= through different modes. The <rich:collapsibleSubTable> component works with the <rich:collapsibleSubTableToggle= r> component, which expands and collapses the sub-tables. + =
Basic usage @@ -678,6 +693,13 @@ Refer to for an example using the <rich:collapsibl= eSubTable> component. In the example, the toggle control is pl= aced in a column that spans the width of the table. Output text next to the= toggle control displays the car vendor's name for that sub-table.
+ +
+ Appearance + + The icons and labels of the <rich:collapsibleSubTableTogg= ler> component can be customized. Use the collapsedIc= on and expandedIcon attributes to specify icon= s for the toggler when it is collapsed and expanded respectively. Use the <= varname>collapsedLabel and expandedLabel attri= butes to specify labels for the toggler when it is collapsed and expanded r= espectively. + +
=
Reference data @@ -721,7 +743,7 @@
<sgmltag><rich:extendedDataTable></sgmltag> - The <rich:extendedDataTable> component builds = on the functionality of the <rich:dataTable> compo= nent, adding features such as data scrolling, row and column selection, and= rearranging of columns. + The <rich:extendedDataTable> component builds = on the functionality of the <rich:dataTable> compo= nent, adding features such as scrolling for the table body (both horizontal= and vertical), Ajax loading for vertical scrolling, frozen columns, row se= lection, and rearranging of columns. It also supports all the basic table f= eatures such as sorting, filtering, and paging using the <rich:= dataScroller> component. = The <rich:extendedDataTable> component include= s the following main attributes not included in the <rich:dataT= able> component: @@ -762,51 +784,7 @@ selectionMode - - - The <rich:extendedDataTable> component does not include the following attributes available with the = <rich:dataTable> component: - - - - - - breakBefore - - - - - columnGroup - - - - - colSpan - - - - - rowSpan - - - = Complex sub-tables @@ -814,21 +792,21 @@ Due to the complex mark-up involved in the <rich:extendedD= ataTable> component, it does not support the use of the <rich:collapsibleSubTable> component. The <r= ich:collapsibleSubTable> component is only available with the = <rich:dataTable> component. - Similarly, complex row and column spanning using the breakBef= ore, columnGroup, colSpan, = and rowSpan attributes is also not available with the <rich:extendedDataTable> component. + Similarly, complex row and column spanning using the breakBef= ore, colSpan, and rowSpan a= ttributes is also not available with the <rich:extendedDataTabl= e> component. =
Basic usage - Basic use of the <rich:extendedDataTable> com= ponent requires the value and var att= ributes, the same as with the <rich:dataTable> com= ponent. Refer to for details. + Basic use of the <rich:extendedDataTable> com= ponent requires the value and var att= ributes, the same as with the <rich:dataTable> com= ponent. In addition, a set of columns must be included to define the table = content. Refer to for details.
=
Table appearance - The height attribute defines the height of the tabl= e on the page. This is set to 100% by default. The width= of the table can be set by using the width attribute. A= s with the <rich:dataTable> component, the look of= the <rich:extendedDataTable> component can be cus= tomized and skinned using the header and footer= facets. + As with the <rich:dataTable> component, the l= ook of the <rich:extendedDataTable> component can = be customized using the header and footer facets.
= @@ -861,7 +839,7 @@ Large tables can use Ajax "lazy" loading to cache data on the client = during scrolling. Use the clientRows attribute to specif= y the number of rows to load. The specified number of rows are loaded on th= e initial rendering and with every vertical scroll. If the clientR= ows attribute is not specified, all the rows are loaded on the cl= ient without the use of Ajax. - In addition to Ajax scrolling, the <rich:extendedDataTabl= e> component can also be used with the <rich:dataS= croller> component in the same way as a regular <r= ich:dataTable> component. Refer to for full details on us= ing the <rich:dataScroller> component. + In addition to Ajax scrolling, the <rich:extendedDataTabl= e> component can also be used with the <rich:dataS= croller> component in the same way as a regular <r= ich:dataTable> component. If both the clientRows and rows attributes are included, Ajax loading occ= urs as defined by the clientRows attribute, but the load= ing is limited to the current table page as determined by the rows= attribute. Refer to for full details on using the = <rich:dataScroller> component.
= @@ -1488,7 +1466,7 @@
Basic usage - The <rich:dataScroller> must be placed in the= footer facet of the table or grid it needs to control. = Alternatively, use the for attribute to bind the parent = table or grid to the scroller. + The <rich:dataScroller> must be placed in a f= acet of the table or grid it needs to control. Alternatively, use the for attribute to bind the parent table or grid to the scrolle= r. The bound table or grid should also have the rows a= ttribute defined to limit the number of rows per page. @@ -1531,6 +1509,8 @@ + + To add optional separators between controls, define the separators w= ith the controlsSeparator facet. @@ -1722,9 +1703,12 @@ = + + - Use the filterExpression attribute to define an exp= ression that can be evaluated as a boolean value. The expression checks if = each table entry satisfies the filtering condition when the table is render= ed. + Use the filterExpression attribute to define an exp= ression that can be evaluated as a boolean value. The expression checks if = each table entry satisfies the filtering condition when the table is render= ed. For example, the expression might be a JSTL (JavaServer Pages Standard = Tag Library) function such as contains or eq= uals. - Use the filterMethod attribute to define a method b= inding. The method needs to accept an object as a parameter and return a bo= olean value. Similar to the filterExpression attribute, = the table is rendered only with those entries that satisfy the filtering co= ndition. By defining a custom filtering method, you can implement complex b= usiness logic to filter a table. + Use the filter attribute to define a filter interfa= ce. The attribute must use EL (Expression Language) to point to an object w= hich implements the org.richfaces.model.Filter<T> interface. The object must provide a single accept(= T t) method. The method takes each iteration object as a param= eter and returns a boolean value, which determines whether the object satis= fies the filter. By defining a custom filter, you can implement complex bus= iness logic to filter a table. + + Use the filterValue attribute to point to an object= which holds the current filtering value for the column. The attribute can= be used to store filtering conditions in a session. Alternatively, use the= filterValue attribute when using the JavaScript API for= filtering. The attribute can store a value to pass as parameter to a JavaS= cript filter method. + External filtering @@ -1782,7 +1770,7 @@ -
+
=
@@ -1838,15 +1826,21 @@ Use the sortMode attribute to determine how multipl= e columns are sorted. By default, the value of the sortMode attribute is single, so tables are only sorted by a = single column. Each time the header of a column is clicked the entire table= is re-sorted according to that column. Set sortMode=3D"multiple" to allow tables to be sorted by a primary column, then by a secondary c= olumn, and so on.
- --> =
External sorting + --> - Bind the sortOrder attribute to bean properties to = manage the sorting order externally. The bean must handle all the sorting a= lgorithms. demonstrates table sorting using an external control. + Set the sortBy attribute to indicate which iteratio= n object property to use when sorting the column. By default, the target wi= ll be sorted using the compare() method. - - External sorting + + If using custom-defined rules for sorting, use the comparator= attribute instead. Set the comparator attribu= te to point to your comparator method, which will be used when sorting the = data model. + + + Bind the sortOrder attribute to bean properties to = manage the sorting order. The bean must handle all the sorting algorithms. = demonstrates table sorting using an external control. + + + Sorting The example uses an external control to manage the table's sorting. @@ -1863,12 +1857,9 @@ - When using the sortMode=3D"multiple" configuration, set t= he priority by which columns are sorted with the sortPriorities attribute. + When multiple columns are capable of being sorted at the same time, se= t the priority by which the columns are sorted with the sortPriori= ties attribute. The attribute must contain a list of column ident= ifiers in the order of the sorting sequence. - - Use the sortExpression attribute to define a bean p= roperty to use for sorting the column. The expression checks each table ent= ry against the sorting expression during rendering. - -
+
= Added: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras= /exam-Component_Reference-a4jrepeat-Update_a_single_component.xml_sample =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 --- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/ex= am-Component_Reference-a4jrepeat-Update_a_single_component.xml_sample = (rev 0) +++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/ex= am-Component_Reference-a4jrepeat-Update_a_single_component.xml_sample 2011-= 04-04 06:50:06 UTC (rev 22359) @@ -0,0 +1,6 @@ + + + + + + --===============8298854180358446110==--