Pager Tag Reference

Overview
License
Requirements
Installation
Examples
Tag Reference
Troubleshooting
Release History

The latest release of this tag library can be found at http://jsptags.com/tags/navigation/pager/.

Overview

The Pager Tag Library helps generate Google^SM and AltaVista® style search result navigators. It will take multiple pages worth of information, dynamically split it up into page sized pieces and generate a browsable index. It does this in a flexible way that allows designers to give the index just about any look desired.

License

/*
 *  Pager Tag Library
 *
 *  Copyright (C) 2000  James Klicman <james@jsptags.com>
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2.1 of the License, or (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

The full license can be found in the file LICENSE included with this distribution or on the web at http://www.gnu.org/copyleft/lesser.txt.

Requirements

JavaServer Pages 1.1 compliant Web Server/Servlet Engine
Java 1.1 or later runtime environment

Tomcat 3.1 Instructions

Choose the context in which to install. I'll use the "/examples" context created in the default Tomcat configuration for the following instructions.

Edit the tomcat/webapps/examples/WEB-INF/web.xml file and add the following lines inside the body of the <web-app>...</web-app> tags.


<taglib>
  <taglib-uri>
    http://jsptags.com/tags/navigation/pager
  </taglib-uri>
  <taglib-location>
    /WEB-INF/jsp/pager-taglib.tld
  </taglib-location>
</taglib>

Copy the file pager-taglib.tld to the tomcat/webapps/examples/WEB-INF/jsp directory.
Copy pager-taglib.jar to the tomcat/webapps/examples/WEB-INF/lib directory. You may need to create a tomcat/webapps/examples/WEB-INF/lib directory if it does not already exist.

Please Note: The 3.1 Beta version of Tomcat does not support tag libraries in jar files. The following steps will install for Tomcat 3.1 Beta.

Copy pager-taglib.jar to the tomcat/webapps/examples/WEB-INF/classes directory.
Change current working directory to the tomcat/webapps/examples/WEB-INF/classes directory.
Extract the contents of the pager-taglib.jar file with the command:
jar xvf pager-taglib.jar
There will be a META-INF directory created during the extraction, this can be removed.
The pager-taglib.jar file can now be removed from the tomcat/webapps/examples/WEB-INF/classes directory.

Copy the files pager-demo.jsp and jsptags.gif to the tomcat/webapps/examples directory.
Shutdown and restart tomcat.
Check out http://<yourserver>/examples/pager-demo.jsp

JRun 3.0 Instructions

Choose the server and web-app in which to install. The following instructions will install in JRun's default server and default web-app which is jrun/servers/default/default-app.

Edit the jrun/servers/default/default-app/WEB-INF/web.xml file and add the following lines inside the body of the <web-app>...</web-app> tags.


<taglib>
  <taglib-uri>
    http://jsptags.com/tags/navigation/pager
  </taglib-uri>
  <taglib-location>
    /WEB-INF/jsp/pager-taglib.tld
  </taglib-location>
</taglib>

Copy the file pager-taglib.tld to the jrun/servers/default/default-app/WEB-INF/jsp directory.
Copy pager-taglib.jar to the jrun/servers/default/default-app/WEB-INF/lib directory.
Copy the files pager-demo.jsp and jsptags.gif to the jrun/servers/default/default-app directory.
Restart JRun Default Server.
Check out http://<yourserver>/pager-demo.jsp

Generic Instructions

Choose the web-app in which to install. I'll use web-app/ to represent a generic web-app directory.

Edit the web-app/WEB-INF/web.xml file and add the following lines inside the body of the <web-app>...</web-app> tags.


<taglib>
  <taglib-uri>
    http://jsptags.com/tags/navigation/pager
  </taglib-uri>
  <taglib-location>
    /WEB-INF/jsp/pager-taglib.tld
  </taglib-location>
</taglib>

Copy the file pager-taglib.tld to the web-app/WEB-INF/jsp directory.
Copy pager-taglib.jar to the web-app/WEB-INF/lib directory.
Copy the files pager-demo.jsp and jsptags.gif to the web-app/ directory.
Restart your Servlet/JSP engine.
Check out http://<yourserver>/pager-demo.jsp

Examples

Please note that since the ex:searchresults tag is fictitious the following examples will not run as is. You must provide your own looping data source. As an alternative, you may repeat as many <pg:item>...</pg:item> tags as you wish to generate a static list of items.

Example 1. A Simple Pager

[ (1) << Previous ] 1 2 3 4 5 6 7 8 9 10 [ Next >> (3) ]


<%@ taglib uri="http://jsptags.com/tags/navigation/pager" prefix="pg" %>

<pg:pager>
  <pg:param name="keywords"/>

  <ex:searchresults>
    <pg:item>
      <%= searchResult %>
    </pg:item>
  </ex:searchresults>

  <pg:index>
    <pg:prev>
      <a href="<%= pageUrl %>">[ (<%= pageNumber %>) << Previous ]</a>
    </pg:prev>
    <pg:pages>
       <a href="<%= pageUrl %>"><%= pageNumber %></a> 
    </pg:pages>
    <pg:next>
      <a href="<%= pageUrl %>">[ Next >> (<%= pageNumber %>) ]</a>
    </pg:next>
  </pg:index>
</pg:pager>

Example 2. An AltaVista® Pager

Result Pages: [<< Prev] 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 [Next >>]


<%@ taglib uri="http://jsptags.com/tags/navigation/pager" prefix="pg" %>

<pg:pager url="http://www.altavista.com/cgi-bin/query" maxIndexPages="20">
  <pg:param name="pg"/>
  <pg:param name="q"/>

  <ex:searchresults>
    <pg:item>
      <%= searchResult %>
    </pg:item>
  </ex:searchresults>

  <pg:index>
    <font face=Helvetica size=-1>Result Pages:
    <pg:prev>&nbsp;<a href="<%= pageUrl %>">[<< Prev]</a></pg:prev>
    <pg:pages><%
      if (pageNumber.intValue() < 10) { 
        %>&nbsp;<%
      }
      if (pageNumber == pagerPageNumber) { 
        %><b><%= pageNumber %></b><%
      } else { 
        %><a href="<%= pageUrl %>"><%= pageNumber %></a><%
      }
    %>
    </pg:pages>
    <pg:next>&nbsp;<a href="<%= pageUrl %>">[Next >>]</a></pg:next>
    <br></font>
  </pg:index>
</pg:pager>

Example 2. A Google^SM Pager

This index references Google^SM for images so if your not connected to the net right now you will see broken images.

Result Page:

Previous

Next


<%@ taglib uri="http://jsptags.com/tags/navigation/pager" prefix="pg" %>

<pg:pager url="http://www.google.com/search">
  <pg:param name="q"/>
  <pg:param name="sa" value="N"/>

  <ex:searchresults>
    <pg:item>
      <%= searchResult %>
    </pg:item>
  </ex:searchresults>

  <pg:index>
    <center>
    <table border=0 cellpadding=0 width=10% cellspacing=0>
    <tr align=center valign=top>
    <td valign=bottom><font face=arial,sans-serif
      size=-1>Result Page: </font></td>
    <pg:prev ifnull="true">
      <% if (pageUrl != null) { %>
        <td align=right><A HREF="<%= pageUrl %>"><IMG
          SRC=http://www.google.com/nav_previous.gif alt="" border=0><br>
        <b>Previous</b></A></td>
      <% } else { %>
        <td><IMG SRC=http://www.google.com/nav_first.gif alt="" border=0></td>
      <% } %>
    </pg:prev>
    <pg:pages>
      <% if (pageNumber == pagerPageNumber) { %>
        <td><IMG SRC=http://www.google.com/nav_current.gif alt=""><br>
        <font color=#A90A08><%= pageNumber %></font></td>
      <% } else { %>
        <td><A HREF="<%= pageUrl %>"><IMG
          SRC=http://www.google.com/nav_page.gif alt="" border=0><br>
        <%= pageNumber %></A></td>
      <% } %>
    </pg:pages>
    <pg:next ifnull="true">
      <% if (pageUrl != null) { %>
        <td><A HREF="<%= pageUrl %>"><IMG
          SRC=http://www.google.com/nav_next.gif alt="" border=0><br>
        <b>Next</b></A></td>
      <% } else { %>
        <td><IMG SRC=http://www.google.com/nav_last.gif alt="" border=0></td>
      <% } %>
    </pg:next>
    </tr>
    </table>
    </center>
  </pg:index>
</pg:pager>

Tag Reference

pg:pager
pg:param
pg:item
pg:index
pg:prev
pg:pages
pg:next

pg:pager

The pg:pager tag defines the pager. Inside the pg:pager tag, use the pg:param tag to add preserve request parameters, use the pg:item tag to define items of information, use the pg:index tag to define a navigation index, and use the pg:prev, pg:pages and pg:next tags to define navigation elements.

Syntax


<pg:pager

  id="value"

  url="url"

  maxItems="int"

  maxPageItems="int"

  maxIndexPages="int"

  isOffset="true|false"

>

<%= pagerPageNumber %>

<%= pagerOffset %>

<%= pagerMaxItems %>

...

</pg:pager>

Exported Variables

Name	Type	Scope
pagerPageNumber	Integer	Nested
pagerOffset	Integer	Nested
pagerMaxItems	Integer	Nested

id: Specifies the id of the tag. The default id is "pager". The id is used as a prefix for exported variables which are available in the body of the pg:pager tag. If id is specified as "pg1" the exported variables become pg1Offset and pg1MaxItems.
url: Specifies the url to be used in the generated index. The default is the url of the current JSP page as returned by <%= request.getRequestURI() %> with any request parameters removed.
maxItems: Specifies the maximum number of items to be available in the generated index. The default and maximum value is 2147483647.
maxPageItems: Specifies the maximum number of items to be displayed in each page. The default value is 10.
maxIndexPages: Specifies the maximum number of pages to be included in the generated index. The default value is 10.
isOffset: Specifies that the first pg:item will be offset to the current pager offset. This is useful when the data source is a database that supports the limit & offset clauses. The default value is false.

pg:param

The pg:param tag is used inside the pg:pager tag to add request parameters to each page url in the index.

Syntax


<pg:param

  name="value"

  value="value"

 />

name: Specifies the required request parameter name.
value: Specifies an optional static value. The default is the request parameter specified by the name attribute.

pg:item

The pg:item tag is used inside the pg:pager tag to define page items. If the item is out of range for the current page it is not displayed.

Syntax


<pg:item>

...

</pg:item>

pg:index

The pg:index tag is used inside the pg:pager tag to specify the index. If there are no page items for the current page the index is not displayed.

Syntax


<pg:index>

...

</pg:index>

pg:prev

The pg:prev tag is used inside the pg:index tag to specify the link to the previous page. If there is no previous page the exported variables will be null.

Syntax


<pg:prev

  ifnull="true|false"

>

<%= pageUrl %>

<%= pageNumber %>

...

</pg:prev>

Exported Variables

Name	Type	Scope
pageUrl	String	Nested
pageNumber	Integer	Nested

ifnull: Specifies whether or not to evaluate the body if there is no previous page to the current page. The default is false, do not evaluate body. If the value is true then the body is evaluated when there is no previous page and the exported variables are set to null.

pg:pages

The pg:pages tag is used inside the pg:index tag to specify the link to each page in the index. The body of the pg:pages tag is processed for each page in the index. The variable pageNumber can be compared with pagerPageNumber exported by pg:page to determine the current page.

Syntax


<pg:pages>

<%= pageUrl %>

<%= pageNumber %>

...

</pg:pages>

Exported Variables

Name	Type	Scope
pageUrl	String	Nested
pageNumber	Integer	Nested

pg:next

The pg:next tag is used inside the pg:index tag to specify the link to the next page. If there is no next page the exported variables will be null.

Syntax


<pg:next

  ifnull="true|false"

>

<%= pageUrl %>

<%= pageNumber %>

...

</pg:next>

Exported Variables

Name	Type	Scope
pageUrl	String	Nested
pageNumber	Integer	Nested

ifnull: Specifies whether or not to evaluate the body if there is no next page to the current page. The default is false, do not evaluate body. If the value is true then the body is evaluated when there is no next page and the exported variables are set to null.

Troubleshooting

Translation Time Errors

If you get translation time errors reported for your JSP file, it may be a problem with your JavaServer Pages implementation.

Many JSP implementations do not correctly handle conversions of attributes in custom actions. This means that instead of automatically converting an attribute such as maxPageItems="5" to the correct (in this case) native type of int, the JSP engine incorrectly attempts to pass the attribute as a String.

The correct behavior has been clarified by JSP 1.1a Errata Issue #7 which states:

...
Conversions in attributes in custom actions

What type of conversions are applied to attribute values of a custom action. Specifically, what is done to a request-time attribute value, and what is done to a literal string.

Resolution

A request-time attribute value is passed with no conversion.

A literal string is converted following the rules in Table 2-4, section 2.13.2.
...

If you encounter this issue, I would recommend reporting the bug to your JSP server vendor.

In the mean time, you can work around the issue by using request-time values for any attributes that expect an int or boolean value. To specify a request time attribute simply wrap the value in <%= %>. Attributes such as maxPageItems="5" would become maxPageItems="<%= 5 %>" and ifnull="true" would become ifnull="<%= true %>".

Release History

September 26th, 2000 v1.1 Maintenance Release

Fixed bug which caused a ClassCastException by calling javax.servlet.jsp.tagext.TagData.getAttributeString() on a request-time attribute.

Modified pager-demo.jsp to use request-time attributes which are more compatible with the current releases of commercial JSP servers. (see JSP 1.1a Errata Issue #7)

Updated installation instructions for Tomcat.

Added installation instructions for JRun 3.0.

Added generic installation instructions.
March 29th, 2000 v1.0 Initial Release

Table of Contents

Overview

License

Requirements

Installation

Tomcat 3.1 Instructions

JRun 3.0 Instructions

Generic Instructions

Examples

Example 1. A Simple Pager

Example 2. An AltaVista® Pager

Example 2. A GoogleSM Pager

Tag Reference

pg:pager

Syntax

Exported Variables

id

url

maxItems

maxPageItems

maxIndexPages

isOffset

pg:param

Syntax

name

value

pg:item

Syntax

pg:index

Syntax

pg:prev

Syntax

Exported Variables

ifnull

pg:pages

Syntax

Exported Variables

pg:next

Syntax

Exported Variables

ifnull

Troubleshooting

Release History

Example 2. A Google^SM Pager