Displaying Paginated Database Results

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.

With and Without Pagination

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>

Setting Pagination Options

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)

Pagination Widget

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