Class PagerTool
- Direct Known Subclasses:
AbstractPagerTool
,AbstractSearchTool
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. #endThe 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 tools.xml configuration:
<tools> <toolbox scope="request"> <tool class="org.apache.velocity.tools.view.PagerTool"/> </toolbox> </tools>
- Since:
- VelocityTools 2.0
- Version:
- $Revision: 595822 $ $Date: 2007-11-16 13:07:51 -0800 (Fri, 16 Nov 2007) $
- Author:
- Nathan Bubna
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate boolean
static final String
static final int
the default number of items shown per pagestatic final String
static final String
static final int
the default max number of page indices to liststatic final String
private int
private String
private List
private int
private String
private String
protected HttpSession
private int
private String
protected static final String
the key under which items are stored in session -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionboolean
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.getItems()
Returns the item list.int
Returns the set number of items to be displayed per page of itemsReturns 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).Returns the index for the next page of items (as determined by the current index, items per page, and the number of items).getPage()
Returns the current "page" of search items.Returns a description of the current page.Returns the "page number" for the current index.getPageNumber
(int i) Returns the "page number" for the specified index.int
Returns the number of pages that can be made from this list given the set number of items per page.Return the index for the previous page of items (as determined by the current index, items per page, and the number of items).getSlip()
Returns a Sliding List of Indices for Pages of items.int
Returns the number of result page indicesgetSlip()
will return per request (if available).protected List
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 pagevoid
setIndexKey
(String key) void
Sets the List to page through.void
setItemsPerPage
(int itemsPerPage) Sets the number of items returned in a page of itemsvoid
setItemsPerPageKey
(String key) void
setNewItemsKey
(String key) void
setRequest
(HttpServletRequest request) Initializes this tool with the specifiedHttpServletRequest
.void
setSlipSize
(int slipSize) Sets the number of result page indices forgetSlip()
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
(HttpServletRequest request) Sets the index, itemsPerPage, and/or slipSize *if* they are set in the request parameters.
-
Field Details
-
DEFAULT_NEW_ITEMS_KEY
- See Also:
-
DEFAULT_INDEX_KEY
- See Also:
-
DEFAULT_ITEMS_PER_PAGE_KEY
- See Also:
-
DEFAULT_SLIP_SIZE_KEY
- See Also:
-
DEFAULT_ITEMS_PER_PAGE
public static final int DEFAULT_ITEMS_PER_PAGEthe default number of items shown per page- See Also:
-
DEFAULT_SLIP_SIZE
public static final int DEFAULT_SLIP_SIZEthe default max number of page indices to list- See Also:
-
STORED_ITEMS_KEY
the key under which items are stored in session -
newItemsKey
-
indexKey
-
itemsPerPageKey
-
slipSizeKey
-
createSession
private boolean createSession -
items
-
index
private int index -
slipSize
private int slipSize -
itemsPerPage
private int itemsPerPage -
session
protected HttpSession session
-
-
Constructor Details
-
PagerTool
public PagerTool()
-
-
Method Details
-
setRequest
public void setRequest(HttpServletRequest request) Initializes this tool with the specifiedHttpServletRequest
. This is required for this tool to operate and will throw a NullPointerException if this is not set or is set tonull
. -
setup
public void setup(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 thegetNewItemsKey()
.- Parameters:
request
- the current HttpServletRequest
-
setNewItemsKey
-
getNewItemsKey
-
setIndexKey
-
getIndexKey
-
setItemsPerPageKey
-
getItemsPerPageKey
-
setSlipSizeKey
-
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
Sets the List to page through.- Parameters:
items
- - theList
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 forgetSlip()
to list. (for google-ish result page links).- Parameters:
slipSize
- - the number of result page indices to list- See Also:
-
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 indicesgetSlip()
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
Returns the item list. This is guaranteed to never returnnull
.- Returns:
List
of all the items
-
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
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
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 thangetIndex()
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
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
Returns the current "page" of search items.- Returns:
- a
List
of items for the "current page"
-
getPageNumber
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
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
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
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
Retrieves stored search items (if any) from the user's session attributes.- Returns:
- the
List
retrieved from memory
-
setStoredItems
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
- theList
to be stored
-