{pager}
Page links for a tag written with the page option: first and last, a window round the current page, previous and next.
Syntax
{pager 'name'}
{pager 'name', window=2, query='p'}
{pager 'name'} ... {$kind} {$page} {$label} {$href} ... @else@ ... {/pager}Parameters
-
name -
The paged tag - its
name=, or the tag's own name. Left out, the pager follows the last paged tag of the page.
Options
-
window -
The number of pages shown on each side of the current one; 2 by default. The first and the last page always show, a gap (
…) stands for the pages left out. -
query -
The request value the links set. By default the variable
page=was written with -page=$pgmakes the links setpg- elsepage.
Description
{pager 'products'} writes the page links for a tag that the page handling option slices - {products page=$pg ?? 1, rows=12}. While that tag renders, its paging books the current page, the rows per page and the number of rows it pages through (after the options written before page, such as a where); the pager reads that booking. So the paged tag must come first: under the strict check a pager without a paged tag of that name before it is an error.
Written alone the tag answers <nav class="pager" aria-label="Pagination"> with links: previous, the first page, a window of pages around the current one, the last page, next. The current page is marked aria-current="page", a gap of pages left out is …, and a previous or next that does not exist is a disabled <span>. The labels pager.label, pager.previous and pager.next come from the application's _lang/ catalog when it has them. When everything fits on one page the pager answers nothing.
Each link is $padGo with the page the request asked for, the request's other query values kept and the page value set - so a search or filter in the address survives. The value is the variable the page option was written with (page=$pg gives &pg=3), or query=.
Written as a pair the pager hands the links over as rows for markup of your own: kind (prev, next, page, current, gap), page, label and href - empty for a gap and for a missing previous or next. A single page gives no rows, so the pair shows its @else@ branch. A table of the Select subsystem is paged by its SQL limit; the pager then counts the same query to know the total.
Examples
Page links
The tag with page= comes first; the pager reads what its paging left and links the pages.
<p>{numbers page=$pg ?? 1, rows=5}{$numbers} {/numbers}</p>
{pager 'numbers'}<?php
$numbers = range ( 1, 23 );
?>16 17 18 19 20
A window round the current page
window= sets how many pages show on each side; the first and the last are always there.
<p>{cities page=$cityPage ?? 6, rows=2}{$cities} {/cities}</p>
{pager 'cities', window=1}<?php
$cities = [ 'Amsterdam', 'Berlin', 'Copenhagen', 'Dublin', 'Edinburgh', 'Florence',
'Geneva', 'Helsinki', 'Istanbul', 'Jerusalem', 'Kyoto', 'Lisbon',
'Madrid', 'Naples', 'Oslo', 'Prague', 'Quebec', 'Riga', 'Seville', 'Tallinn' ];
?>Kyoto Lisbon
Markup of your own
As a pair the pager hands the links over as rows: kind, page, label and href.
<p>{letters page=$letterPage ?? 2, rows=4}{$letters} {/letters}</p>
<p>
{pager 'letters'}
{if $href eq ''}
<span style="color:#999">{$label}</span>
{elseif $kind eq 'current'}
<strong>[{$label}]</strong>
{else}
<a href="{$href}">{$label}</a>
{/if}
@else@
Everything fits on one page.
{/pager}
</p><?php
$letters = range ( 'a', 'n' );
?>See also
- {datatable} Rows as a complete HTML table - formatted numbers, a totals row, sorting and paging on the server.
- {array} Runs a SQL query on the application database and repeats its content once per row.
- {collection} Reads a folder of Markdown files from _content/ and repeats its content once per file, the front matter as fields.