The Pagination System

When a loop returns many results (dozens of articles, thousands of petition signatures), it is rarely practical, and sometimes impossible, to display everything on just one page.

A better solution would be to display the results on multiple pages, with a navigation system to go from one page of results to another. Even if this can be delivered with a combination of ordinary SPIP loops, such a solution would be relatively complex.

Therefore, in SPIP 1.9, a new feature has been introduced to easily paginate the results of a loop.


The basic version of the pagination system may be used by adding one tag and one criterion to your loops:

  • the criterion {pagination} will paginate the loop it is applied to,
  • the tag #PAGINATION, used in one of the optional parts (“before” or “after”) of this loop will display the pagination links.
<BOUCLE_page(ARTICLES) {par date} {pagination}>

For a site with 90 published articles, this loop will display the ten most recent articles, and, at the top of the list, a list of links to the pages showing the 10 next elements, the 10 after that, etc. The resulting links would be similar to the following:

0 | 10 | 20 | 30 | 40 | 50 | 60 | 70 | 80 | ...

The index of the article slice to display will be provided in the URL with the parameter debut_page=x with the same name as the loop it refers to. This parameter can be used in other loops with the usual criterion {debut_page,10}.

Note: the total number of links displayed is limited; if you exceed the available display space, dots will be shown to go to the end of the pagination list or to come back to its beginning.

Pagination anchors

When using the #PAGINATION tag, HTML anchors are introduced which allow the browser to navigate directly to the part of the page containing the pagination. However, if the pagination links have to be placed below the list of articles (for example), then it would be better to place this anchor at the beginning of the list.

The #ANCRE_PAGINATION tag can be used to place the anchor somewhere else. This will just return the right HTML code for the anchor and tell the #PAGINATION tag not to display its anchor.

<BOUCLE_page(ARTICLES) {par date} {pagination}>

The total number of results

In a loop with the {pagination} criterion, the tag #TOTAL_BOUCLE will only display the number of elements displayed by the loop. This will then return 10 (by default) for all the pages except the last page that may contain less results.

To display the total number of elements that would have been displayed by the loop without {pagination}, you should use the #GRAND_TOTAL tag.

<BOUCLE_pagination (ARTICLES) {pagination}>
#TITRE <br />
There are #GRAND_TOTAL articles, this page only displays #TOTAL_BOUCLE articles at a time.

will display: “There are 15570 articles, this page only displays 10 articles at a time.”

Changing the {pagination} “step”

The default number of elements returned by a paginated loop is 10. This can easily be modified by adding a parameter to the criterion.

For example,

<BOUCLE_page (ARTICLES) {pagination 5}>
#TITRE <br />

will display the titles of the 5 articles stating from the article corresponding to the current value of the debut_page environment variable.

The value of the parameter can be a constant or any tag — in particular #ENV{xx} — which give the opportunity to do a fully on-request display.

Pagination and inclusions

If the pagination is in an included loop, you must add the parameter {self=#SELF} to the INCLUDE tag. This is required for the included template to be able to compute the parameter debut_xxx, and is also justified for safety reasons (the #PAGINATION tag is actually calculated based on the complete URL of the page).

Since SPIP 1.9, the {self=#SELF} criterion has been replaced by using a pair of other criteria: {env} {ajax} [1].

Naming the pagination criteria

When you use the same included template segment several times on the same page, as with:

<BOUCLE_incluse(ARTICLES) {id_rubrique} {par titre}>
  <INCLURE{fond=motsgroupe5} {id_article} {ajax} {env}>

and that this INCLURE has a pagination implemented (which is why we use the {env} criterion), whenever you click on a pagination, you will see all of the paginations modified at the same time.
To avoid this happening, you will need to simply name the pagination criterion inside the included file with a name that will be different for each inclusion:

<BOUCLE_groupe5(MOTS) {id_groupe=5} {pagination 15 #ID_ARTICLE}>
  <p class="pagination">#PAGINATION</p>

You may also wish to specify when calling the INCLURE the name that you want to assign to the pagination criterion:

<INCLURE{fond=page_paginee, env, nom_p=_abc}>
<INCLURE{fond=page_paginee, env, nom_p=_def}>

and within page_paginee.html you would code:

<BOUCLE_a(ARTICLES) {pagination 25 #ENV{nom_p}}>
  #TITRE<br />

Styling the pagination

The list of pages constructed by the #PAGINATION contains a series of links with the current page having the class “.on”. You can therefore style this list by changing the styles of the <tt>a</tt> and <tt>.on</tt> selector.

Selecting the pagination model

Since SPIP 1.9.1, the #PAGINATION tag can accept a parameter for the {modele}, which allows you to modify the displayed results of the tag.

This is how #PAGINATION{precedent_suivant} will display the links to the previous and following pages. The links will look like this:

previous page | next page

#PAGINATION{page} will display something that looks like this:

1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | ...

#PAGINATION{page_precedent_suivant} will display something like this:

< 1 | 2 | 3 | 4 | 5 | 6 | >

It is possible to define other pagination models, which need to be named pagination_modelname. When building your own, it might be helpful to inspire yourself from those that are delivered with the standard SPIP distribution located in the prive/modeles/ directory (prior to and including version 1.9.2 of SPIP, they were located in dist/modeles/) . For more information on this, please read the relevant documentation about models.


[1Note: in order for the {ajax} criterion to be recognised for the #PAGINATION tag, that tag must be surrounded by an element with the pagination class.

Caution: This mechanism is a lot simpler than the contribution provided by SPIP-Contrib’, and is incompatible with that contribution. If you used that contribution, you will have to review your templates.

Author mortimer Published : Updated : 26/10/12

Translations : català, English, Español, français, italiano, Nederlands