pagelinks - paginate SQL results

SYNOPSIS

<pagelinks [options]>

DESCRIPTION
The 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 $rows.min and $rows.max (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 <SQL> statement's SKIP and MAX must be known, so that skips and page sizes can be set properly. Thus pagelinks automatically uses the last <SQL> statement's SKIP var and MAX value. To ensure that the links work properly, it is the programmer's responsibility to EXPORT 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" pagination:

• SKIPVAR The 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 SKIP value when each link is printed. It is thus assumed that this variable is URL EXPORTed as well. The default is the SKIP variable named in the last <SQL> statement (in versions after Dec. 16 1999); if not given, skip is assumed.

• NUMROWS Normally 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, overriding $rows.max. (Note: to just control the number of page links produced without affecting the "X through Y of Z documents" numbers, use MAXPGS.)

• PGSZ The number of rows per page. This should correspond to the SQL loop's MAX value; in versions after Dec. 16 1999 PGSZ therefore defaults to that value. Otherwise it defaults to 10.

• MAXPGS The maximum number of page links to call the PGFUNC callback for; the default is 10. This is useful to avoid printing links for thousands of potential pages for a noisy query.

• SUMFUNC 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.

• PREVFUNC 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 parameters.

• NEXTFUNC 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.

• PGFUNC 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 to MAXPGS pages. The default is pgfunc; if that does not exist a default set of page links will be printed. See below for parameters.

• ORDER The order in which to call the summary, previous, next, and page link callbacks. Its value is a comma-separated list of the strings "sum", "prev", "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.

• URLEND 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 $urlfunc and $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 /$urlfunc$urlext, e.g. /search.html. URLEND was added in version 3.0.945400000 19991216.

The SUMFUNC, PREVFUNC, NEXTFUNC and PGFUNC callback functions will have the following parameters set each time they are called. Note that not all parameters are set for all callbacks:

• startrow The first row of the current page's results, counting from 1 as $next does.

• endrow The ending row of the current page's results, counting from 1.

• numrows The total number of rows the query will return (i.e. $rows.max or the NUMROWS value).

• pg The page number (counting from 1) that this callback is to print a link for (for PGFUNC). This is not necessarily the current page.

• curpg 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.)

• numpgs The total number of pages, counting from 1, in the entire result set.

• pgsz The number of rows per page, derived from PGSZ or its default.

• valid Only set for the PREVFUNC and NEXTFUNC callbacks, 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.

• prev Only set for the PREVFUNC and NEXTFUNC callbacks, 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 SKIP value for the link being generated. Thus the variable should be EXPORTed to the URL for the skip to take effect on links.