pagelinks function automatically paginates the results of
a SQL search, printing the necessary HTML and links for previous/next
buttons etc. It eliminates the tedious code needed to compute
SKIP values and loop over numbered-page links.
The values of
(here) are used to compute the necessary page
link information. Thus,
pagelinks can be called after the
SQL loop ends, or at the very first row (though possibly with a
different accuracy, if the true row count is not known yet).
When called with no options,
pagelinks prints out an "X
through Y of Z documents" summary, previous- and next-page links, and
numbered page-by-page links in a default format. In order to compute
these links, the associated
MAX must be known, so that skips and page sizes can be set
pagelinks automatically uses the last
SKIP var and
value. To ensure that the links
work properly, it is the programmer's responsibility to
the necessary variables for the original search, such as the
SKIP variable and any
<SQL> query parameters.
Since pagination design varies widely by application,
pagelinks has a number of options to fully control output
formatting, as well as defaults for use in simple "quick and dirty"
SKIP variable used by the
SQL query. This is
not simply the
SKIP value, but the variable name
itself: not only is the current
SKIP value obtained from
it, but this variable will be set to the correct
when each link is printed. It is thus assumed that this variable
EXPORTed as well. The default is the
variable named in the last
<SQL> statement (in versions
after Dec. 16 1999); if not given,
skip is assumed.
pagelinks will use
$rows.max to get the
maximum total rows the query will return and thus compute how many
links to create. If that number is known to be inaccurate, or a
different limit is to be forced, the
NUMROWS option can be
set to the total number of rows to assume the query will return,
$rows.max. (Note: to just control the number of
page links produced without affecting the "X through Y of Z
documents" numbers, use
The number of rows per page. This should correspond to the
MAX value; in versions after Dec. 16 1999
PGSZ therefore defaults to that value. Otherwise it
defaults to 10.
The maximum number of page links to call the
callback for; the default is 10. This is useful to avoid printing
links for thousands of potential pages for a noisy query.
The name of the function to call to print the "X through Y of Z
documents" summary. The default is
sumfunc; if that
function does not exist, a default summary will be printed. The
SUMFUNC function has several parameters initialized when
called, as described below.
The name of the function to call to print the previous-page button
link. The default is
prevfunc; if that does not exist a
default previous-page link will be printed. See below for
The name of the function to call to print the next-page button
link. The default is
nextfunc; if that does not exist a
default next-page link will be printed. See below for parameters.
The name of the function to call to print the numbered-page links.
This is called once for each page in the projected result set, up
MAXPGS pages. The default is
pgfunc; if that
does not exist a default set of page links will be printed. See
below for parameters.
The order in which to call the summary, previous, next, and page
link callbacks. Its value is a comma-separated list of the
page". The default is "
print the summary first, then the previous-page link, then the
page links, then the next-page link. If a callback is not listed
it will not be called.
The additional function and MIME extension to add to URLs. This
only applies to URLs printed by the builtin callbacks: if a script
callback is used the programmer just prints the complete URL as
needed. Normally, the builtin callbacks print URLs as
$url/$urlfunc$urlext$urlq (with the original values of
$urlext), so that they will have the
same start function as the current invocation. If the links are
to enter elsewhere (but the same builtin callbacks are desired),
URLEND can be set to a replacement for
was added in version 3.0.945400000 19991216.
callback functions will have the following parameters set each time
they are called. Note that not all parameters are set for all
The first row of the current page's results, counting from 1 as
The ending row of the current page's results, counting from 1.
The total number of rows the query will return
$rows.max or the
The page number (counting from 1) that this callback is to print a
link for (for
PGFUNC). This is not necessarily the current
The page number of the currently displayed page. The
PGFUNC callback uses this as it iterates through pages: if
$pg is equal to
$curpg, then a link isn't generated
because that's the current page. (The default callback bolds this
number instead of making it a link.)
The total number of pages, counting from 1, in the entire result set.
The number of rows per page, derived from
PGSZ or its default.
Only set for the
this is nonzero if the link is "valid", i.e. based on the current
page whether a previous or next link is valid. There's no
previous page for the first page, and no next page for the last
page. Thus the default callback doesn't print a previous/next
link when this is 0.
Only set for the
this is nonzero if the callback is
PREVFUNC and zero for
NEXTFUNC. Provides a way to combine the previous- and
next-page callbacks into one function if desired.
In addition to these parameters, the parameter named by
SKIPVAR (or its default) will be set to the proper
value for the link being generated. Thus the variable should be
EXPORTed to the URL for the skip to take effect on links.