|
The results of our patent search often take up more than we
can comfortably display on one page. Thus we'd like to paginate
results across pages, providing previous/next links, and numbering
the results.
As we've seen, this can be accomplished with the SKIP
and
MAX
parameters to <SQL>
. The special variable $next
, at the end of the SQL loop, is set to the amount we need
to skip for the next page. Thus, if we <EXPORT $next>
, we
could make a link at the end of the results page to link to the next
page. We can also use $next
to number individual results
inside the SQL loop.
However, we have to do a bit of math to come up with a previous-page
link. We also have to do math if we want to provide direct links
to every page of results. While simple in principle, it can become
tiresome to hand-code the HTML and math to do pagination, every time
we write a new search script.
Using <pagelinks>
This is where the <pagelinks>
function comes in. Available
in Vortex versions after 3.0.945400000 (Dec. 16 1999), it automates
the printing of HTML for page links. In our patent example, it's
called at the end of the <search>
function.
It is normally called right after the ending </SQL>
(though it can be called on the first row as well). It prints the
"X through Y of Z documents" summary, as well as the page numbers
and previous/next links at the bottom. See the Vortex manual on
pagelinks
for full details on how to configure it. It
uses the special variables $rows.min
and $rows.max
set by <SQL>
to compute the page links.
The gory details
In most cases, the total row count is handled automatically by <SQL>
and <pagelinks>
, as in our patent example.
But read on if you want more info on the "behind the scenes" math:
$indexcount
The $indexcount
variable is set by <SQL>
at
the start of the first row returned. It is an estimate of how
many total rows the query will returned, based on the
index used to help resolve the query.
If the index can completely resolve the query, $indexcount
will match the true final result count. We can then use this
number to predict how many page links we'll need, and to print
the "X through Y of Z documents" summary, as <pagelinks>
does automatically.
However, some SQL queries require post-processing or ANDing and
cannot be resolved by an index alone. The index matches must be
further processed by Texis to determine the final result set. Thus
$indexcount
is an estimate. The only way to get an
exact count in such cases is to let the query run to
completion. But that might mean processing thousands of rows, when
the user only wants to see the first 10, solely to establish that
exactly 98,576 rows matched instead of roughly 100,000. In
most cases getting those first 10 matches quickly is more important
than knowing the exact count.
$rows.min / $rows.max - A better count
The problem for Vortex programmers is knowing when $indexcount
is accurate or not, and to what degree. The $rows.min
and $rows.max
variables help here. They
are the minimum and maximum number of total rows that the query will
return. If unknown, they are -1 and -2 respectively. These
variables are updated every row, starting with the first, and at the
end of the SQL loop. $rows.max
is typically the same as $indexcount
. $rows.min
is often just one ahead of $next
, if the exact row count isn't known. (These vars were
introduced in Vortex versions after Nov. 16 1999.)
We can use these variables to draw some firmer rules about pagination:
- If $rows.min
equals $rows.max
, then we have
an exact row count. This may occur for completely indexed queries,
at the first row and beyond (in a near-future release of
Texis). It also occurs at the end of the loop in the obvious case
when we exceed MAX
.
- If $rows.min
is greater than $next
at any
point, we know there's more rows. <SQL>
will do a
look-ahead to check for "is there one more row?" and reflect it in
$rows.min
. This saves us upping MAX
by one to
check for more rows (ie. next-page).
- If either is greater than or equal to 0, that boundary
is known, ie. the minimum or maximum limit.
Of course, we can also just use <pagelinks>
and avoid
the hassle.
|