A collection of data in a list layout is presented by dataList
with several display types and features, such as AJAX pagination.
A basic definition of a data list with a header
facet for listing the names of countries starting with the letter "A" would be as follows:
<p:dataList id="simple" value="#{dataListBean.countriesShort}" var="country" itemType="disc"> <f:facet name="header"> Countries starting with 'A' </f:facet> <h:outputText value="#{country}" /> </p:dataList>
By default, the dataList
component renders an unordered list, which corresponds to the <ul>
HTML tag. The visual output is given here:
The bullet type can be customized with the itemType
attribute, which has the default value disc
. For an unordered list, the other possible values are circle
and square
.
When type
is set to ordered
, dataList
renders an ordered list, which corresponds to the <ol>
HTML tag. The visual output is given here:
With ordered lists, the default value for the itemType
is set to 1
to render a numerically ordered list. The other possible values to render alphabetically ordered characters as bullets in lowercase and uppercase are a
and A
, respectively. The last alternatives for rendering roman numbers as bullets in lowercase and uppercase are i
or I
.
The third type of the dataList
component is definition
, where an inline description can be visualized for each item. The next definition displays a list of car names along with their small images. The detailed definition should be provided with the facet named description
. The definition of definition
is provided here:
<p:dataList id="withDescription" value="#{dataListBean.cars}" var="car" type="definition"> Name: #{car.name} <f:facet name="description"> <p:graphicImage value="/resources/images/autocomplete/#{car.name}.png" width="60" height="40" /> </f:facet> </p:dataList>
The dataList
component has a built-in AJAX pagination that is enabled by setting the paginator
attribute to true
. To support the pagination, the number of rows to display per page should be set with the rows
attribute. Its default value is 0
, which indicates that all the data available will be displayed. Pagination can be customized using the paginatorTemplateOption
attribute, which accepts keys to specify the content of the paginator
:
FirstPageLink
LastPageLink
PreviousPageLink
NextPageLink
PageLinks
CurrentPageReport
RowsPerPageDropdown
The default rendering for the pagination would be as shown here:
It would be the same as the pagination template, as shown in the following code snippet:
{FirstPageLink} {PreviousPageLink} {PageLinks} {NextPageLink} {LastPageLink}
A more complex paginator
definition is given here:
{CurrentPageReport} {FirstPageLink} {PreviousPageLink} {PageLinks} {NextPageLink} {LastPageLink} {RowsPerPageDropdown}
This will be rendered as shown here:
The {RowsPerPageDropdown}
attribute has its own mechanism to produce templates, and the mechanism should be provided in order to render the dropdown (for example, rowsPerPageTemplate="5,10,15"
).
Also,{CurrentPageReport}
has its own template defined with the currentPageReportTemplate
option.
We can use the {currentPage}
, {totalPages}
, {totalRecords}
, {startRecord}
, and{endRecord}
keywords within currentPageReportTemplate
. The default value is {currentPage} of {totalPages}
.
The pageLinks
attribute defines the maximum number of page links to display. Its default value is 10
. For the complex paginator
definition given previously, it's set to 3
.The paginator
attribute can be positioned in three different locations by setting the paginatorPosition
attribute to top
, bottom
, or both
(the last value being the default value). The paginatorAlwaysVisible
attribute defines whether the pagination should be hidden or not when the total data count is less than the number of rows per page.
The content of paginator
can also be customized with a custom facet definition, as shown here:
<p:dataList value="#{dataListBean.countries}" var="country"
rows="10" paginator="true"
paginatorTemplate="{CurrentPageReport} {CustomContent}">
<f:facet name="{CustomContent}
">
..custom content..
</f:facet>
<f:facet name="header">
Countries
</f:facet>
<h:outputText value="#{country}" />
</p:dataList>
As seen in the example, the name of the facets should match with the name of the token given in the template.
This recipe is available in the demo web application on GitHub (https://github.com/ova2/primefaces-cookbook/tree/second-edition). Clone the project if you have not done it yet, explore the project structure, and build and deploy the WAR file on application servers compatible with Servlet 3.x, such as JBoss WildFly and Apache TomEE.
The showcase for the recipe is available at http://localhost:8080/pf-cookbook/views/chapter5/dataList.jsf
.