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"
SKIPvariable used by the
SQLquery. This is not simply the
SKIPvalue, but the variable name itself: not only is the current
SKIPvalue obtained from it, but this variable will be set to the correct
SKIPvalue when each link is printed. It is thus assumed that this variable is URL
EXPORTed as well. The default is the
SKIPvariable named in the last
<SQL>statement (in versions after Dec. 16 1999); if not given,
$rows.maxto 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
NUMROWSoption can be set to the total number of rows to assume the query will return, overriding
$rows.max. (Note: to just control the number of page links produced without affecting the "X through Y of Z documents" numbers, use
PGSZThe number of rows per page. This should correspond to the
MAXvalue; in versions after Dec. 16 1999
PGSZtherefore defaults to that value. Otherwise it defaults to 10.
MAXPGSThe maximum number of page links to call the
PGFUNCcallback for; the default is 10. This is useful to avoid printing links for thousands of potential pages for a noisy query.
SUMFUNCThe 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
SUMFUNCfunction has several parameters initialized when called, as described below.
PREVFUNCThe 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 parameters.
NEXTFUNCThe 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.
PGFUNCThe 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 to
MAXPGSpages. The default is
pgfunc; if that does not exist a default set of page links will be printed. See below for parameters.
ORDERThe order in which to call the summary, previous, next, and page link callbacks. Its value is a comma-separated list of the strings "
next", and/or "
page". The default is "
sum,prev,page,next": 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.
URLENDThe 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),
URLENDcan be set to a replacement for
URLENDwas 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
startrowThe first row of the current page's results, counting from 1 as
endrowThe ending row of the current page's results, counting from 1.
numrowsThe total number of rows the query will return (i.e.
pgThe page number (counting from 1) that this callback is to print a link for (for
PGFUNC). This is not necessarily the current page.
curpgThe page number of the currently displayed page. The
PGFUNCcallback uses this as it iterates through pages: if
$pgis 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.)
numpgsThe total number of pages, counting from 1, in the entire result set.
pgszThe number of rows per page, derived from
PGSZor its default.
validOnly set for the
NEXTFUNCcallbacks, 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.
prevOnly set for the
NEXTFUNCcallbacks, this is nonzero if the callback is
PREVFUNCand 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.