When you have lots of items to list, sometimes there's more than you want to show on one page. The universal solution to this is pagination: break the list up into some number of pages, with a maximum number of items per page. Of course, you then need some sort of control to navigate between the pages.
Webvanta provides a very easy-to-use pagination feature that you can apply to any database content. Suppose, for example, that you have dozens or hundreds of articles. You could list all of them, like this:
<w:kb:item:each>
<h2><a href="<w:path url='article' />"><w:name /></a></h2>
<p><w:description /></p>
</w:kb:item:each>
But that page could get awfully long, and take a long time to generate (if it is not cached). Here's the same code, modified to paginate in pages of 10 items each:
<w:kb:item>
<w:paginate by='name desc' limit='10' start='1' page='auto' type='article'>
<div><w:pagination_widget /></div>
<w:each>
<h2><a href="<w:path url='article' />"><w:name /></a></h2>
<p><w:description /></p>
</w:each>
</w:paginate>
</w:kb:item>
Note that the paginate element needs to fit in between "w:kb:item" and "each", which are combined onto one line in the first example. In the second example, we split that statement into two lines, and insert the pagination statement and the pagination widget between them:
<w:kb:item>
<w:paginate by='name desc' limit='10' start='1' page='auto' type='article'>
<div><w:pagination_widget /></div>
<w:each>
The paginate statement (second line above) tells Webvanta to break the database contents into page-sized sections, and display only the current page. You can set a variety of parameters, as defined in the table below. These are mostly the same as those for kb:item:each.
Parameter | Value |
---|---|
by | Determines how the results are sorted; field name followed by sort direction ('asc' or 'desc') |
limit | Maximum number of items to display per page |
start | First item to include. If you are paginating all content, this should be "1". If there is a "main" page that lists, for example, the first 5 articles, and then you wanted a paginated "more articles" page that started with article 6, you would use start="6" |
page | Normally should be "auto", which causes the particular page displayed to be determined by a parameter in the URL. |
type | Item type(s) to be included (omit for all) |
category | Category(ies) to be included (omit for all) |
To display the pagination widget wherever you want, simply insert the code <w:pagination_widget />. This returns the HTML code for the set of page numbers and previous and next controls, such as this:
Each page number displayed in the widget is linked to the same URL as the current page, but with the value of the page parameter set.
You can start with the default settings for the pagination widget, and you can add styling via CSS; you only need to make changes to the widget's parameters if you want to customize its HTML.
The table below summarizes the pagination widget options:
Parameter | Default Value | Function |
---|---|---|
previous_label | "« Previous" | "Go to previous page" link |
next_label | "Next »" | "Go to next page" link |
page_links | true | Set to false to show only previous/next links (no list of page numbers) |
inner_window | 4 | How many links are shown around the current page |
outer_window | 1 | How many links are around the first and the last page |
separator | single space | String separator for page HTML elements |
class | pagination | CSS class name for the generated DIV |
container | true | Toggles rendering of the DIV container for pagination links. Set to false only when you are rendering your own pagination markup |