Pagination in Confluence plugin

2nd part in Confluence plugin development series..
Confluence provides items pagination out of the box but I couldn't find any reference in developer documentation. Standard page navigation bar looks like this:

Here are the easy steps to implement it for your own list of items:

1. extend your action class from AbstractEntityPaginationAction

public class ViewUsers 
  extends AbstractEntityPaginationAction {
}

AbstractEntityPaginationAction provides
protected bucket.core.actions.PaginationSupport paginationSupport;
which you can use in your action:

public String execute() throws Exception {
 List users = ... // load users here
 paginationSupport.setItems(users);
 paginationSupport.setPageSize(preferredPageSize);
 return SUCCESS;
}

2. insert pagination macro in viewusers.vm page

#pagination($action.paginationSupport "page.action?")

where page.action is the action name which will be called when you select a page. Pagination macro then adds a parameter startIndex, that's why you need a question mark (?) at the end


3. implement page.action

public String page() throws Exception {
 HttpServletRequest req = 
   ServletActionContext.getRequest();
 int startIndex = 
   Integer.parseInt(req.getParameter("startIndex"));
 List users = ... // load users
 paginationSupport.setItems(users);
 paginationSupport.setPageSize(preferredPageSize);
 paginationSupport.setStartIndex(startIndex);
 return SUCCESS;
}

4. view current items in page

#foreach( $user in 
  $action.paginationSupport.page.iterator())
 ...
#end

PaginationSupport allows to control page size (number of items per page) so you may provide a selector in web page for page size and save it in user session.
That's it!