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
The <rich:columns> is a component, that allows you to create a dynamic set of columns from your model.
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"
Table 6.61. rich : columns attributes
| Attribute Name |
Description
|
|---|---|
| begin | Contains the first iteration item |
| breakBefore | if "true" next column begins from the first row |
| colspan | Corresponds to the HTML colspan attribute |
| columns | Number of columns to be rendered |
| comparator | Defines value binding to the comparator that is used to compare the values |
| dir | HTML: Direction indication for text that does not inherit directionality. Valid values are "LTR" (left-to-right) and "RTL" (right-to-left) |
| end | Contains the last iteration item |
| filterBy | Defines iterable object property which is used when filtering performed. |
| filterEvent | Event for filter input that forces the filtration (default value is "onchange") |
| filterExpression | Attribute defines a bean property which is used for filtering of a column |
| filterMethod | This attribute is defined with method binding. This method accepts on Object parameter and return boolean value |
| filterValue | Defines current filtering value |
| footerClass | Assigns one or more space-separated CSS class names to any footer generated for this component |
| headerClass | Assigns one or more space-separated CSS class names to any header generated for this component |
| id | JSF: Every component may have a unique id that is automatically created if omitted |
| index | The current counter |
| label | Column label for drag indicator. Usable only for extendedDataTable component |
| lang | HTML: Code describing the language used in the generated markup for this component |
| rendered | JSF: Attribute defines if component should be rendered. Default value is "true". |
| rowspan | Corresponds to the HTML rowspan attribute |
| selfSorted | Manages 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. Default value is "true" |
| sortable | Boolean attribute. If "true" it's possible to sort the column content after click on the header. Default value is "true" |
| sortBy | Defines a bean property which is used for sorting of a column. This attribute used with <rich:dataTable> |
| sortExpression | Defines a bean property which is used for sorting of a column and used only with <rich:scrollableDataTable>. |
| sortIcon | Defines sort icon. The value for the attribute is context related. |
| sortIconAscending | Defines sort icon for ascending order. The value for the attribute is context related. |
| sortIconDescending | Defines sort icon for descending order. The value for the attribute is context related. |
| sortOrder | SortOrder is an enumeration of the possible sort orderings. Default value is "UNSORTED" |
| style | HTML: CSS style rules to be applied to the component |
| styleClass | JSF: Assigns one or more CSS class names to the component. Corresponds to the HTML "class" attribute. |
| title | HTML: Advisory title information about markup elements generated for this component |
| value | JSF: The current value for this component |
| var | The current variable |
| visible | The attribute is used to define whether the component is visible or not. The default value is "true". |
| width | HTML: Attribute defines width of column. |
Table 6.62. Component identification parameters
| Name | Value |
|---|---|
| component-type | org.richfaces.Column |
| tag-class | org.richfaces.taglib.ColumnsTagHandler |
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>
...
Example:
import org.richfaces.component.html.HtmlColumn;
...
HtmlColumn myColumns = new HtmlColumn();
...
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 "rowspan" 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" rowspan="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:
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>
...
Now, you can use a few <rich:columns> together with <rich:column> within the one table:
...
<rich:dataTable value="#{dataTableScrollerBean.model}" var="model" width="500px" rows="5">
<f:facet name="header">
<h:outputText value="Cars Available"></h:outputText>
</f:facet>
<rich:columns value="#{dataTableScrollerBean.columns}" var="columns" index="ind">
<f:facet name="header">
<h:outputText value="#{columns.header}" />
</f:facet>
<h:outputText value="#{model[ind].model} " />
</rich:columns>
<rich:column>
<f:facet name="header">
<h:outputText value="Price" />
</f:facet>
<h:outputText value="Price" />
</rich:column>
<rich:columns value="#{dataTableScrollerBean.columns}" var="columns" index="ind">
<f:facet name="header">
<h:outputText value="#{columns.header}" />
</f:facet>
<h:outputText value="#{model[ind].mileage}$" />
</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 =
"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>
...
The <rich:columns> tag is initialized during components tree building process. This process precedes page rendering at "Render Response" JSF phase. To be rendered properly the component needs all it variables to be initialized while the components tree is being building. A javax.servlet.jsp.JspTagException occurs if <rich:columns> uses variables passed from other components, if these variables are initialized during rendering. Thus, when <rich:columns> is asking for such variables they do not already exist. Use <c:forEach> JSP standard tag as workaround. Compare two examples below.
This code calls the exception:
...
<rich:dataTable value="#{bean.data}" var="var">
<rich:columns value="#{var.columns}">
...
</rich:columns>
</rich:dataTable>
...
This code works properly:
...
<c:forEach items="#{bean.data}" var="var">
<rich:columns value="#{var.columns}">
...
</rich:columns>
</c:forEach>
...
Since 3.3.0GA <rich:columns> requires explicit definition of "id" for children components to ensure that decode process works properly. The example of how you can define unique "id" for children component:
...
<rich:columns value="#{bean.columns}" var="col" index="ind" ... >
<h:inputText id="input#{ind}" value="">
<a4j:support id="support#{ind}" event="onchange" reRender="someId" />
</h:inputText>
</rich:columns>
...
Only if "id" defined as shown above Ajax after onchange event will be processed as expected.
Sorting and filtering for the <rich:columns> component works the same as for <rich:column> . See the "Sorting and Filtering" section.
Table 6.63. Facets
| Facet name | Description |
|---|---|
| header | Defines the header content |
| footer | Defines the footer content |
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
Skin parameters redefinition for <rich:columns> are the same as for the <rich:dataTable> component .
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 (possible classes could be found in the tables above ) and define necessary properties in them.
Example:
...
.rich-table-subheadercell{
color: #a0a0a0;
}
...
This is a result:
In the example column header cells color was changed.
Also it's possible to change styles of particular <rich:columns> component. In this case you should create own style classes and use them in corresponding <rich:columns> styleClass attributes. An example is placed below:
Example:
...
.myClass {
font-style: oblique;
}
...
The "styleClass" attribute for <rich:columns> is defined as it's shown in the example below:
Example:
<rich:columns styleClass="myClass">
This is a result:
As it could be seen on the picture above, the font style for columns was changed.
On the component LiveDemo page you can found some additional information for <rich:columns> component usage.
