Pagination

The Query snippet ties into the Craftsman Coding Pagination Library. Before pagination links can be rendered, you must do two things:

1. You need to set a &_limit value: this will define the number of results you want to show per page
2. Your query must return more than than number of results (i.e. you need to have multiple pages of results)

If you haven't defined a limit (i.e. the number of results you want displayed on each page), then all results will be shown on a single page. Or if you have specified a limit, but you don't have enough rows in your search results, then there is no need for pagination.

Styles

The easiest way to change the appearance of the links generated by the Query Snippet is to use one of the built-in styles by setting the &_style argument:

[[Query? &_style=`flickr`]]

More commonly, however, you will also be specifying other formatting parameters and you must dynamically listen for the offset parameter in your URLs. Make sure you include the [[+pagination_links]] placeholder in the &_tplOuter or somewhere on your page. A more complete example might look like this:

[[!Query? &_limit=10 &_style=`apple` 
    &_tpl=`<li><a href="[[~[[+id]]]]">[[+pagetitle]]</a></li>` 
    &_tplOuter=`<ul>[[+content]]</ul>[[+pagination_links ]]` 
    &_offset=`offset:get`]]

default

Short and sweet with no embedded styles. Start here if you want to use your own CSS.

apple

Tastes like Apple.

digg

Dig it.

flickr

See the Pagination Library for the latest supported styles.

---

Custom Formatting Overview

Formatting can be complicated because it involves a handful of interrelated formatting strings.

Here is a sample representation of some pagination links:

	<<First <<Prev 1 2 3 Next>> Last>>
	\_____/ \____/ ^ ^ ^ \____/ \____/
	   |       |   | | |    |      +----- lastTpl
	   |       |   | | |    +------------ nextTpl
	   |       |   | | +----------------- currentPageTpl
	   |       |   +-+------------------- pageTpl
	   |       +------------------------- prevTpl
	   +--------------------------------- firstTpl        
\_________________________________________________/
                    |
                    +-------------------- outerTpl

Formatting Strings

You can copy the pagination config file from core/components/query/config/default.config.php

firstTpl : formats a link that jumps to the first page of results.

<a href="[[~[[*id]]? &offset=`0`]]">&laquo; First</a> &nbsp;

lastTpl : formats the link that jumps to the last page of results.

&nbsp;<a href="[[~[[*id]]? &offset=`[[+offset]]`]]">Last &raquo;</a>

prevTpl : formats a link that jumps to the previous page of results.

<a href="[[~[[*id]]? &offset=`[[+offset]]`]]">&lsaquo; Prev.</a>&nbsp;

nextTpl : formats the link that jumps to the next page of results.

&nbsp;<a href="[[~[[*id]]? &offset=`[[+offset]]`]]">Next &rsaquo;</a>

currentPageTpl : formats the indicator of the current page (usually not a link).

&nbsp;<span>[[+page_number]]</span>&nbsp;

pageTpl : formats a link to a specific page of results.

&nbsp;<a href="[[~[[*id]]? &offset=`[[+offset]]`]]">[[+page_number]]</a>&nbsp;

outerTpl : formats the HTML that wraps the entire generated set of links.

<div id="pagination">[[+content]]<br/>
Page [[+current_page]] of [[+page_count]]<br/>
Displaying records [[+first_record]] thru [[+last_record]] of [[+record_count]]
</div>

Placeholders

When pagination links are created, the following placeholders are set:

• extra
• base_url e.g. "/my/page?"
• offset = 0
• results_per_page 5
• page_count
• current_page
• lowest_visible_page : page number of first visible page
• highest_visible_page : page number of the last visible page
• first_record : first record on the current page
• last_record : last record on the current page
• record_count : total number of pages
• link_cnt : max number of page links
• content : used in the outerTpl to contain the links
• pagination_links : the final result

Examples

Here's a sample query on a custom data set:

[[!Query? 
  &status=`approved` 
  &_pkg=`reviews;[[++core_path]]components/reviews/model/;axpr_` 
  &_classname=`Reviews` 
  &_sortby=`created` 
  &_sortdir=`DESC` 
  &_tpl=`reviewTpl` 
  &_limit=`5` 
  &_offset=`offset:get` 
  &_config=`myconfig`]]

We're using a custom config to format the pagination links. Here's what it looks like:

<?php
return array (
    'firstTpl'		=> '',
    'lastTpl' 		=> '',
    'prevTpl' 		=> '<a href="[[~[[*id]]? &offset=`[[+offset]]`]]">&lt;&nbsp;Prev.</a>&nbsp;',
    'nextTpl' 		=> '&nbsp;<a href="[[~[[*id]]? &offset=`[[+offset]]`]]">Next.&nbsp;&rsaquo;</a>',
    'currentPageTpl'=> '&nbsp;<span>[[+page_number]]</span>&nbsp;',
    'pageTpl' 		=> '',
    'outerTpl' 		=> [[+content]]
	    Displaying [[+first_record]] thru [[+last_record]] of [[+record_count]] reviews',
);
?>

NOTE: that the _offset parameter uses an input filter to read the offset parameter out of the generated URLs.