org.apache.velocity.tools.view.tools
Class AbstractPagerTool

java.lang.Object
  extended by org.apache.velocity.tools.view.tools.AbstractPagerTool
Direct Known Subclasses:
AbstractSearchTool

public abstract class AbstractPagerTool
extends java.lang.Object

Abstract view tool for doing request-based pagination of items in an a list.

Usage:
To use this class, you must extend it and implement the setup(HttpServletRequest) method.

The setup(HttpServletRequest) method ought to extract from the current request the current list index and, optionally, the number of items to display per page. Upon extracting these parameters, they should be set using the provided setIndex(int) and setItemsPerPage(int) methods. A simple implementation would be:

 public void setup(HttpServletRequest req)
 {
     ParameterParser pp = new ParameterParser(req);
     setIndex(pp.getInt("index", 0));
     setItemsPerPage(pp.getInt("show", DEFAULT_ITEMS_PER_PAGE));
 }
 
You can also set the list of items to be paged at this point using the setItems(List) method, or you can always set the item list at another point (even from within the template).

Here's an example of how your subclass would be used in a template:

   #if( $pager.hasItems() )
   Showing $!pager.pageDescription<br>
     #set( $i = $pager.index )
     #foreach( $item in $pager.page )
       ${i}. $!item <br>
       #set( $i = $i + 1 )
     #end
     <br>
     #if ( $pager.pagesAvailable > 1 )
       #set( $pagelink = $link.self.param("show",$!pager.itemsPerPage) )
       #if( $pager.prevIndex )
           <a href="$pagelink.param('index',$!pager.prevIndex)">Prev</a>
       #end
       #foreach( $index in $pager.slip )
         #if( $index == $pager.index )
           <b>$pager.pageNumber</b>
         #else
           <a href="$pagelink.param('index',$!index)">$!pager.getPageNumber($index)</a>
         #end
       #end
       #if( $pager.nextIndex )
           <a href="$pagelink.param('index',$!pager.nextIndex)">Next</a>
       #end
     #end
   #else
   No items in list.
   #end
 
The output of this might look like:

Showing 1-5 of 8
1. foo
2. bar
3. blah
4. woogie
5. baz

1 2 Next

Example toolbox.xml configuration:

<tool>
   <key>pager</key>
   <scope>request</scope>
   <class>com.foo.tools.MyPagerTool</class>
 </tool>
 

Since:
VelocityTools 1.2
Version:
$Revision: 483616 $ $Date: 2006-12-07 11:19:53 -0800 (Thu, 07 Dec 2006) $
Author:
Nathan Bubna

Field Summary
static int DEFAULT_ITEMS_PER_PAGE
          the default number of items shown per page
static int DEFAULT_SLIP_SIZE
          the default max number of page indices to list
private  int index
           
private  java.util.List items
           
private  int itemsPerPage
           
protected  javax.servlet.http.HttpSession session
           
private  int slipSize
           
protected static java.lang.String STORED_ITEMS_KEY
          the key under which items are stored in session
 
Constructor Summary
AbstractPagerTool()
           
 
Method Summary
 java.lang.Integer getFirstIndex()
          Returns the index of the first item on the current page of results (as determined by the current index, items per page, and the number of items).
 int getIndex()
          Returns the current search result index.
 java.util.List getItems()
          Returns the item list.
 int getItemsPerPage()
          Returns the set number of items to be displayed per page of items
 java.lang.Integer getLastIndex()
          Returns the index of the last item on the current page of results (as determined by the current index, items per page, and the number of items).
 java.lang.Integer getNextIndex()
          Returns the index for the next page of items (as determined by the current index, items per page, and the number of items).
 java.util.List getPage()
          Returns the current "page" of search items.
 java.lang.String getPageDescription()
          Returns a description of the current page.
 java.lang.Integer getPageNumber()
          Returns the "page number" for the current index.
 java.lang.Integer getPageNumber(int i)
          Returns the "page number" for the specified index.
 int getPagesAvailable()
          Returns the number of pages that can be made from this list given the set number of items per page.
 java.lang.Integer getPrevIndex()
          Return the index for the previous page of items (as determined by the current index, items per page, and the number of items).
 java.util.List getSlip()
          Returns a Sliding List of Indices for Pages of items.
 int getSlipSize()
          Returns the number of result page indices getSlip() will return per request (if available).
protected  java.util.List getStoredItems()
          Retrieves stored search items (if any) from the user's session attributes.
 int getTotal()
          Returns the total number of items available.
 boolean hasItems()
          Checks whether or not the result list is empty.
 void init(java.lang.Object obj)
          Initializes this instance by grabbing the request and session objects from the current ViewContext.
 void reset()
          Sets the item list to null, page index to zero, and items per page to the default.
 void setIndex(int index)
          Sets the index of the first result in the current page
 void setItems(java.util.List items)
          Sets the List to page through.
 void setItemsPerPage(int itemsPerPage)
          Sets the number of items returned in a page of items
 void setSlipSize(int slipSize)
          Sets the number of result page indices for getSlip() to list.
protected  void setStoredItems(java.util.List items)
          Stores current search items in the user's session attributes (if one currently exists) in order to do efficient result pagination.
abstract  void setup(javax.servlet.http.HttpServletRequest request)
          Abstract method to make it as obvious as possible just where implementing classes should be retrieving and configuring display parameters.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_ITEMS_PER_PAGE

public static final int DEFAULT_ITEMS_PER_PAGE
the default number of items shown per page

See Also:
Constant Field Values

DEFAULT_SLIP_SIZE

public static final int DEFAULT_SLIP_SIZE
the default max number of page indices to list

See Also:
Constant Field Values

STORED_ITEMS_KEY

protected static final java.lang.String STORED_ITEMS_KEY
the key under which items are stored in session


items

private java.util.List items

index

private int index

slipSize

private int slipSize

itemsPerPage

private int itemsPerPage

session

protected javax.servlet.http.HttpSession session
Constructor Detail

AbstractPagerTool

public AbstractPagerTool()
Method Detail

init

public void init(java.lang.Object obj)
Initializes this instance by grabbing the request and session objects from the current ViewContext.

Parameters:
obj - the current ViewContext
Throws:
java.lang.ClassCastException - if the param is not a ViewContext

setup

public abstract void setup(javax.servlet.http.HttpServletRequest request)
Abstract method to make it as obvious as possible just where implementing classes should be retrieving and configuring display parameters.

A simple implementation would be:

 public void setup(HttpServletRequest req)
 {
     ParameterParser pp = new ParameterParser(req);
     setIndex(pp.getInt("index", 0));
     setItemsPerPage(pp.getInt("show", DEFAULT_ITEMS_PER_PAGE));
 }
 

Parameters:
request - the current HttpServletRequest

reset

public void reset()
Sets the item list to null, page index to zero, and items per page to the default.


setItems

public void setItems(java.util.List items)
Sets the List to page through.

Parameters:
items - - the List of items to be paged through

setIndex

public void setIndex(int index)
Sets the index of the first result in the current page

Parameters:
index - the result index to start the current page with

setItemsPerPage

public void setItemsPerPage(int itemsPerPage)
Sets the number of items returned in a page of items

Parameters:
itemsPerPage - the number of items to be returned per page

setSlipSize

public void setSlipSize(int slipSize)
Sets the number of result page indices for getSlip() to list. (for google-ish result page links).

Parameters:
slipSize - - the number of result page indices to list
See Also:
getSlip()

getItemsPerPage

public int getItemsPerPage()
Returns the set number of items to be displayed per page of items

Returns:
current number of items shown per page

getSlipSize

public int getSlipSize()
Returns the number of result page indices getSlip() will return per request (if available).

Returns:
the number of result page indices getSlip() will try to return

getIndex

public int getIndex()
Returns the current search result index.

Returns:
the index for the beginning of the current page

hasItems

public boolean hasItems()
Checks whether or not the result list is empty.

Returns:
true if the result list is not empty.

getItems

public java.util.List getItems()
Returns the item list. This is guaranteed to never return null.

Returns:
List of all the items

getLastIndex

public java.lang.Integer getLastIndex()
Returns the index of the last item on the current page of results (as determined by the current index, items per page, and the number of items). If there is no current page, then null is returned.

Returns:
index for the last item on this page or null if none exists
Since:
VelocityTools 1.3

getNextIndex

public java.lang.Integer getNextIndex()
Returns the index for the next page of items (as determined by the current index, items per page, and the number of items). If no "next page" exists, then null is returned.

Returns:
index for the next page or null if none exists

getFirstIndex

public java.lang.Integer getFirstIndex()
Returns the index of the first item on the current page of results (as determined by the current index, items per page, and the number of items). If there is no current page, then null is returned. This is different than getIndex() in that it is adjusted to fit the reality of the items available and is not a mere accessor for the current, user-set index value.

Returns:
index for the first item on this page or null if none exists
Since:
VelocityTools 1.3

getPrevIndex

public java.lang.Integer getPrevIndex()
Return the index for the previous page of items (as determined by the current index, items per page, and the number of items). If no "next page" exists, then null is returned.

Returns:
index for the previous page or null if none exists

getPagesAvailable

public int getPagesAvailable()
Returns the number of pages that can be made from this list given the set number of items per page.


getPage

public java.util.List getPage()
Returns the current "page" of search items.

Returns:
a List of items for the "current page"

getPageNumber

public java.lang.Integer getPageNumber(int i)
Returns the "page number" for the specified index. Because the page number is used for the user interface, the page numbers are 1-based.

Parameters:
i - the index that you want the page number for
Returns:
the approximate "page number" for the specified index or null if there are no items

getPageNumber

public java.lang.Integer getPageNumber()
Returns the "page number" for the current index. Because the page number is used for the user interface, the page numbers are 1-based.

Returns:
the approximate "page number" for the current index or null if there are no items

getTotal

public int getTotal()
Returns the total number of items available.

Since:
VelocityTools 1.3

getPageDescription

public java.lang.String getPageDescription()

Returns a description of the current page. This implementation displays a 1-based range of result indices and the total number of items. (e.g. "1 - 10 of 42" or "7 of 7") If there are no items, this will return "0 of 0".

Sub-classes may override this to provide a customized description (such as one in another language).

Returns:
a description of the current page

getSlip

public java.util.List getSlip()
Returns a Sliding List of Indices for Pages of items.

Essentially, this returns a list of item indices that correspond to available pages of items (as based on the set items-per-page). This makes it relativly easy to do a google-ish set of links to available pages.

Note that this list of Integers is 0-based to correspond with the underlying result indices and not the displayed page numbers (see getPageNumber(int)).

Returns:
List of Integers representing the indices of result pages or empty list if there's one or less pages available

getStoredItems

protected java.util.List getStoredItems()
Retrieves stored search items (if any) from the user's session attributes.

Returns:
the List retrieved from memory

setStoredItems

protected void setStoredItems(java.util.List items)
Stores current search items in the user's session attributes (if one currently exists) in order to do efficient result pagination.

Override this to store search items somewhere besides the HttpSession or to prevent storage of items across requests. In the former situation, you must also override getStoredItems().

Parameters:
items - the List to be stored


Copyright (c) 2003-2007 Apache Software Foundation