6.30.  < rich:columns >

6.30.1. Description

The <rich:columns> is a component, that allows you to create a dynamic set of columns from your model.

<rich:columns> component

Figure 6.34.  <rich:columns> component


6.30.2. Key Features

  • Highly customizable look and feel

  • Dynamic tables creation

  • Possibility to combine columns with the help of "colspan" and "breakBefore"

  • Possibility to combine rows with the help of "rowspan"

  • Sorting column values

  • Filtering column values

Table 6.117. rich : columns attributes

Attribute NameDescription
beginThe first iteration item
bindingThe attribute takes a value-binding expression for a component property of a backing bean
breakBeforeif "true" next column begins from the first row
colspanCorresponds to the HTML colspan attribute
columnsCount of columns
comparatorDefines value binding to the comparator that is used to compare the values
dirDirection indication for text that does not inherit directionality. Valid values are "LTR" (left-to-right) and "RTL" (right-to-left)
endThe last iteration item
filterByDefines iterable object property which is used when filtering performed.
filterEventEvent for filter input that forces the filtration (default = onchange)
filterExpressionAttribute defines a bean property which is used for filtering of a column
filterMethodThis attribute is defined with method binding. This method accepts on Object parameter and return boolean value
filterValueDefines current filtering value
footerClassSpace-separated list of CSS style class(es) that are be applied to any footer generated for this table
headerClassSpace-separated list of CSS style class(es) that are be applied to any header generated for this table
idEvery component may have a unique id that is automatically created if omitted
indexThe current counter
langCode describing the language used in the generated markup for this component
renderedIf "false", this component is not rendered
rowspanCorresponds to the HTML rowspan attribute
selfSortedManages if the header of the column is clickable, icons rendered and sorting is fired after click on the header. You need to define this attribute inside <rich:dataTable> component
sortableBoolean attribute. If "true" it's possible to sort the column content after click on the header. Default value is "true"
sortByAttribute defines a bean property which is used for sorting of a column
sortExpressionDEPRECATED(use sortBy)Attribute defines a bean property which is used for sorting of a column
sortIconDefines sort icon
sortIconAscendingDefines sort icon in ascending order
sortIconDescendingDefines sort icon in descending order
sortOrderSortOrder is an enumeration of the possible sort orderings.
styleCSS style(s) is/are to be applied when this component is rendered
styleClassCorresponds to the HTML class attribute
titleAdvisory title information about markup elements generated for this component
valueThe current value for this component
varThe current variable
widthAttribute defines width of column.

Table 6.118. Component identification parameters

NameValue
component-typeorg.richfaces.Column
tag-classorg.richfaces.taglib.ColumnsTagHandler

6.30.3. Creating the Component with a Page Tag

To create the simplest variant on a page use the following syntax:

Example:


...
<rich:dataTable value="#{capitalsBean.capitals}" var="cap">
        <rich:columns value="#{capitalsBean.labels}" var="col" index="index">
                <h:outputText value="#{cap[index]}" />
        </rich:columns> 
</rich:dataTable>
...

6.30.4. Creating the Component Dynamically Using Java

Example:


import org.richfaces.component.html.HtmlColumns;
... 
HtmlColumns myColumns = new HtmlColumns();
...

6.30.5. Details of Usage

The <rich:columns> component gets a list from data model and outputs corresponding set of columns inside <rich:dataTable> on a page. It is possible to use "header" and "footer" facets with <rich:columns> component.

The "value" and "var" attributes are used to access the values of collection.

The simple example is placed below.

Example:


...
<rich:dataTable value="#{capitalsBean.capitals}" var="cap">
        <rich:columns value="#{capitalsBean.labels}" var="col" index="index">
                <f:facet name="header">
                        <h:outputText value="#{col.text}" />
                </f:facet>
         <h:outputText value="#{cap[index]}" />
         <f:facet name="footer">
                 <h:outputText value="#{col.text}" />
         </f:facet>
        </rich:columns> 
</rich:dataTable>
...

The "columns" attribute defines the count of columns.

The "rows" attribute defines the number of rows to be displayed. If the value of this attribute is zero, all remaining rows in the table are displayed on a page.

The "begin" attribute contains the first iteration item. Note, that iteration begins from zero.

The "end" attribute contains the last iteration item.

With the help of the attributes described below you can customize the output, i.e. define which columns and how many rows appear on a page.

Example:


...
<rich:dataTable value="#{capitalsBean.capitals}" var="cap">
        <rich:columns value="#{capitalsBean.labels}" var="col" index="index" rows="0" columns="3" begin="1" end="2">
                <f:facet name="header">
                        <h:outputText value="#{col.text}" />
                </f:facet>
                <h:outputText value="#{cap[index]}" />
        </rich:columns> 
</rich:dataTable>
...

In the example below, columns from first to second and all rows are shown in the <rich:dataTable> .

The result is:

Generated <rich:columns> with columns from first to second and all rows

Figure 6.35. Generated <rich:columns> with columns from first to second and all rows


The <rich:columns> component does not prevent to use <rich:column> . In the following example one column renders in any way and another columns could be picked from the model.

Example:


...
<rich:dataTable value="#{rowBean.rows}" var="row">
        <rich:column>
                <h:outputText value ="#{row.columnValue}"/>
        </rich:column>
        <rich:columns value="#{colBean.columns}" var="col">
                <f:facet name="header">
                        <h:outputText value="#{col.header}"/>
                </f:facet>
                <h:outputText value="#{row.columnValue}"/>
                <f:facet name="footer">
                        <h:outputText value="#{col.footer}"/>
                </f:facet>
        </rich:columns>
</rich:dataTable>   
...

In order to group columns with text information into one row, use the "colspan" attribute, which is similar to an HTML one. In the following example the third column contains 3 columns. In addition, it's necessary to specify that the next column begins from the first row with the help of the "breakBefore" attribute = true.

Example:


...
<rich:dataTable value="#{columns.data1}" var="data">
        <rich:column>
                <h:outputText value="#{column.Item1}" />
        </rich:column>
        <rich:column>
                <h:outputText value="#{column.Item2}" />
        </rich:column>
        <rich:column>
                <h:outputText value="#{column.Item3}" />
        </rich:column>
        <rich:columns columns="3" colspan="3" breakBefore="true">   
                <h:outputText value="#{data.str0}" />
        </rich:columns>
</rich:dataTable>
...

The same way is used for columns grouping with the "rowspan" attribute that is similar to an HTML. The only thing to add in the example is an instruction to move onto the next row for each next after the second column.

Example:


...
<rich:dataTable value="#{columns.data1}" var="data">
        <rich:columns columns="2" rowspan="3">  
                <h:outputText value="#{data.str0}" />
        </rich:columns>
        <rich:column>
                <h:outputText value="#{column.Item1}" />
        </rich:column>
        <rich:column  breakBefore="true">
                <h:outputText value="#{column.Item2}" />
        </rich:column>
        <rich:column  breakBefore="true">
                <h:outputText value="#{column.Item3}" />
        </rich:column>
</rich:dataTable>
...

Information about sorting and filtering you can find here.

6.30.6. Look-and-Feel Customization

For skinnability implementation, the components use a style class redefinition method. Default style classes are mapped on skin parameters.

There are two ways to redefine the appearance of all <rich:columns> components at once:

  • Redefine the corresponding skin parameters

  • Add to your style sheets style classes used by a <rich:columns> component

6.30.7. Skin Parameters Redefinition

Skin parameters redefinition for <rich:columns> are the same as for the <rich:dataTable> component.

6.30.8. Definition of Custom Style Classes

Custom style classes for <rich:columns> are the same as for the <rich:dataTable> component.

In order to redefine styles for all <rich:columns> components on a page using CSS, it's enough to create classes with the same names and define necessary properties in them.

To change styles of particular <rich:columns> components, define your own style classes in the corresponding <rich:columns> attributes.

6.30.9. Relevant Resources Links

Here you can found some additional information for <rich:columns> component usage.