org.apache.velocity.tools.view

## Class PagerTool

- java.lang.Object
- - org.apache.velocity.tools.generic.SafeConfig
  - - org.apache.velocity.tools.view.PagerTool

Direct Known Subclasses:
  AbstractSearchTool

    @DefaultKey(value="pager")
     @InvalidScope(value={"application","session"})
    public class PagerTool
    extends SafeConfig

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

Usage:
To use this class, you typically push a List of items to it by putting it in the request attributes under the value returned by `getNewItemsKey()` (default is "new.items"). You can also set the list of items to be paged in a subclass using the setItems(List) method, or you can always set the item list at another point (even from within the template). This need only happen once per session if a session is available, but the item list can be (re)set as often as you like.

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<br>
       1. foo<br>
       2. bar<br>
       3. blah<br>
       4. woogie<br>
       5. baz<br><br>
       <b>1</b> <a href="">2</a> <a href="">Next</a>

Example tools.xml configuration:

     <tools>
       <toolbox scope="request">
         <tool class="org.apache.velocity.tools.view.PagerTool"/>
       </toolbox>
     </tools>

Since:
  VelocityTools 2.0
Version:
  $Revision$ $Date$
Author:
  Nathan Bubna

### Field Summary

Fields
`static String` `DEFAULT_INDEX_KEY`
`static int` `DEFAULT_ITEMS_PER_PAGE` the default number of items shown per page
`static String` `DEFAULT_ITEMS_PER_PAGE_KEY`
`static String` `DEFAULT_NEW_ITEMS_KEY`
`static int` `DEFAULT_SLIP_SIZE` the default max number of page indices to list
`static String` `DEFAULT_SLIP_SIZE_KEY`
`protected javax.servlet.http.HttpSession` `session`
`protected static String` `STORED_ITEMS_KEY` the key under which items are stored in session

### Fields inherited from class org.apache.velocity.tools.generic.SafeConfig

`LOCK_CONFIG_KEY, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY`

### Constructor Summary

Constructors
Constructor and Description
`PagerTool()`

### Method Summary

All Methods Instance Methods Concrete Methods
`boolean` `getCreateSession()`
`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.
`String` `getIndexKey()`
`List` `getItems()` Returns the item list.
`int` `getItemsPerPage()` Returns the set number of items to be displayed per page of items
`String` `getItemsPerPageKey()`
`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).
`String` `getNewItemsKey()`
`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).
`List` `getPage()` Returns the current "page" of search items.
`String` `getPageDescription()` Returns a description of the current page.
`Integer` `getPageNumber()` Returns the "page number" for the current index.
`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.
`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).
`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).
`String` `getSlipSizeKey()`
`protected 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` `reset()` Sets the item list to null, page index to zero, and items per page to the default.
`void` `setCreateSession(boolean createSession)`
`void` `setIndex(int index)` Sets the index of the first result in the current page
`void` `setIndexKey(String key)`
`void` `setItems(List items)` Sets the List to page through.
`void` `setItemsPerPage(int itemsPerPage)` Sets the number of items returned in a page of items
`void` `setItemsPerPageKey(String key)`
`void` `setNewItemsKey(String key)`
`void` `setRequest(javax.servlet.http.HttpServletRequest request)` Initializes this tool with the specified `HttpServletRequest`.
`void` `setSlipSize(int slipSize)` Sets the number of result page indices for `getSlip()` to list.
`void` `setSlipSizeKey(String key)`
`protected void` `setStoredItems(List items)` Stores current search items in the user's session attributes (if one currently exists) in order to do efficient result pagination.
`void` `setup(javax.servlet.http.HttpServletRequest request)` Sets the index, itemsPerPage, and/or slipSize *if* they are set in the request parameters.

### Methods inherited from class org.apache.velocity.tools.generic.SafeConfig

`configure, configure, getLog, initLogger, isConfigLocked, isSafeMode, setLockConfig, setSafeMode`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### DEFAULT_NEW_ITEMS_KEY

    public static final String DEFAULT_NEW_ITEMS_KEY

See Also:
  Constant Field Values

#### DEFAULT_INDEX_KEY

    public static final String DEFAULT_INDEX_KEY

See Also:
  Constant Field Values

#### DEFAULT_ITEMS_PER_PAGE_KEY

    public static final String DEFAULT_ITEMS_PER_PAGE_KEY

See Also:
  Constant Field Values

#### DEFAULT_SLIP_SIZE_KEY

    public static final String DEFAULT_SLIP_SIZE_KEY

See Also:
  Constant Field Values

#### 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 String STORED_ITEMS_KEY

the key under which items are stored in session

#### session

    protected javax.servlet.http.HttpSession session

### Constructor Detail

#### PagerTool

    public PagerTool()

### Method Detail

#### setRequest

    public void setRequest(javax.servlet.http.HttpServletRequest request)

Initializes this tool with the specified `HttpServletRequest`. This is required for this tool to operate and will throw a NullPointerException if this is not set or is set to `null`.

Parameters:
  `request` - servlet request

#### setup

    public void setup(javax.servlet.http.HttpServletRequest request)

Sets the index, itemsPerPage, and/or slipSize *if* they are set in the request parameters. Likewise, this will set the item list to be paged *if* there is a list pushed into the request attributes under the `getNewItemsKey()`.

Parameters:
  `request` - the current HttpServletRequest

#### setNewItemsKey

    public void setNewItemsKey(String key)

#### getNewItemsKey

    public String getNewItemsKey()

#### setIndexKey

    public void setIndexKey(String key)

#### getIndexKey

    public String getIndexKey()

#### setItemsPerPageKey

    public void setItemsPerPageKey(String key)

#### getItemsPerPageKey

    public String getItemsPerPageKey()

#### setSlipSizeKey

    public void setSlipSizeKey(String key)

#### getSlipSizeKey

    public String getSlipSizeKey()

#### setCreateSession

    public void setCreateSession(boolean createSession)

#### getCreateSession

    public boolean getCreateSession()

#### 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(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 List getItems()

Returns the item list. This is guaranteed to never return `null`.

Returns:
  `List` of all the items

#### getLastIndex

    public 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 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 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 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.

Returns:
  number of available pages

#### getPage

    public List getPage()

Returns the current "page" of search items.

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

#### getPageNumber

    public 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 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.

Returns:
  number of items
Since:
  VelocityTools 1.3

#### getPageDescription

    public 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 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 List getStoredItems()

Retrieves stored search items (if any) from the user's session attributes.

Returns:
  the `List` retrieved from memory

#### setStoredItems

    protected void setStoredItems(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