nevett.org
The Web Site of Fraser Nevett

Page Contents

  1. Main content body
  2. Site navigation (including site map)
  3. Search facility

Main Content Body

Paginate, a Smarty plugin

Example

List of 42 items, showing 5 per page:
  1. Item 1
  2. Item 2
  3. Item 3
  4. Item 4
  5. Item 5
1 - 5 | 6 - 10 | 11 - 15 | 16 - 20 | 21 - 25 | ...

Usage

Firstly, view or download the source code and copy it into you Smarty plugins directory, ensuring the filename is block.paginate.php. This plugin is released under the terms of the GNU General Public License.

Suppose you have a Smarty variable, $Items, which is an array of the items you wish to display in a list. This could be written as:

<ul>
 {foreach from=$Items item=item}
 <li>{$item}</li>
 {/foreach}
</ul>

To add pagination, simply wrap this in a {paginate} block and display the subset of data:

{paginate data=$Items subset=subset}
 <ul>
  {foreach from=$subset item=item}
  <li>{$item}</li>
  {/foreach}
 </ul>
{/paginate}

Appropriate links will be added beneath the list to allow a user to move between pages of items.

Parameters

Parameter Required Description
data yes

The set of data which is to be paginated.

Type: Array
subset no

The name of the variable to which the current subset of data should be assigned so that it can be iterated through and displayed.

Type: String
Default: subset
per_page no

The number of items of data to be displayed per page. This determines the size of the subset.

Type: Integer
Default: 10
page_links no

The number of page links to display in the pager.

Type: Integer or the string 'all'
Default: 5
href no
copy_get no

A comma separated list of the names of the current page's query string (GET) variables which should be appended to the page link. For example, this might include the search query if the paginator is use to display search results.

Type: String
start_var no

The name of the query string (GET) variable to be used to determine the index of the starting item in the subset.

Type: String
Default: start
next_back no

Whether or not “Next” and “Back” links should be displayed in the pager.

Type: Boolean
Default: false
style no

The paginator supports different styles, there are two built in, default and ol. The default style is simply a series of links separated by pipe (|) characters. The ol style marks up the paginator as an ordered list (using an <ol> and <li>s). Additionally, using the following 7 parameters, it is possible to completely customise the display format.

Type: Boolean
Default: default
prefix no

The string to be displayed before the pager.

Type: String
Default is dependent on the style parameter
suffix no

The string to be displayed after the pager.

Type: String
Default is dependent on the style parameter
format no

The string which defines the format of each page link. The following placeholders can be used:

%1$s
The URL of the page being linked; probably for us within the href attribute of a link.
%2$d
The index of the first item of the page being linked.
%3$d
The index of the last item of the page being linked.
%4$d
The page number of the page being linked.

Type: String
Default is dependent on the style parameter
current_format no

The string which defines the format of the page link to the page currently being displayed. The same placeholders can be used as with the format parameter.

Type: String
Default is the same as format
seperator no

The string which is inserted between each page link.

Type: String
Default is dependent on the style parameter
back_format no

The string which defines the format of the link to the previous page. This is only used if the next_back parameter is set to true. The following placeholder can be used:

%1$s
The URL of the previous page; probably for us within the href attribute of a link.

Type: String
Default is dependent on the style parameter
back_format no

The string which defines the format of the link to the next page. This is only used if the next_back parameter is set to true. The following placeholder can be used:

%1$s
The URL of the next page; probably for us within the href attribute of a link.

Type: String
Default is dependent on the style parameter