6.6.1. < rich:column > available since 3.0.0

### Create new RichFaces Documentation Jira issue

Summary
255 characters left
Description
Environment
This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.

JBoss.org Community Documentation

- Prev
- Next

### 6.6.1. < rich:column > available since 3.0.0

expand all

#### 6.6.1.1. Description

The component is meant for row rendering in UIData components.

Figure 6.13. <rich:column> component

#### 6.6.1.2. Key Features

- Completely skinned table rows and child elements

- Possibility to combine columns with the help of "colspan"

- Possibility to combine rows with the help of "rowspan" and "breakBefore"

- Sorting column values

- Filtering column values

## Important

The "colspan", "rowspan", and "breakbefore" attributes only affect columns in a <rich:dataTable>, not those in a <rich:extendedDataTable>.

#### 6.6.1.3. Details of Usage

To output a simple table, the <rich:column> component is used the same way as the standard <h:column> . See the example of the component usage below:

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:

Figure 6.14. Generated <rich:column> component

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 `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:

Figure 6.15. <rich:column> modified with "colspan" and "breakbefore" attributes

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 row 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:

Figure 6.16. <rich:column> generated with "rowspan" attribute

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.

#### 6.6.1.4. Sorting and Filtering

expand all

##### 6.6.1.4.1. Sorting

In order to sort the columns you should use the "sortBy" attribute that indicates what values to be sorted. This attribute can be used only with the <rich:dataTable> component. Expressions in the "sortBy" attribute can refer only to the variable declared with the "var" attribute, not to those declared with other attributes such as the "rowKeyVar" attribute. 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:

Figure 6.17. <rich:column> with "sortBy" attribute

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

Example:

    ...

    <rich:scrollableDataTable

            value="#{dataTableScrollerBean.allCars}" sortMode="single"

            var="category">

            <rich:column sortExpression="#{category.make}">

                <f:facet name="header">

                    <h:outputText styleClass="headerText" value="Make" />

                </f:facet>

                <h:outputText value="#{category.make}" />

            </rich:column>

            <rich:column>

                <f:facet name="header">

                    <h:outputText styleClass="headerText" value="Model" />

                </f:facet>

                <h:outputText value="#{category.model}" />

            </rich:column>

            <rich:column>

                <f:facet name="header">

                    <h:outputText styleClass="headerText" value="Price" />

                </f:facet>

                <h:outputText value="#{category.price}" />

            </rich:column>

    </rich:scrollableDataTable>

    ...

The "selfSorted" attribute is meant for adding the possibility of automatic sorting by clicking on 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>

    ...

The "sortOrder" attribute is used for changing the sort order of columns by means of external controls.

Possible values are:

- "ASCENDING" - column is sorted in ascending order

- "DESCENDING" - column is sorted in descending order

- "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:

Figure 6.18. <rich:column> with "sortOrder" attribute

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.

##### 6.6.1.4.2. Filtering

There are two ways to filter the column value:

- Using built-in filtering. It uses `startsWith()` function to make filtering. In this case you need to define the "filterBy" attribute at a column you want to be filterable. This attribute defines iterable object property which is used when filtering performed. Expressions in the "filterBy" attribute can refer only to the variable declared with the "var" attribute, not to those declared with other attributes such as the "rowKeyVar" attribute.

  The "filterValue" attribute is used to get or change current filtering value. It could be defined with initial filtering value on the page or as value binding to get/change it on server. If the "filterValue" attribute isn't empty from the beginning table is filtered on the first rendering.

  You can customize the input form using "rich-filter-input" CSS class.

  In order to change filter event you could use "filterEvent" attribute on column, e.g. "onblur"(default value).

  Below you can see the example:

  Example:

      ...

      <rich:dataTable value="#{capitalsBean.capitals}" var="cap" width="200px">

              <f:facet name="header">

                  <h:outputText value="Sorting Example"/>

              </f:facet>

              <rich:column filterBy="#{cap.state}" filterEvent="onkeyup">

                      <f:facet name="header">

                          <h:outputText value="State Name"/>

                      </f:facet>

                     <h:outputText value="#{cap.state}"/>

              </rich:column>

              <rich:column filterBy="#{cap.name}" filterEvent="onkeyup">

                  <f:facet name="header">

                      <h:outputText value="State Capital"/>

                  </f:facet>

                  <h:outputText value="#{cap.name}"/>

              </rich:column>

      </rich:dataTable>

      ...

  This is the result:

  Figure 6.19. Built-in filtering feature usage

- Using external filtering. In this case you need to write your custom filtering function or expression and define controls.

  The "filterExpression" attribute is used to define expression evaluated to boolean value. This expression checks if the object satisfies filtering condition.

  The "filterMethod" attribute is defined with method binding. This method accepts on Object parameter and returns boolean value. Thus, this method also could be used to check if the object satisfies filtering condition or not. The usage of this attribute is the best way for implementing your own complex business logic.

  See a simple example of "filterExpression" and "filterMethod" attributes usage on the RichFaces LiveDemo page.

#### 6.6.1.5. Reference Data

Table of <rich:column> attributes.

Table 6.30. Component Identification Parameters

Name | Value
--- | ---
component-type | org.richfaces.Column
component-class | org.richfaces.component.html.HtmlColumn
component-family | org.richfaces.Column
renderer-type | org.richfaces.renderkit.CellRenderer
tag-class | org.richfaces.taglib.ColumnTag

Table 6.31. Facets

Facet name | Description
--- | ---
header | Defines the header content
footer | Defines the footer content

Custom style classes as well as skin parameters for <rich:column> are the same as for the <rich:dataTable> component.

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

#### 6.6.1.6. Relevant Resources Links

Visit the Column page at RichFaces LiveDemo for examples of the component usage and their sources.

See the example on how to use the "rendered" attribute of <rich:column> in the RichFaces Cookbook article.

- Prev6.6. Data Iteration
- Top of page
- Front page
- Next6.6.2. < rich:columnGroup > ...