6.32.  < rich:column >

6.32.1. Description

The component for row rendering for a UIData component.

<rich:column> component

Figure 6.38.  <rich:column> component


6.32.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"
  • Possibility to sort and to filter of columns

Table 6.120. rich : column attributes

Attribute NameDescription
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
comparator 
dirDirection indication for text that does not inherit directionality. Valid values are "LTR" (left-to-right) and "RTL" (right-to-left)
filterBy 
filterDefaultLabel 
filterEventEvent for filter input that forces the filtration (default = onchange)
filterExpressionAttribute defines a bean property which is used for filtering of a column
filterMethod 
filterValue 
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
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
selfSorted 
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
sortModesortMode
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
widthAttribute defines width of column.

Table 6.121. Component identification parameters

NameValue
component-typeorg.richfaces.Column
component-classorg.richfaces.component.html.HtmlColumn
component-familyorg.richfaces.Column
renderer-typeorg.richfaces.ColumnRenderer
tag-classorg.richfaces.taglib.ColumnTag

6.32.3. Creating the Component with a Page Tag

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

Example:


...
    <rich:dataTable var="set">
        <rich:column>
            <h:outputText value="#{set.property1}"/>
        </rich:column>
        <!--Set of another columns and header/footer facets-->
    </rich:dataTable>
...

6.32.4. Creating the Component Dynamically Using Java

Example:


import org.richfaces.component.html.HtmlColumn;
...
HtmlColumn myColumn = new HtmlColumn();
...

6.32.5. Details of Usage

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:

Generated <rich:column> component

Figure 6.39. 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 the "breakBefore" attribute = 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:

<rich:column> modified with colspan and breakbefore attributes

Figure 6.40.  <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 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:

<rich:column> generated with rowspan attribute

Figure 6.41.  <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.

6.32.6. Sorting and Filtering

6.32.6.1. Sorting

In order to sort the columns you should use "sortBy" attribute which defines a bean property which is used for sorting of a column.

By default, the first column sorted in ascending. Below you can see code 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"></h:outputText>
            </f:facet>
            <h:outputText value="#{cap.state}"></h:outputText>
        </rich:column> 
        <rich:column sortBy="#{cap.name}">
            <f:facet name="header">
                <h:outputText value="State Capital"></h:outputText>
            </f:facet>
            <h:outputText value="#{cap.name}"/> 
        </rich:column>
    </rich:dataTable>
</h:form>
...

This is result:

Example sorting first column in ascending

Figure 6.42. Example sorting first column in ascending


In order to sort the data in descending order, you should double-click on the header of column, which you want to sort.

"sortOrder" attribute may be possible in three states:

  • "none"
  • "ascending"
  • "descending" .

By default, data in the columns is not sorted.

Example:


...
<rich:dataTable value="#{dataTableScrollerBean.allCars}" var="category" rows="5" id="table">
        <rich:column id="make" sortBy="#{category.make}" sortOrder="#{sortingBean.makeDirection}">
            <f:facet name="header">
                <h:outputText styleClass="headerText" value="Make" />
            </f:facet>
            <h:outputText value="#{category.make}" />
        </rich:column>
        <rich:column id="model" sortBy="#{category.model}" sortOrder="#{sortingBean.modelDirection}">
            <f:facet name="header">
                <h:outputText styleClass="headerText" value="Model" />
            </f:facet>
            <h:outputText value="#{category.model}" />
        </rich:column>
        <rich:column id="price" sortBy="#{category.price}" sortOrder="#{sortingBean.priceDirection}">
            <f:facet name="header">
                <h:outputText styleClass="headerText" value="Price" />
            </f:facet>
            <h:outputText value="#{category.price}" />
        </rich:column>
        <rich:column id="mileage" sortBy="#{category.mileage}" sortOrder="#{sortingBean.mileageDirection}">
            <f:facet name="header">
                <h:outputText styleClass="headerText" value="Mileage" />
            </f:facet>
            <h:outputText value="#{category.mileage}" />
        </rich:column>
        <rich:column width="200px" id="vin">
            <f:facet name="header">
                <h:outputText styleClass="headerText" value="VIN" />
            </f:facet>
            <h:outputText value="#{category.vin}" />
        </rich:column>
        <rich:column id="stock">
            <f:facet name="header">
                <h:outputText styleClass="headerText" value="Stock" />
            </f:facet>
            <h:outputText value="#{category.stock}" />
        </rich:column>
</rich:dataTable>
...

Below you can see result:

Sorting using the example of the "sortOrder" attribute

Figure 6.43. Sorting using the example of the "sortOrder" attribute


"sortPriority" attribute is defined in the rich:dataTable component which should be defined as set of column ids in the order the columns should be set.

If the columns sort order changed externally – sort priorities should be used to define which columns will be sorted first.

Example:


...
<rich:dataTable value="#{dataTableScrollerBean.allCars}"
                             var="category" rows="30" id="table"
        sortPriority="#{sortingBean.prioritList}">
        <rich:column id="make" sortBy="#{category.make}" sortOrder="#{sortingBean.makeDirection}" selfSorted="false">
            <f:facet name="header">
                <h:outputText styleClass="headerText" value="Make" />
            </f:facet>
            <h:outputText value="#{category.make}" />
        </rich:column>
        <rich:column id="model" sortBy="#{category.model}" sortOrder="#{sortingBean.modelDirection}" selfSorted="false">
            <f:facet name="header">
                <h:outputText styleClass="headerText" value="Model" />
            </f:facet>
            <h:outputText value="#{category.model}" />
        </rich:column>
        <rich:column id="price" sortBy="#{category.price}" sortOrder="#{sortingBean.priceDirection}" selfSorted="false">
            <f:facet name="header">
                <h:outputText styleClass="headerText" value="Price" />
            </f:facet>
            <h:outputText value="#{category.price}" />
        </rich:column>
        <rich:column id="mileage" sortBy="#{category.mileage}" sortOrder="#{sortingBean.mileageDirection}" selfSorted="false">
            <f:facet name="header">
                <h:outputText styleClass="headerText" value="Mileage" />
            </f:facet>
            <h:outputText value="#{category.mileage}" />
        </rich:column>
        <rich:column width="200px" id="vin">
            <f:facet name="header">
                <h:outputText styleClass="headerText" value="VIN" />
            </f:facet>
            <h:outputText value="#{category.vin}" />
        </rich:column>
        <rich:column id="stock">
            <f:facet name="header">
                <h:outputText styleClass="headerText" value="Stock" />
            </f:facet>
            <h:outputText value="#{category.stock}" />
        </rich:column>
        <f:facet name="footer">
            <rich:datascroller />
        </f:facet>
</rich:dataTable>
...

"selfSorted" attribute will manage if it's header will be clickable, icons rendered and sorting will be fired after click on the header. So, developer will be able to define the sortBy property and conditionally use internal sorting.

The default attribute is set to "true" .

Example:


...
<h:form>
    <rich:dataTable value="#{capitalsBean.capitals}" var="cap" width="300px" columnClasses="center">
        <f:facet name="header">
    <h:outputText value="Sorting Example"/>
        </f:facet>
        <rich:column>
    <f:facet name="header">
        <h:outputText value="State Flag"></h:outputText>
    </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"></h:outputText>
    </f:facet>
    <h:outputText value="#{cap.state}"></h:outputText>
        </rich:column> 
        <rich:column sortBy="#{cap.name}">
    <f:facet name="header">
        <h:outputText value="State Capital"></h:outputText>
    </f:facet>
    <h:outputText value="#{cap.name}"/> 
        </rich:column>
    </rich:dataTable>
</h:form>
...

As a result, the second column will be unavailable for sorting.

"sortable" attribute is used with <rich:scrollableDataTable> component.

Below you can find example code of usage and result:

Example:


...
<h:form>
   <rich:spacer height="30" />
    <rich:scrollableDataTable rowKeyVar="rkv" frozenColCount="1" height="400px" width="700px" id="carList" rows="40" columnClasses="col"
                              value="#{dataTableScrollerBean.allCars}" var="category" sortMode="single"
                           binding="#{dataTableScrollerBean.table}"
                           selection="#{dataTableScrollerBean.selection}">
        <rich:column id="make" sortable="true">
    <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:column id="mileage">
    <f:facet name="header">
        <h:outputText styleClass="headerText" value="Mileage" />
               </f:facet>
    <h:outputText value="#{category.mileage}" />
        </rich:column>
        <rich:column width="200px" id="vin">
    <f:facet name="header">
        <h:outputText styleClass="headerText" value="VIN" />
               </f:facet>
    <h:outputText value="#{category.vin}" />
        </rich:column>
        <rich:column id="stock">
            <f:facet name="header">
                <h:outputText styleClass="headerText" value="Stock" />
            </f:facet>
            <h:outputText value="#{category.stock}" />
        </rich:column>
    </rich:scrollableDataTable>
   <rich:spacer height="20px"/>
</h:form>
...

As a result, only the first column can be sorted.

Sorting using the example of the "sortable" attribute

Figure 6.44. Sorting using the example of the "sortable" attribute


"sortExpression" attribute defines a bean property which is used for sorting of a column. Usage of this attribute is not recommendable.

Sorting can't be used together with pagination.

6.32.6.2. Filtering

In order to filter the column value, in accordance with the entered value, it is necessary to use a "filterBy" attribute.

If "filterValue" attribute isn't empty from the beginning – table should be filtered on first rendering.

Below you can see example code and the result of its use:

Example:


...
<h:form>
    <rich:dataTable value="#{capitalsBean.capitals}" var="cap" width="500px">
        <f:facet name="header">
            <h:outputText value="Filtering Example"/>
        </f:facet>
        <rich:column> 
    <f:facet name="header">
        <h:graphicImage value="/images/ico_DataTable.gif"></h:graphicImage>
    </f:facet>
    <h:graphicImage value="#{cap.stateFlag}"/>
        </rich:column>
        <rich:column filterBy="#{cap.state}" filterDefaultLabel="click to filter" filterValue="#{filterName.filterBean}">
    <h:outputText value="#{cap.state}"></h:outputText>
        </rich:column> 
        <rich:column filterBy="#{cap.name}" filterDefaultLabel="click to filter">
    <h:outputText value="#{cap.name}"/> 
        </rich:column>
    </rich:dataTable>
</h:form>
...
Filtering using the example of the "filterBy" attribute

Figure 6.45. Filtering using the example of the "filterBy" attribute


"filterExpression" attribute is used to check if the row should be present in result. Any expression could be used inside and should return boolean value.

Below you can find example code:

Example:


...
<h:form id="form">
    <h:inputText value="#{capitalsBean.filter}">
        <a4j:support event="onblur" reRender="dataTable" />
    </h:inputText>
    <rich:dataTable value="#{capitalsBean.capitals}" var="cap" width="500px">
        <f:facet name="header">
            <h:outputText value="Filtering Example" />
        </f:facet>
        <rich:column>
            <f:facet name="header">
                <h:graphicImage value="/images/ico_DataTable.gif"/>
            </f:facet>
            <h:graphicImage value="#{cap.stateFlag}" />
        </rich:column>
        <rich:column filterBy="#{cap.state}" filterDefaultLabel="click to filter" filterExpression="#{form:startWith(cap.name,cap.state)}">
            <h:outputText value="#{cap.state}"></h:outputText>
        </rich:column>
        <rich:column filterBy="#{cap.name}" filterDefaultLabel="click to filter">
            <h:outputText value="#{cap.name}" />
        </rich:column>
    </rich:dataTable>
</h:form>
...

"filterEvent" attribute is used for customization.

"filterMethod" should be called for every object of the table. It should get current object and return boolean value.

6.32.7. 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:column> components at once:

  • Redefine the corresponding skin parameters

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

6.32.8. Skin Parameters Redefinition

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

6.32.9. Definition of Custom Style Classes

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

In order to redefine styles for all <rich:column> 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:column> components, define your own style classes in the corresponding <rich:column> attributes.

6.32.10. Relevant Resources Links

Here you can see the example of <rich:column> usage and sources for the given example.