hirondelle.web4j.ui.tag
Class Pager

Object
  SimpleTagSupport
      hirondelle.web4j.ui.tag.TagHelper
          hirondelle.web4j.ui.tag.Pager

All Implemented Interfaces:

JspTag, SimpleTag

public final class Pager
extends TagHelper

Generate links for paging through a long list of records.

With this class, paging is implemented in two steps :

• emitting the proper links (with the proper request parameters) to identify each page
• extracting the data from the database, using the given request parameters, and perhaps subsetting the ResultSet

The first step is performed by this tag, but the second step is not (see below). For an example of paging, please see the 'Discussion' feature of the Fish & Chips Club application.

Emitting Links For Paging

This tag works by emitting various links which are modifications of the current URI.

Example

 <w:pager pageFrom="PageIndex"> 
  <a href="placeholder_first_link">First</a> | 
  <a href="placeholder_next_link">Next</a> | 
  <a href="placeholder_previous_link">Previous</a> | 
 </w:pager>
 

The placeholder_xxx items act as placeholders. They are replaced by this tag with modified values of the current URI. The <w:pager> tag has a single pageFrom attribute. It tells this tag which request parameter it will need to modify, in order to generate the various links. This modified request parameter represents the page index, in the range 1..9999 : for example, PageIndex=1, PageIndex=2, and so on.

For example, if the following URI displays "page 5" :

http://www.blah.com/main/SomeAction.do?PageIndex=5&Criteria=Blah

then this tag will let you emit the following links, derived from the above URI simply by replacing the value of the PageIndex request parameter :

http://www.blah.com/main/SomeAction.do?PageIndex=1&Criteria=Blah
http://www.blah.com/main/SomeAction.do?PageIndex=6&Criteria=Blah
http://www.blah.com/main/SomeAction.do?PageIndex=4&Criteria=Blah

Of course, these generated links don't do the actual subsetting of the data. Rather, these links simply alter the current URI to use the desired value for the page index request parameter. The resulting request parameters are then used elsewhere to extract the desired data (as described below).

Link Suppression

If the emission of a link would create a 'link to self', then this tag will not emit the link. For example, if you are already on the first page, then the First and Previous links will not be emitted as links - only the bare text, without the link, is emitted.

Extracting and Subsetting the Data

There are three alternatives to implementing the subsetting of the ResultSet :

• in the JSP itself
• in the Data Access Object (DAO)
• directly in the underlying SELECT statement

Subsetting in the JSP

• this is the simplest style
• it can be applied quickly, to add paging to any existing listing
• the DAO performs a single, unchanging SELECT that always returns the same set of records for all pages
• it requires only a single change to the Action - the addition of a public static final RequestParameter field for the page index parameter
• the JSP performs the subsetting to display a single page at a time, simply using <c:out>

The JSP performs the subsetting with simple JSTL. In the following example, the page size is hard-coded to 25 items per page. The <c:out> tag has begin and end attributes which can control the range of rendered items :

<c:forEach 
  var="item" 
  items="${items}" 
  begin="${25 * (param.PageIndex - 1)}" 
  end="${25 * param.PageIndex - 1}"
>
  ...display each item...
</c:forEach>

Note the different expressions for begin and end :

begin = 25 * (PageIndex - 1)
end = (25 * PageIndex) - 1

which give the following values :

Page	Begin	End
1	0	24
2	25	49
...	...	...

An alternate variation would be to allow the page size to also come from a request parameter :

<c:forEach 
  var="item" 
  items="${items}" 
  begin="${param.PageSize * (param.PageIndex - 1)}" 
  end="${param.PageSize * param.PageIndex - 1}"
>
  ...display each line...
</c:forEach>

Subsetting in the DAO

• the full ResultSet is still returned by the SELECT, as in the JSP case above
• however, this time the DAO performs the subsetting, using Db.listRange(Class, SqlId, Integer, Integer, Object[]). This avoids the cost of unnecessarily parsing records into Model Objects.
• the <c:out> tag does not use any begin and end attributes, since the subsetting has already been done.

Subsetting in the SELECT

• the underlying SELECT is constructed to return only the desired records. (Such a SELECT may be difficult to construct, according to the capabilities of the target database.)
• the SELECT will likely need two request parameters to form the proper query: a page index and a page size, from which start and end indices may be calculated
• the DAO and JSP are implemented as in any regular listing

Here are the kinds of calculations you may need when constructing such a SELECT statement

For items enumerated with a 0-based index :

 start_index = page_size * (page_index - 1)
 end_index = page_size * page_index - 1
 

For items enumerated with a 1-based index :

 start_index = page_size * (page_index - 1) + 1
 end_index = page_size * page_index
 

Setting In web.xml

Note that there is a MaxRows setting in web.xml which controls the maximum number of records returned by a SELECT.

Constructor Summary

Pager()

Method Summary

protected String	getEmittedText(String aOriginalBody) See class comment.
void	setPageFrom(String aPageIndexParamName) Name of request parameter that holds the index of the current page.

Methods inherited from class hirondelle.web4j.ui.tag.TagHelper

checkForContent, crossCheckAttributes, doTag, getPageContext, getPageName, getRequest, getResponse

Methods inherited from class SimpleTagSupport

findAncestorWithClass, getJspBody, getJspContext, getParent, setJspBody, setJspContext, setParent

Methods inherited from class Object

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

Constructor Detail

Pager

public Pager()

Method Detail

setPageFrom

public void setPageFrom(String aPageIndexParamName)

Name of request parameter that holds the index of the current page.

This request parameter takes values in the range 1..9999.

(The name of this method is confusing. It should rather be named setPageIndex.)

getEmittedText

protected String getEmittedText(String aOriginalBody)

See class comment.

Specified by:

getEmittedText in class TagHelper

Parameters:

aOriginalBody - is the evaluated body of this tag. If there is no body, or if the body is present but empty, then it is null.

Returns:

the text to display in the resulting web page.