On préférera alors répartir les résultats en plusieurs pages, avec un système de navigation page à page. S’il est possible de réaliser cela avec des boucles SPIP ordinaires, c’est tout de même relativement complexe.
Aussi SPIP 1.9 introduit-il un système simplifié de pagination des résultats d’une boucle.
Exemple
Au plus simple, ce système est composé d’un critère et d’une balise :
- le critère
{pagination}s’ajoute sur la boucle à paginer ; - la balise
#PAGINATION, placée dans une des parties optionnelles (« avant » ou « après ») de la boucle, affiche la « pagination ».
Si le site comporte 90 articles publiés, cette boucle affichera la liste des dix plus anciens articles, surplombée de liens conduisant vers la page qui affiche les dix suivants, les dix d’après, etc. Ces liens sont numérotés comme suit :
Le numéro à partir duquel les résultats sont affichés est passé dans l’url via un paramètre {debut_page=x} portant le même nom (ici, « page ») que la boucle concernée. (Ce paramètre est exploitable dans une autre boucle via le critère classique {debut_page,10}.)
A noter : le nombre total de liens affichés est limité ; des points de suspension permettent, le cas échéant, d’aller directement à la toute fin de la liste, ou de revenir au tout-début.
Ancres de pagination
La balise #PAGINATION comporte une ancre html qui permet au navigateur d’afficher directement la partie de la page qui est paginée ; toutefois si l’on veut mettre les liens de pagination en dessous de la liste des articles, il faut pouvoir placer l’ancre au-dessus de la liste.
C’est à cela que sert la balise #ANCRE_PAGINATION, qui retourne l’ancre en question, et interdit à la balise #PAGINATION suivante d’afficher son ancre.
Inversement, pour ne pas ancrer, on précisera [(#ANCRE_PAGINATION|vide)] dans la boucle.
Accés direct à un élément particulier
Pour permettre de donner une url permanente vers un élément précis d’une liste paginée on utilisera &debut_abc=@xxx où « abc » est le nom de la boucle de pagination et « xxx » l’id de l’objet dans la table sur laquelle porte la pagination.
Exemple :
Dans une boucle
<B_pagi>
[<p class="pagination">(#PAGINATION)</p>]
<ul>
<BOUCLE_pagi(ARTICLES) {par titre} {pagination}>
<li>#ID_ARTICLE : #TITRE</li>
</BOUCLE_pagi>
</ul>
</B_pagi>&debut_pagi=10 place la pagination sur la deuxième page (à partir du dixième élément de la liste)
&debut_pagi=@231 place la pagination sur la page qui contient l’id_article « 231 ».
Le nombre total de résultats
Dans une boucle avec le critère {pagination}, #TOTAL_BOUCLE affiche le nombre d’éléments effectivement retournés, c’est-à-dire 10 sur les pages pleines, et 10 ou moins sur la dernière page de résultats.
Pour afficher le nombre d’éléments qui auraient été retournés si le critère {pagination} n’avait pas été là, utilisez la balise #GRAND_TOTAL.
indiquera : « Il y a au total 1578 articles, cette page en affiche 10. »
Changer le pas de la {pagination}
Le nombre standard de 10 éléments par page peut être modifié par un paramètre supplémentaire dans le critère.
Ainsi
<BOUCLE_page (ARTICLES) {pagination 5}>
#TITRE <br />
</BOUCLE_page>retournera les titres de cinq articles à partir de debut_page.
Le paramètre en question peut lui-même être composé comme on le souhaite à partir d’autres balises, notamment #ENV{xx}, ce qui permet de faire un affichage à la demande très complet.
La pagination dans les squelettes inclus
Si votre pagination doit fonctionner dans un squelette inclus, vous devez passer en paramètre de la commande INCLURE la formulation {self=#SELF} ; ceci permet au squelette inclus de se calculer avec la bonne valeur du paramètre debut_xxx, et se justifie qui plus est par un besoin de sécurité (la balise #PAGINATION est en effet calculée à partir de l’URL complète de la page).
Depuis SPIP 1.9 le critère {self=#SELF} sera avantageusement remplacé par le couple {env} {ajax} [1].
Nommer le critère de pagination
Lorsque l’on utilise des squelettes inclus plusieurs fois dans la même page comme :
<BOUCLE_incluse(ARTICLES) {id_rubrique} {par titre}>
<INCLURE{fond=motsgroupe5} {id_article} {ajax} {env}>
</BOUCLE_incluse>et que cet INCLURE possède une pagination (d’où l’utilisation du critère {env}), lorsque vous cliquerez sur une pagination, vous verrez toutes les paginations se modifier en même temps.
Pour éviter celà, il suffit de nommer le critère pagination à l’intérieur du fichier inclu par un nom qui sera différent à chaque inclusion :
<B_groupe5>
#ANCRE_PAGINATION
<BOUCLE_groupe5(MOTS) {id_groupe=5} {pagination 15 #ID_ARTICLE}>
#TITRE
</BOUCLE_groupe5>
<p class="pagination">#PAGINATION</p>
</B_groupe5>On peut aussi vouloir spécifier dès l’appel de l’INCLURE le nom que l’on veut donner au critère pagination :
<INCLURE{fond=page_paginee, env, nom_p=_abc}>
<INCLURE{fond=page_paginee, env, nom_p=_def}>dans page_paginee.html :
<B_a>
#ANCRE_PAGINATION
<BOUCLE_a(ARTICLES) {pagination 25 #ENV{nom_p}}>
#TITRE<br />
</BOUCLE_a>
#PAGINATION
</B_a>Styles de la pagination
La pagination est constituée d’une série de liens, et d’un numéro de page correspondant à la page actuelle doté de la class « .on » : on définira donc les styles pour a et .on pour en personnaliser l’apparence.
Choisir le modèle de pagination
Depuis SPIP 1.9.1, la balise #PAGINATION accepte un paramètre {modele}, qui permet de modifier le résultat de la balise.
Ainsi #PAGINATION{precedent_suivant} affichera des liens vers les pages précédentes et suivantes. Les liens seront les suivants
#PAGINATION{page} affichera quelque chose de la forme suivante
#PAGINATION{page_precedent_suivant} affichera quelquechose comme
Il est possible de définir d’autres modèles de pagination, qui devront s’appeler pagination_modele. On pourra, pour les fabriquer, s’inspirer de ceux livrés de base avec SPIP et situés dans le répertoire prive/modeles/ (jusqu’à la version 1.9.2 de SPIP, ils étaient placés dans dist/modeles/) . Pour plus d’info, lire la documentation sur les modèles.