paginate

paginate (http://github.com/lmcalpin/Play--Paginate) is a replacement for the standard #{list/} Play! tag.

Getting Started

To include paginate in an existing project add the following lines to your conf/application.conf file

module.paginate=${play.path}/modules/paginate-head

Using paginate

You can use paginate by creating an instance of a Paginator object. Two are provided for you, though you can always create your own:

play.modules.paginate.ModelPaginator is used to paginate standard Play! JPA-based models.

public static void index() {
      ModelPaginator paginator = new ModelPaginator(TheModel.class);
      render(paginator);
    }

You can also provide a JPA-QL WHERE clause and/or an ORDER clause to sort and filter the results.

ModelPaginator entities = new ModelPaginator(Foo.class, "foo=?", "bar").orderBy("ID DESC"));
    render(entities);

**play.modules.paginate.ValuePaginator ** is used to wrap any existing List.

public static void index() {
      List<T> realList = ...;
      ValuePaginator paginator = new ValuePaginator(realList);
      render(paginator);
    }

You can also simply provide a standard Java Collections API List, and behind the scenes, it will be autoboxed into a ValuePaginator.

public static void index() {
      List<T> realList = ...;
      render(realList);
    }

From your view, include the pagination list and controls:

#{paginate.list items:paginator, as:'r'} 
    ... ${r} // or whatever 
    #{/paginate.list} 
    #{paginate.controls items:paginator /} 

If you would like to use the default stylesheet, include this somewhere in your layout:

<link rel="stylesheet" type="text/css" media="screen" href="@{'/public/stylesheets/play-pagination.css'}"> 

If you would like to include a summary “Displaying rows X to Y”, you may include the
summary tag:

#{paginate.summary items:paginator/}

You can use the standard Play! #{else} tag with #{paginate.list}.
The contents within this tag will be rendered if the collection is empty:

#{paginate.list items:emptyCollection, as:'doesntmatter'}
      This content won't be displayed
    #{/paginate.list}
    #{else}
      Empty list!
    #{/else}
  
h2. Customization

By default, a request parameter “page” is used to determine which page is being viewed in a paginated list. If you would rather use an alternate name, you can customize this in your conf/application.conf file.

paginator.parameter.name=__page

In addition, the Paginator classes expose properties that you can use to determine how many items are displayed per page, as well as how the controls will be displayed.

- 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

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.