Classificar os resultados
{par criterio_de_classificacao} indica a ordem de exibição dos resultados. Este critério de classificação corresponde a uma das tags retiradas da base de dados para cada tipo de loop. Por exemplo, pode-se ordenar as matérias {por date} (pela data de publicação), {par date_redac} (pela data de redação) ou {par titre} (pelo título). (Note que, embora as tags estejam em maiúsculas, os critérios de classificação estão em letras minúsculas.)
Caso particular: {par hasard} (sorteado) permite obter uma lista apresentada numa ordem aleatória.
Inverter a classificação Além disso, {inverse} provoca a exibição da classificação em ordem inversa. Por exemplo, {par date} começa pelas matérias mais antigas; com {par date}{inverse} começa a lista de resultados pelas matérias mais recentes.
O critério inverse pode utilizar qualquer tag como parâmetro para variar dinamicamente o sentido da classificação. Por exemplo, é possível escrever: <BOUCLE_exemplo(ARTICLES){par #ENV{tri}}{inverse #ENV{senstri}}>, que permite escolher a coluna de ordenação e o sentido de ordenação pelo URL (&senstri=1 ou &senstri=0)
Classificar pelo número. Ao classificar por um elemento de texto (por exemplo, titre), a classificação é feita por ordem alfabética. No entanto, para forçar uma ordem de apresentação, pode-se indicar um número antes do título, por exemplo: «1. O meu primeiro artigo», «2. Segundo artigo», «3. Terceiro...» etc; numa classificação alfabética, a ordem destes elementos daria a série “1, 10, 11, 2, 3...”. Para restabelecer a classificação de acordo com os números, pode-se usar o critério:
{par num critère}
Por exemplo:
<BOUCLE_materias(ARTICLES){id_rubrique}{par date}{inverse}>
…exibe as matérias de uma seção por ordem cronológica inversa (mais recentes no início, mais antigas no final) e:
<BOUCLE_materias(ARTICLES){id_rubrique}{par titre}>
…exibe segunda a ordem alfabética dos títulos; finalmente:
<BOUCLE_materias(ARTICLES){id_rubrique}{par num titre}>
…exibe segundo a ordem dos números dos títulos.
<BOUCLE_articles(ARTICLES){id_rubrique}{par multi titre}>
No contexto de um site multilingue, o critério {par multi critério} permite classificar alfabeticamente em cada idioma. Sem adicionar "multi", o loop devolve a mesma ordenação para cada idioma.
Classificar por vários critérios pode-se classificar por vários critérios:
{par critério1, critério2}. As ordens de classificação consecutivas são indicadas assim. Os resultados serão primeiro ordenados pelo critério1 e depois pelo critério2 para resultados com o mesmo critério1. Pode especificar quantos critérios forem necessários.
Por exemplo {par date, titre} ordenará os resultados por date (data de publicação) e os resultados com a mesma date serão ordenados pelo titre (título).
Vários critérios {par ...} podem ser especificados para um loop para atingir o mesmo resultado. Por exemplo: {par date} {par titre} é equivalente ao exemplo anterior.
Nota: Quando se usam vários critérios de classificação, o critério{inverse}aplica-se apenas ao critério de classificação colocado imediatamente antes deste.A notação
{!par ...}que inverte um critério de ordenação em particular. Por exemplo:{!par date} {par num titre}ordena por date decrescente e por número crescente no titre para os resultados que tenham a mesma date.
{par_ordre_liste campo, #LISTE} (após SPIP 4.1)
Permite ordenar explicitamente os resultados por um campo.
Opcionalmente, pode ser combinado com o critério {… IN …}, eles têm escopos diferentes:
{… IN …} é usado principalmente para seleccionar conteúdos, a ordem nem sempre é preservada.
par_ordre_liste campo … serve para ordenar a seleção de forma fiável.
Pode ser também combinado com outros {par…} na ordem que se quiser.
O exemplo seguinte seleciona todas as matérias e classifica-as numa ordem predefinida. As matérias não presentes na lista serão ordenadas após:
<BOUCLE_materias(ARTICLES) {par_ordre_liste id_article, #LISTE{5,15,10}}>
O exemplo a seguir faz a mesma coisa, mas limitada às três matérias ordenadas:
<BOUCLE_materias(ARTICLES) {id_article IN 5,10,15} {par_ordre_liste id_article, #LISTE{5,15,10}}>
Comparações, igualdades
{critério < valor}
Comparação com um valor fixo (pode ser utilizado «>», «<», «=», «>=», «<=». Todos os critérios de classificação (conforme retirados da base de dados) também podem ser usados para limitar o número de resultados.
O valor à direita do operador pode ser:
- Um valor constante fixo no template. Por exemplo:
<BOUCLE_mat(ARTICLES){id_article=5}>
…exibe a matéria de número 5 (útil para destacar uma matéria específica na página inicial).
<BOUCLE_mat(ARTICLES){id_secteur=2}>
…exibe as matérias do setor número 2.
- Uma tag disponível no contexto do loop. Por exemplo:
<BOUCLE_mat(ARTICLES){id_article=5}>
<BOUCLE_titulo(ARTICLES) {titre=#TITRE}>
...
</BOUCLE_titulo>
</BOUCLE_mat>
…serve para encontrar as matérias que têm o mesmo título que a matéria 5.
Atenção: Só pode ser usada uma tag simples. Não é permitido filtrá-la ou usar código opcional.Especialmente, se quiser usar a tag #ENV — ou qualquer outra tag que aceite parâmetros —, deve-se usar a notação:
{titre = #ENV{titre}}et pas:{titre = [(#ENV{titre})]}.
Expressões regulares:
Muito potente (mas claramente mais complexa de manipular), o termo de comparação «==» introduz uma comparação segundo uma expressão regular. Por exemplo:
<BOUCLE_mat(ARTICLES){titre==^[aA]}>
…seleciona as matérias cujo título começa por «a» ou «A».
Negação:
Pode-se usar a notação {xxx != yyy} e {xxx !== yyy}, o ! correspondendo à negação (operador lógico NOT).
<BOUCLE_mat(ARTICLES){id_secteur != 2}>
…seleciona as matérias que não pertencem ao setor numero 2.
<BOUCLE_mat(ARTICLES){titre!==^[aA]}>
…seleciona as matérias cujo título não começa por «a» ou «A».
Exibição em função da data
Para facilitar a comparação entre datas, criou-se alguns critérios:
- age e age_redac correspondem respectivamente à idade da publicação e da primeira publicação de uma matéria, em dias: {age<30} seleciona os elementos publicados há um mês;
- os critérios mois, mois_redac, annee, annee_redac permitem comparar com valores fixos ({annee<=2000} para os elementos publicados antes do fim do ano 2000).
Pode-se combinar vários desses critérios para realizar seleções muito exatas. Por exemplo:
<BOUCLE_mat(ARTICLES){id_secteur=2}{id_rubrique!=3}{age<30}>
…exibe as matérias do setor 2, excluindo as da seção 3, publicadas há menos de 30 dias.
Dica. O critério age (idade) é muito útil para exibir matérias ou notas cuja data se situe «no futuro», com valores negativos (desde que tenha seleccionado, na configuração do SPIP, a opção «Publicar matérias pós-datadas»). Por exemplo, este critério permite destacar eventos futuros: {idade<0} seleciona matérias ou notas cuja data é no futuro («depois» de hoje)...
Idade relativa a uma data fixa. O critério age é calculado em relação à data de hoje (portanto, {idade<30} corresponde a matérias publicadas há menos de um mês em relação a hoje). O critério age_relatif (idade relativa) compara a data de uma matéria ou nota com uma data «atual»; por exemplo, dentro de um loop ARTICLES, já conhecemos a data para cada resultado do loop, pelo que podemos selecionar em relação a essa data (e não mais em relação ao dia de hoje).
Por exemplo:
<BOUCLE_materia_principal(ARTICLES){id_article}>
<h1>#TITRE</h1>
<BOUCLE_seguinte(ARTICLES){id_rubrique}{age_relatif<=0}{exclus}{par date}{0,1}>
Matéria seguinte: #TITRE
</BOUCLE_seguinte>
</BOUCLE_materia_principal>
O BOUCLE_seguinte exibe uma única matéria da mesma seção, classificada por data, em que a data de publicação é inferior ou igual à data da «materia_principal»; ou seja, a matéria da mesma seção publicado após a matéria principal.
Mais informações sobre o uso das datas encontram-se na matéria sobre «A gestão das datas».
Exibição de uma parte dos resultados
- {branche} (ramo) limita os resultados — para os loops contendo um #ID_RUBRIQUE — ao ramo atual (a seção corrente e suas subseções). Por exemplo:
<BOUCLE_matérias(ARTICLES) {branche}>
…retornará todas as matérias da seção corrente e as das suas subseções,
<BOUCLE_matérias(ARTICLES) {!branche}>
…retornará todas as matérias que não pertencem à seção corrente oou às suas subseções,
Pode-se usar o critério {branche?} opcional para o aplicar apenas se uma seção for selecionada no contexto (um loop envolvente ou o URL fornecer um id_rubrique).
Par exemple:
<BOUCLE_materias(ARTICLES) {branche?}>
retornará todas as matérias da seção corrente e das suas subseções se houver um id_rubrique no contexto, senão, todas as matérias do site.
- {doublons} (duplicados) ou {unique} (único) (estes dois critérios são rigorosamente idênticos)
bloqueiam a exibição de resultados já exibidos em outros loops que também usem este critério.
- {doublons xxxx} pode-se ter vários conjuntos de critérios {doublons} independentes. Os loops com {doublons vermelho} não terão nenhuma influência sobre os loops com {doublons azul} como critério.
- {exclus} (excluído) remove do resultado o elemento (matéria, nota, seção etc.) no qual já se encontra. Por exemplo, ao exibir matérias da mesma secção, não queremos exibir um link para a matéria em que já nos encontramos.
- {xxxxINa,b,c,d} limita a exibição aos resultados contendo o critério xxxx igual a a, b, c ou d. Os resultados são classificados na ordem indicada (a menos que seja explicitamente solicitado por outro critério de classificação). Também é possívelselecionar strings, por exemplo com {titre IN 'China', 'Japão'}.
As tags são permitidas nos argumentos IN, incluindo a tag ENV, à qual são aplicados filtros de análise para garantir que a consulta SQL será escrita corretamente. Excepcionalmente, o SPIP testará se o argumento ENV designa uma matriz (por exemplo, proveniente de entradas de formulários cujo atributo name termina com []). Se for este o caso, e se os filtros de análise tiverem sido desativados ao adicionar um duplo asterisco a essa tag, cada elemento da matriz será considerado como um argumento de IN, com o SPIP aplicando os filtros de segurança em cada um deles.
O template do plugin-dist fórum inc-forum_previsu.html fornece um exemplo de uso com um loop MOTS tendo o critério {id_mot IN #ENV**{ajouter_mot}}: este loop apenas selecciona apenas as palavras-chave pertencentes a um conjunto indicado dinamicamente. Aqui, este conjunto terá sido construído sob a forma deste plug-in-dist inc-choix_mots.html, que usa os atributos "name=ajout_mot[]".
- {a, b} onde a e b são números. Este critério permite limitar o número de resultados. a o resultado a partir do qual se inicia a exibição (atenção , o primeiro resultado é numerado como 0 - zero); b indica o número de resultados exibidos.
Por exemplo {0, 10} exibe os dez primeiros resultados; {4, 2} exibe os dois resultados a partir do quinto (inclusive).
- {debut_xxx, b} (início) é uma variante mais elaborada do anterior. Permite começar a limitar os resultados com uma variável passada no URL (esta variável substitui o a que foi indicado anteriormente). É uma operação um pouco complicada, que felizmente não precisa de utilizar com muita frequência.
A variável passada no URL deve começar por debut_xxx< (onde xxx é uma palavra escolhida pelo webmaster). Assim, para uma página cujo URL é:
spip.php?page=petition&id_article=13&debut_signatures=200 com um template (petition.html) contendo, por exemplo:
<BOUCLE_assinaturas(SIGNATURES){id_article}{debut_signatures,100}>
obteremos a lista de 100 assinaturas a partir da 201ª [lembrete].
Com o URL: spip.php?page=petition&id_article=13&debut_signatures=300 obteremos a lista das 100 assinaturas a partir da 301ª [lembrete].
- {a, n-b} é uma variante de {a, b} que limita a exibição em função do número de resultados no loop. a é o resultado a partir do qual se começa a fazer a exibição; b indica o número de resultados não exibir no final do loop.
{0, n-10} exibirá todos os resultados do loop menos os 10 últimos.
{5, n} exibirá os resultados do 6º ao último.
Atenção:
se "a" e "b" devem ser substituídos por números, é a letra "n" que deve ser utilizada quando necessário.
- {n-a, b} é a contrapartida de {a, n-b}. Limitamos os resultados a b iniciando a exibição no resultado aº antes do final do loop.
Por exemplo: {n-20,10} exibirá 10 resultados a partir do 20º resultado antes do final do loop.
Atenção:
os critérios {a, n}, {a, n-b} e {n-a, b} não funcionam se forem usados com o critério {pagination} e retornam resultados incoerentes!
- {a/b} onde a e b são números. Este critério permite exibir uma parte a (proporcionalmente) dos resultados em função de um número de «partes» b.
Por exemplo: {1/3} apresenta o primeiro terço dos resultados. Este critério é especialmente útil para apresentar listas em múltiplas colunas. Para obter uma apresentação de duas colunas, basta criar um primeiro ciclo, apresentado na primeira coluna, com o critério {1/2} (a primeira metade dos resultados), depois um segundo ciclo na segunda coluna, com o critério {2/2} (a segunda metade dos resultados).
Atenção. O uso do critério {doublons} com este critério é perigoso. Por exemplo:#
<BOUCLE_prim(ARTICLES){id_rubrique}{1/2}{doublons}>
<li> #TITRE
</BOUCLE_prim>
<BOUCLE_seg(ARTICLES){id_rubrique}{2/2}{doublons}>
<li> #TITRE
</BOUCLE_seg>
…não exibirá todas as matérias da seção! Por exemplo, imaginemos que existe um total de 20 matérias na nossa seção. O BOUCLE_prim exibirá a primeira metade das matérias, ou seja, as primeiros 10, e bloqueará (por causa dos {doublons}) a sua reutilização. O BOUCLE_seg irá recuperar a segunda metade dos artigos desta secção que ainda não foram apresentados pelo BOUCLE_prim; portanto, metade das 10 matérias seguintes, ou seja, as últimas 5 matérias da seção. Você “perdeu” assim 5 itens na operação...
Exibição entre os resultados
{"inter"} permite indicar um código HTML (aqui, inter) inserido entre os resultados do loop como separador. Por exemplo, para separar uma lista de autores por vírgulas, indica-se:
<BOUCLE_autores(AUTEURS){id_article}{", "}>
Diversos
{logo} permite só selecionar matérias (ou seções etc) que disponham de um logo.
O critério inverso {!logo} lista os objetos que não possuem logo.
Também funciona no loop (HIERARCHIE).