Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages
CGI::Pager(3) User Contributed Perl Documentation CGI::Pager(3)

CGI::Pager - generate HTML pagination linkage easily.

Generates helper data and HTML for paginated representation of results.

  my $pager = CGI::Pager->new(
     total_count => $search_results_count,
     page_len    => 50,

  print 'Found ', $search_results_count, ' results, displaying: ',
         $pager->first_pos_displayed, ' - ', $pager->last_pos_displayed, ' ';

  # Display links to first and previous page, if necessary.
  unless ($pager->is_at_start) {
     print a({ -href => $pager->first_url }, 'First page'), ' ',
           a({ -href => $pager->prev_url }, '<< Previous page');

  # Display links to each individual page of results.
  foreach my $page ($pager->pages) {
     if ($page->{is_current}) {
        print strong($page->{number});
     else {
        print a({ -href => $page->{url} }, $page->{number});

  # Display links to next and the last page, if necessary.
  unless ($pager->is_at_end) {
     print a({ -href => $pager->next_url }, 'Next page >>'), ' ',
           a({ -href => $pager->last_url }, 'Last page');

  my $pager = CGI::Pager->new(
     labels => {
        first => 'First',
        last  => 'Last',
        next  => 'Next',
        prev  => 'Previous',
     links_order => [ qw/first prev pages next last/ ],
     links_delim => ' &nbsp; | &nbsp; ',
     pages_delim => ' ',

     first_page_url => $pager->first_url,
     prev_page_url  => $pager->prev_url,
     next_page_url  => $pager->next_url,
     last_page_url  => $pager->last_url,
     page_links     => $pager->html('pages'),

 print CGI::Pager::quick_html(
    total_count => $search_results_count,
    page_len    => 50,
    html_mode   => 'combined',

CGI::Pager performs the "dirty work" necessary to program paginated data display in a web application. Based on given resultset size, page size, and offset value sensed from current URI, it constructs links for navigation between results pages. It can be used conveniently from a templating system, has both OO and functional interface, and can optionally generate necessary HTML itself.

The constructor, accepting named configuration parameters. See "PARAMETERS" below.
is_at_start, is_at_end
Return true if the pager is at the start or the end of recordset respectively.
next_offset, prev_offset, last_offset
Return offset value the respective pages. If there's a bounds conflict, like when you call prev_offset while on the first page, undef is returned.
first_pos_displayed, last_pos_displayed
Return the position (starting from 1) of the first or last row respectively, displayed on current page.
first_url, prev_url, next_url, last_url
Return URLs of the respective pages as URI objects. Bounds conflicts are handled like in the above family of methods.
Return total count of results, as set on initialization.
Returns reference to an array of hashes representing pages in the result set. The hashes have following keys: "url" - the URL of the page, "number" - the number of page, starting from 1, and "is_current" - true if page is the currently displayed page.
Returns HTML string with navigational links according to $mode, which can be: "first", "last", "prev", "next", "pages", "combined" or "combined_div". The first four will produce a single link to respective page. 'pages' yields a string of links to individual pages. "combined", which is the default, is concatenation of these. "combined_div" is like "combined", but wrapped in a DIV element with class attribute set to "navBar". The concatenation of links can be controlled by "links_order", "links_delim" and "pages_delim" initialization parameters.
Not a method, but function, designed to be called as "CGI::Pager::quick_html". Returns HTML generated by internally created temporary pager instance. Made for those rare cases when not using OO style is cleaner. Accepted parameters are the same as for constructor, except with the extra "html_mode" which works like the $mode parameter of "html" method.

All options are given as named parameters to constructor (when using OO style) and aren't then changeble - a CGI::Pager instance is not meant to persist between requests. Below is a list of valid options:
  • "total_count"

    The size of your recordset. This is the only mandatory option.

  • "page_len"

    The number of items displayed per page. Default is 20.

  • "offset_param"

    The name of the GET request variable holding current offset within the resultset. Defaults to 'offset'. Change if you name your variable differently.

  • "hide_zero_offset"

    If true (default), generated URL of the first page will not contain the offset parameter (like, '&offset=0'.) This is what you want in most cases.

  • "url"

    Specifies the base URL, which will be used to produce URLs in all links, generated by this module. Defaults to value of $ENV{REQUEST_URI}, which should be fine in most web application environments.

  • "labels"

    Content to place inside generated links. Can be arbitary text or HTML. Given as a hash reference, see "SYNOPSIS" for explanatory example, which also shows default values.

  • "links_order"

    In what order navigational links will be placed, when generating HTML in 'combined' format. For example/defaults, see the above.

  • "links_delim"

    Delimiter used to space ordinary links (i.e, 'First', 'Previous', etc) when generating HTML in 'combined' format. Defaults to ' &nbsp; '.

  • "pages_delim"

    Delimiter used to space individual page links. Defaults to ' '.

This module operates on the assumption that current offset is passed as a GET request variable (except that for the first page, where it's OK for it to be absent.)

An instance of CGI::Pager is meant to last only for the duration of the request and isn't designed to be reused, like one might try in a mod_perl environment.


Egor Shipovalov, <>

Copyright 2006 by Egor Shipovalov

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

2014-06-10 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.