A paginação permite distribuir resultados muito numerosos por várias páginas.
O SPIP fornece um sistema simplificado de paginação dos resultados de um loop.
Sintaxe básica
Na forma mais simples, este sistema compõe-se de um critério e de uma tag:
- o critério
{pagination}inclui-se no loop a paginar; - a tag
#PAGINATION, inserida numa das partes opcionais («anterior» ou « posterior») do loop, exibe a «paginação».
<B_pagina>
[<nav role="navigation" class="pagination">(#PAGINATION)</nav>]
<ul>
<BOUCLE_pagina(ARTICLES){par date}{pagination}>
<li>#TITRE</li>
</BOUCLE_pagina>
</ul>
</B_pagina>
Se o site tiver 90 matérias publicadas, este loop exibirá a lista das dez matérias mais antigas, adicionada de links que levam às dez matérias seguintes, anteriores etc. Estes links são numerados como a seguir:
O número a partir do qual os resultados são exibidos é passado no URL por um parâmetro {debut_page=x} com o mesmo nome (aqui, «pagina») do loop a que diz respeito. (Este parâmetro pode ser utilizado noutro loop através do critério clássico {debut_page,10}.)
Nota: o número total de links exibidos é limitado: reticências permitem, quando apropriado, saltar diretamente para o fim da lista, ou de voltar à página inicial.
Âncoras de paginação
A tag #PAGINATION inclui uma Âncora HTML que permite ao navegador exibir diretamente a parte da página que está paginada; todavia, se desejar inserir os links de paginação abaixo da lista de matérias, é preciso colocar a âncora sobre a lista.
A tag #ANCRE_PAGINATION devolve precisamente a âncora em questão e impede a tag #PAGINATION seguinte de exibir a sua âncora.
<B_pagina>
#ANCRE_PAGINATION
<ul>
<BOUCLE_pagina(ARTICLES){par date}{pagination}>
<li>#TITRE</li>
</BOUCLE_pagina>
</ul>
[<nav role="navigation" class="pagination">(#PAGINATION)</nav>]
</B_pagina>
Inversamente, para não ancorar, deve-se especificar [(#ANCRE_PAGINATION|vide)] no loop.
Acesso direto a um elemento específico
Para permitir dar um URL permanente a um elemento específico de uma lista paginada, deve-se usar &debut_abc=@xxx onde «abc» é o nome do loop de paginação e «xxx» o id do objeto na tabela que está a ser paginada.
Exemplo: Num loop
<B_pagi>
[<nav role="navigation" class="pagination">(#PAGINATION)</nav>]
<ul>
<BOUCLE_pagi(ARTICLES){par titre}{pagination}>
<li>#ID_ARTICLE : #TITRE</li>
</BOUCLE_pagi>
</ul>
</B_pagi>
&debut_pagi=10 posiciona a paginação na segunda página (a partir do décimo elemento da lista)&debut_pagi=@231 posiciona a paginação na página que contém o id_article «231».
O número total de resultados
Num loop com o critério {pagination}, #TOTAL_BOUCLE exibe o número de elementos efetivamente devolvidos, ou seja, 10 nas páginas plenas, e 10 ou menos na última página de resultados.
Para exibir o número de elementos que seriam devolvidos se o critério {pagination} não estivesse presente, usa-se a tag #GRAND_TOTAL.
<B_paginacao>
#ANCRE_PAGINATION
<BOUCLE_paginacao (ARTICLES) {pagination}>
#TITRE <br>
</BOUCLE_paginacao>
Há um total de #GRAND_TOTAL matérias, esta página exibe #TOTAL_BOUCLE
</B_paginacao>
Indicará: «Há um total de 1578 matérias, esta página exibe 10.»
Alterar o passo da {pagination}
O número padrão de 10 elementos por página pode ser alterado por um parâmetro suplementar no critério.
Assim
<BOUCLE_pagina(ARTICLES){pagination 5}>
#TITRE<br>
</BOUCLE_pagina>
devolverá os títulos de cinco matérias a partir de debut_page.
O parâmetro em questão pode ser composto como se quiser a partir de outras tags, especialmente #ENV{xx}, o que permite criar uma exibição personalizada bem completa.
A paginação nos templates incluídos
Se a sua paginação precisa funcionar num template incluído, você deve passar como parâmetro do comando INCLURE a instrução {ajax, env}; isto permite ao template incluído calcular o valor correto do parâmetro debut_xxx, e ainda justifica-se por uma questão de segurança (a tag #PAGINATION é com efeito calcular a partir do URL completo da página).
Nomear o critério de paginação
Quando se usa templates incluídos várias vezes na mesma página, como:
<BOUCLE_incluso(ARTICLES){id_rubrique}{par titre}>
<INCLURE{fond=motsgroupe5,id_article,ajax,env}>
</BOUCLE_incluso>
e esse INCLURE possui uma paginação (daí o uso do critério {env}), ao se clicar em uma paginação, todas as outras paginações alteram-se ao mesmo tempo.
Para evitar isso, basta nomear o critério de paginação no ficheiro incluído com um nome que será diferente a cada inclusão:
<B_grupo5>
#ANCRE_PAGINATION
<BOUCLE_grupo5(MOTS){id_groupe=5}{pagination 15, #ID_ARTICLE}>
#TITRE<br>
</BOUCLE_grupo5>
[<nav role="navigation" class="pagination">(#PAGINATION)</nav>]
</B_grupo5>
Pode-se também querer especificar o nome que se quer dar ao critério de paginação a partir da chamada do INCLURE:
<INCLURE{fond=pagina_paginada, env, nom_p=_abc}>
<INCLURE{fond=pagina_paginada, env, nom_p=_def}>
na pagina_paginada.html:
<B_a>
#ANCRE_PAGINATION
<BOUCLE_a(ARTICLES){pagination 25, #ENV{nom_p}}>
#TITRE<br>
</BOUCLE_a>
[<nav role="navigation" class="pagination">(#PAGINATION)</nav>]
</B_a>
Estilos da paginação
A paginação constitui-se de uma série de links e de um número de página correspondente à página atual associada à classe «.on»: define-se então os estilos para a e .on para personalizar a aparência.
Escolher o modelo de paginação
A tag #PAGINATION aceita um parâmetro {modele}, que permite alterar o resultado da tag.
#PAGINATION{precedent_suivant} exibirá os links para as páginas precedentes e seguintes. Os links serão os seguintes
#PAGINATION{page} exibirá algo como a seguir
#PAGINATION{page_precedent_suivant} exibirá algo como
página precedente 1 | 2 | 3 | 4 | 5 | 6 | página seguinte
#PAGINATION{prive} exibirá algo como
0 | 10 | 20 | 30 | Exibir tudo
É possível definir outros modelos de paginação no diretório modeles/ do seu conjunto de templates. Eles deverão chamar-se pagination_nomedomodelo. Pode inspirar-se nos modelos fornecidos pelo SPIP, situados no diretório prive/modeles/
Personalizar o modelo de paginação
Cada modelo possui parâmetros que podem ser personalizados.
Por exemplo, #PAGINATION{page_precedent_suivant} exibe por padrão:
página precedente 1 | 2 | 3 | 4 | 5 | 6 | página seguinte
#PAGINATION{page_precedent_suivant, label_precedent=<, label_suivant=>} exibe:
Configurar o endereço dos links de #PAGINATION
É possível especificar que URL deve servir de base para os links gerados pela tag #PAGINATION.
Por exemplo, isso permite, se necessário, limpar uma variável de URL indesejável:
#PAGINATION{prive,self=#SELF|parametre_url{...}}
Configurar o número de links
Após o SPIP 4.0, os diferentes modelos de paginação aceitam um parâmetro nombre_liens_max que, passado na tag #PAGINATION permite definir o número máximo de links de paginação exibido pelo modelo. Pode-se igualmente empregar a constante _PAGINATION_NOMBRE_LIENS_MAX.
Definir um novo modelo de paginação
É possível sobrescrever um modelo de paginação existente ou definir um novo no diretório modeles do seu template ou plugin. Para isso, crie o ficheiro desse novo modelo com o nopme desejado. Assim, o modelo ligeiro.html, permite-lhe usar #PAGINATION{ligeiro} nos seus templates.
Os modelos de paginação recebem variáveis de ambiente das quais podem fazer uso: page_courante, nombre_pages, bloc_ancre. Também podem utilizar o filtro |bornes_pagination, que devolve os limites da paginação criada.
Para facilitar o seu trabalho, você pode começar por tomar o código de um modelo de paginação fornecido pelo SPIP e adaptá-lo às suas necessidades.
Não registar no histórico do navegador
Para isso, é precisso associar a classe CSS nohistory ao link ajax (ver `ajax` para os `inclure`) :
[<nav role="navigation" class="pagination">
(#PAGINATION{precedent_suivant}|replace{lien_pagination,lien_pagination nohistory})
</nav>]