Create new RichFaces Documentation Jira issue

This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.

JBoss.orgCommunity Documentation

6.6.1.  < rich:column > available since 3.0.0

The component for row rendering for a UIData component.


To output a simple table, the <rich:column> component is used the same way as the standard <h:column> , i.e. the following code on a page is used:

Example:


...
<rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5"> 
     <rich:column>
          <f:facet name="header">State Flag</f:facet>
          <h:graphicImage value="#{cap.stateFlag}"/>
     </rich:column>
     <rich:column>
           <f:facet name="header">State Name</f:facet>
           <h:outputText value="#{cap.state}"/>
     </rich:column>
     <rich:column >
          <f:facet name="header">State Capital</f:facet>
          <h:outputText value="#{cap.name}"/>
     </rich:column>
     <rich:column>
          <f:facet name="header">Time Zone</f:facet>
          <h:outputText value="#{cap.timeZone}"/>
     </rich:column>
</rich:dataTable>
...

The result is:


Now, in order to group columns with text information into one row in one column with a flag, use the "colspan" attribute, which is similar to an HTML one, specifying that the first 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="true".

Example:


...
<rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5"> 
     <rich:column colspan="3">
          <h:graphicImage value="#{cap.stateFlag}"/>
     </rich:column>
     <rich:column breakBefore="true"> 
          <h:outputText value="#{cap.state}"/>
     </rich:column>
     <rich:column >
          <h:outputText value="#{cap.name}"/>
     </rich:column>
     <rich:column>
          <h:outputText value="#{cap.timeZone}"/>
     </rich:column>
</rich:dataTable>
...

As a result the following structure is rendered:


The same way is used for columns grouping with the "rowspan" attribute that is similar to an HTML one responsible for rows quantity definition occupied with the current one. 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="#{capitalsBean.capitals}" var="cap" rows="5"> 
     <rich:column rowspan="3">
          <f:facet name="header">State Flag</f:facet>
          <h:graphicImage value="#{cap.stateFlag}"/>
     </rich:column>
     <rich:column> 
          <f:facet name="header">State Info</f:facet>
          <h:outputText value="#{cap.state}"/>
     </rich:column>
     <rich:column breakBefore="true">
          <h:outputText value="#{cap.name}"/>
     </rich:column>
     <rich:column breakBefore="true">
          <h:outputText value="#{cap.timeZone}"/>
     </rich:column>
</rich:dataTable>
...

As a result:


Hence, additionally to a standard output of a particular row provided with the <h:column> component, it becomes possible to group easily the rows with special HTML attribute.

The columns also could be grouped in a particular way with the help of the <h:columnGroup> component that is described in the following chapter.

In the Dynamic Columns Wiki article you can find additional information about dynamic columns.

In order to sort the columns you should use "sortBy" attribute that indicates what values to be sorted.This attribute can be used only with the <rich:dataTable> component. In order to sort the column you should click on its header. See the following example.

Example:


...
<h:form>
    <rich:dataTable value="#{capitalsBean.capitals}" var="cap" width="300px">
        <f:facet name="header">
            <h:outputText value="Sorting Example"/>
        </f:facet>
        <rich:column sortBy="#{cap.state}">
            <f:facet name="header">
                <h:outputText value="State Name"/>
            </f:facet>
            <h:outputText value="#{cap.state}"/>
        </rich:column> 
        <rich:column sortBy="#{cap.name}">
            <f:facet name="header">
                <h:outputText value="State Capital"/>
            </f:facet>
            <h:outputText value="#{cap.name}"/> 
        </rich:column>
    </rich:dataTable>
</h:form>
...

This is result:


The "sortExpression" attribute defines a bean property which is used for sorting of a column. This attribute can be used only with the <rich:scrollableDataTable> component. The following example is a example of the attribute usage.

Example:


...
<rich:scrollableDataTable id="carList"
        value="#{dataTableScrollerBean.allCars}" sortMode="single"
        binding="#{dataTableScrollerBean.table}">
        <rich:column id="make" sortExpression="#{cap.make}">
            <f:facet name="header">
                <h:outputText styleClass="headerText" value="Make" />
            </f:facet>
            <h:outputText value="#{category.make}" />
        </rich:column>
        <rich:column id="model">
            <f:facet name="header">
                <h:outputText styleClass="headerText" value="Model" />
            </f:facet>
            <h:outputText value="#{category.model}" />
        </rich:column>
        <rich:column id="price">
            <f:facet name="header">
                <h:outputText styleClass="headerText" value="Price" />
            </f:facet>
            <h:outputText value="#{category.price}" />
        </rich:column>
</rich:scrollableDataTable>
...

The "selfSorted" attribute that would add the possibility of automatic sorting by clicking the column header. Default value is "true". In the example below the second column is unavailable for sorting.

Example:


...
<rich:dataTable value="#{capitalsBean.capitals}" var="cap">
        <rich:column>
                <f:facet name="header">
                        <h:outputText value="State Flag"/>
                </f:facet>
                <h:graphicImage value="#{cap.stateFlag}"/> 
        </rich:column>
        <rich:column sortBy="#{cap.state}" selfSorted="false"> 
                <f:facet name="header">
                        <h:outputText value="State Name"/>
                </f:facet>
                <h:outputText value="#{cap.state}"/>
        </rich:column> 
</rich:dataTable>
...

"sortOrder" attribute is used for changing the sorting of columns by means of external controls.

Possible values are:

  • "ASCENDING" - column is sorted in ascending

  • "DESCENDING" - column is sorted in descending

  • "UNSORTED" - column isn't sorted

Example:


...
<h:form>
    <rich:dataTable value="#{capitalsBean.capitals}" var="cap" width="300px">
        <f:facet name="header">
            <h:outputText value="Sorting Example"/>
        </f:facet>
        <rich:column sortBy="#{cap.state}" sortOrder="ASCENDING">
            <f:facet name="header">
                <h:outputText value="State Name"/>
            </f:facet>
            <h:outputText value="#{cap.state}"/>
        </rich:column> 
        <rich:column sortBy="#{cap.name}" sortOrder="DESCENDING">
            <f:facet name="header">
                <h:outputText value="State Capital"/>
            </f:facet>
            <h:outputText value="#{cap.name}"/> 
        </rich:column>
    </rich:dataTable>
</h:form>
...

Below you can see the result:


In the example above the first column is sorted in descending order. But if recurring rows appear in the table the relative second column are sorted in ascending order.

If the values of the columns are complex, the "sortOrder" attribute should point to a bean property containing the sort order. See how it's done in the LiveDemo for <rich:columns> .

You can customize the sorting's icon element using "rich-sort-icon" class.

Note

In order to sort a column with the values not in English you can add the org.richfaces.datatableUsesViewLocale context parameter in your web.xml. Its value should be "true".

Note:

The "sortBy" and the "selfSorted" attributes used with the <rich:dataTable> component. Also the "selfSorted" can be used with the <rich:extendedDataTable> .

The "sortable" and the "sortExpression" attributes used with the <rich:scrollableDataTable> component.

There are two ways to filter the column value:

Table of <rich:column> attributes.



You can find all necessary information about style classes redefinition in
Definition of Custom Style Classes section.

Visit Column page at RichFaces live demo for examples of component usage and their sources.

" Using the "rendered" attribute of <rich:column>" article in RichFaces cookbook at JBoss portal gives an example of code of the component usage case.