The Paginate module adds two new tags:
#{paginate.list items:var, as:'ref'/}, which works as a drop-in replacement for #{list/} to show one page at a time
and
#{paginate.controls items:var /} to display the pagination controls
Also, add
<link rel="stylesheet" type="text/css" media="screen" href="@{'/public/stylesheets/play-pagination.css'}">
if you want to use the default stylesheet.
The paginator can be used several ways:
1) You can wrap a raw List. Your controller can simply create a List:
List<Foo> values = ...; render(values);
The view will simply refer to that List:
#{paginate.list items:values, as:'row'/}
Behind the scenes, the control will autobox the raw List into a ValuePaginator helper class.
2) You can manually wrap the List with our ValuePaginator helper class.
List<Foo> values = ...; ValuePaginator entites = new ValuePaginator(values); render(entities);
3) You can wrap the keys. Using our ModelPaginator helper class, we will lazily lookup only the rows for the current page that is being rendered.
List<Long> keys = ... "SELECT id FROM Foo" ... ; ModelPaginator entities = new ModelPaginator(Foo.class, keys); render(entities);
4) You can supply a Play! Model and optionally a filter and let the ModelPaginator helper class figure out the rest.
ModelPaginator entities = new ModelPaginator(Foo.class, "foo=?", "bar"); render(entities);
If you want to do sorting as well, you can use a custom record locator strategy. One meant for JPA records is provided, called JPAIndexedRecordLocator.
ModelPaginator entities = new ModelPaginator(new JPAIndexedRecordLocator(Foo.class, "foo=?", "bar").orderBy("ID DESC"));
render(entities);
You will display a page from a collection by including the following tags:
#{paginate.list items:values, as:'r'}
${r} <!-- displays the value for each row -->
#{/paginate.list}
The tag will insert special variables into the template that you can reference if you want to determine which row number is being displayed, and the parity of the row. The variables append “_index”, “_parity”, “_isFirst”, and “_isLast” to the field name specified in the “as” parameter.
For example, in the tag above, the row variable is called “r”, and the following variables will be available.
${r_index} displays the row number (starting from 1)
${r_isFirst} is true for row #1 and false elsewhere
${r_isLast} is true for the last row in the Collection
${r_parity} returns "even" for even-numbered rows and "odd" for odd-numbered rows
Pagination controls are controlled by the view paginate/Controls.html and can be overridden in your project.
The following properties are available to customize pagination display:
-
get/setBoundaryControlsEnabled: determines whether the First and Last buttons are displayed
-
get/setPagesDisplayed: customizes the number of pages that show up between the forward/backward controls
-
get/setPageSize: determines the number of rows we display per page
By default, paginator uses the “page” request parameter to determine what page you are viewing. If you would like to override that, you can add a “paginator.parameter.name” entry to your application.conf:
paginator.parameter.name=__pagenumber
However, using the default page request parameter will paginate every single pagination control on the page. To avoid that, you need to invoke the setParameterName() method in your controller.
ModelPaginator entities = new ModelPaginator(...);
entities.setParameterName("foo");
render(entities);
The example above will use the request parameter “foo” to capture the current page number for the ModelPaginator associated with the variable named “entities.”
There is currently no way to change the parameter name used for Lists that are autoboxed into ValuePaginators.
An additional summary tag is available if you would like to display the message: “Displaying rows X to Y out of Z records.”
#{paginate.summary items:paginator /}