Classer les résultats
{par critère_de_classement} indique l’ordre de présentation des résultats. Ce critère de classement correspond à l’une des balises tirées de la base de données pour chaque type de boucle. Par exemple, on pourra classer les articles {par date}, {par date_redac} ou {par titre}. (Notez que, si les balises sont en majuscules, les critères de classement sont en minuscules.)
Cas particulier : {par hasard} permet d’obtenir une liste présentée dans un ordre aléatoire.
Inverser le classement. De plus, {inverse} provoque l’affichage du classement inversé. Par exemple {par date} commence par les articles les plus anciens ; avec {par date}{inverse} on commence la liste avec les articles les plus récents.
Le critère inverse peut prendre en paramètre n’importe quelle balise pour varier dynamiquement le sens du tri. Par exemple, il est possible d’écrire : <BOUCLE_exemple(ARTICLES){par #ENV{tri}}{inverse #ENV{senstri}}>, ce qui permet de choisir la colonne de tri et le sens du tri par l’url (&senstri=1 ou &senstri=0)
Classer par numéro. Lorsqu’on réalise le classement selon un élément de texte (par exemple le titre), le classement est réalisé par ordre alphabétique. Cependant, pour forcer un ordre d’affichage, on peut indiquer un numéro devant le titre, par exemple : « 1. Mon premier article », « 2. Deuxième article », « 3. Troisième... », etc ; avec un classement alphabétique, le classement de ces éléments donnerait la série « 1, 10, 11, 2, 3... ». Pour rétablir le classement selon les numéros, on peut utiliser le critère :
{par num critère}
Par exemple :
<BOUCLE_articles(ARTICLES){id_rubrique}{par date}{inverse}>
…affiche les articles d’une rubrique classés selon l’ordre chronologique inversé (les plus récents au début, les plus anciens à la fin), et :
<BOUCLE_articles(ARTICLES){id_rubrique}{par titre}>
…les affiche selon l’ordre alphabétique de leur titre ; enfin :
<BOUCLE_articles(ARTICLES){id_rubrique}{par num titre}>
…les affiche selon l’ordre du numéro de leur titre.
<BOUCLE_articles(ARTICLES){id_rubrique}{par multi titre}>
Dans le cadre d’un site multilingue le critère {par multi critère} permet de trier par ordre alphabétique dans chaque langue. Sans l’ajout de "multi" la boucle renvoie le même classement pour chaque langue.
Classer selon plusieurs critères on peut classer selon plusieurs critères :
{par critère1, critère2}. On indique ainsi des ordres de classement consécutifs. Les résultats seront d’abord triés selon le critère1, puis le critère2 pour les résultats ayant le même critère1. On peut spécifier autant de critères que nécessaire.
Par exemple {par date, titre} triera les résultats par date puis les résultats ayant la même date seront triés par titre.
On peut spécifier plusieurs critères {par ...} pour une boucle pour arriver au même résultat. Par exemple : {par date} {par titre} est équivalent à l’exemple précédent.
Remarque : Quand on utilise plusieurs critères de tri, le critère{inverse}ne s’applique qu’au critère de tri placé juste avant.La notation
{!par ...}qui inverse un critère de tri en particulier. Par exemple :{!par date} {par num titre}trie par date décroissantes puis par numéros croissants dans le titre pour les résultats ayant la même date.
{par_ordre_liste champ, #LISTE} (depuis SPIP 4.1)
Permet d’ordonner explicitement les résultats selon un champ.
Il peut optionnellement être combiné avec le critère{… IN …}, ils ont des portées différentes :
{… IN …} sert avant tout à sélectionner des contenus, l’ordre n’est pas tout le temps conservé.
par_ordre_liste champ … sert à ordonner la sélection de façon fiable.
Il peut également être combiné avec d’autres {par…}dans l’ordre que l’on veut
L’exemple suivant sélectionne tous les articles et les ordonne dans un ordre prédéfini. Les articles non présents dans la liste seront classés après :
<BOUCLE_articles(ARTICLES) {par_ordre_liste id_article, #LISTE{5,15,10}}>
L’exemple suivant fait la même chose, mais limité aux 3 articles ordonnés :
<BOUCLE_articles(ARTICLES) {id_article IN 5,10,15} {par_ordre_liste id_article, #LISTE{5,15,10}}>
Comparaisons, égalités
{critère < valeur}
Comparaison avec une valeur fixée (on peut utiliser « > », « < », « = », « >= », « <= ». Tous les critères de classement (tels que tirés de la base de données) peuvent également être utilisés pour limiter le nombre de résultats.
La valeur à droite de l’opérateur peut être :
- Une valeur constante fixée dans le squelette. Par exemple :
<BOUCLE_art(ARTICLES){id_article=5}>
…affiche l’article dont le numéro est 5 (utile pour mettre en vedette un article précis sur la page d’accueil).
<BOUCLE_art(ARTICLES){id_secteur=2}>
…affiche les articles du secteur numéro 2.
- Une balise disponible dans le contexte de la boucle. Par exemple :
<BOUCLE_art(ARTICLES){id_article=5}>
<BOUCLE_titre(ARTICLES) {titre=#TITRE}>
...
</BOUCLE_titre>
</BOUCLE_art>
…sert à trouver les articles qui ont le même titre que l’article 5.
Attention : On ne peut utiliser qu’une balise simple. Il n’est pas permis de la filtrer ou de mettre du code optionnel.Spécialement, si on veut utiliser la balise #ENV — ou tout autre balise prenant des paramètres —, on doit utiliser la notation :
{titre = #ENV{titre}}et pas :{titre = [(#ENV{titre})]}.
Expressions régulières :
Très puissant (mais nettement plus complexe à manipuler), le terme de comparaison « == » introduit une comparaison selon une expression régulière. Par exemple :
<BOUCLE_art(ARTICLES){titre==^[aA]}>
…sélectionne les articles dont le titre commence par « a » ou « A ».
Négation :
On peut utiliser la notation {xxx != yyy} et {xxx !== yyy}, le ! correspondant à la négation (opérateur logique NOT).
<BOUCLE_art(ARTICLES){id_secteur != 2}>
…sélectionne les articles qui n’appartiennent pas au secteur numéro 2.
<BOUCLE_art(ARTICLES){titre!==^[aA]}>
…sélectionne les articles dont le titre ne commence pas par « a » ou « A ».
Affichage en fonction de la date
Pour faciliter l’utilisation des comparaisons sur les dates, on a ajouté des critères :
- age et age_redac correspondent respectivement à l’ancienneté de la publication et de la première publication d’un article, en jours : {age<30} sélectionne les éléments publiés depuis un mois ;
- les critères mois, mois_redac, annee, annee_redac permettent de comparer avec des valeurs fixes ({annee<=2000} pour les éléments publiés avant la fin de l’année 2000).
On peut combiner plusieurs de ces critères pour effectuer des sélections très précises. Par exemple :
<BOUCLE_art(ARTICLES){id_secteur=2}{id_rubrique!=3}{age<30}>
…affiche les articles du secteur 2, à l’exclusion de ceux de la rubrique 3, et publiés depuis moins de 30 jours.
Astuce. Le critère age est très pratique pour afficher les articles ou les brèves dont la date est située « dans le futur », avec des valeurs négatives (à condition d’avoir sélectionné, dans la Configuration précise du site, l’option « Publier les articles post-datés »). Par exemple, ce critère permet de mettre en valeur des événements futurs. {age<0} sélectionne les articles ou les brèves dont la date est située dans le futur (« après » aujourd’hui)...
Âge par rapport à une date fixée. Le critère age est calculé par rapport à la date d’aujourd’hui (ainsi {age<30} correspond aux articles publiés depuis moins d’un mois par rapport à aujourd’hui). Le critère age_relatif compare la date d’un article ou d’une brève à une date « courante » ; par exemple, à l’intérieur d’une boucle ARTICLES, on connaît déjà une date pour chaque résultat de la boucle, on peut donc sélectionner par rapport à cette date (et non plus par rapport à aujourd’hui).
Par exemple :
<BOUCLE_article_principal(ARTICLES){id_article}>
<h1>#TITRE</h1>
<BOUCLE_suivant(ARTICLES){id_rubrique}{age_relatif<=0}{exclus}{par date}{0,1}>
Article suivant: #TITRE
</BOUCLE_suivant>
</BOUCLE_article_principal>
la BOUCLE_suivant affiche un seul article de la même rubrique, classé par date, dont la date de publication est inférieure ou égale à la date de l’« article_principal » ; c’est-à-dire l’article de la même rubrique publié après l’article principal.
De plus amples informations sur l’utilisation des dates se trouvent dans l’article sur « La gestion des dates ».
Affichage d’une partie des résultats
- {branche} limite les résultats — pour des boucles ayant un #ID_RUBRIQUE — à la branche actuelle (la rubrique actuelle et ses sous-rubriques). Par exemple :
<BOUCLE_articles(ARTICLES) {branche}>
…retournera tous les articles de la rubrique actuelle et de ces sous-rubriques,
<BOUCLE_articles(ARTICLES) {!branche}>
…retournera tous les articles qui ne sont pas dans la rubrique actuelle ou ses sous-rubriques,
On peut utiliser le critère {branche?} optionnel pour ne l’appliquer que si une rubrique est sélectionnée dans le contexte (une boucle englobante ou l’url fournie un id_rubrique).
Par exemple :
<BOUCLE_articles(ARTICLES) {branche?}>
retournera tous les articles de la rubrique actuelle et de ces sous-rubriques si il y a un id_rubrique dans le contexte, sinon, tous les articles du site.
- {doublons} ou {unique} (ces deux critères sont rigoureusement identiques) permettent d’interdire l’affichage des résultats déjà affichés dans d’autres boucles utilisant ce critère.
- {doublons xxxx} on peut avoir plusieurs jeux de critères {doublons} indépendants. Les boucles ayant {doublons rouge} n’auront aucune incidence sur les boucles ayant {doublons bleu} comme critère.
- {exclus} permet d’exclure du résultat l’élément (article, brève, rubrique, etc.) dans lequel on se trouve déjà. Par exemple, lorsque l’on affiche les articles contenus dans la même rubrique, on ne veut pas afficher un lien vers l’article dans lequel on se trouve déjà.
- {xxxxINa,b,c,d} limite l’affichage aux résultats ayant le critère xxxx égal à a, b, c ou d. Les résultats sont triés dans l’ordre indiqué (sauf demande explicite d’un autre critère de tri). Il est aussi possible de sélectionner des chaînes de caractères, par exemple avec {titre IN 'Chine', 'Japon'}.
Les balises sont admises dans les arguments de IN, et notamment la balise ENV, à laquelle sont appliqués les filtres d’analyse pour assurer que la requête SQL sera bien écrite. De manière dérogatoire, SPIP testera si l’argument de ENV désigne un tableau (venant par exemple de saisies de formulaire dont l’attribut name se termine par []). Si c’est le cas, et si les filtres d’analyse ont été désactivés en suffixant cette balise par une double étoile, alors chaque élément du tableau sera considéré comme argument de IN, SPIP appliquant les filtres de sécurité sur chacun d’eux.
Le squelette du plug-in-dist forum inc-forum_previsu.html fournit un exemple d’utilisation avec une boucle MOTS ayant le critère {id_mot IN #ENV**{ajouter_mot}} : cette boucle sélectionne seulement les mots-clés appartenant à un ensemble indiqué dynamiquement. Ici, cet ensemble aura été construit par le formulaire de ce plug-in-dist inc-choix_mots.html, qui utilise des attributs "name=ajouter_mot[]".
- {a, b} où a et b sont des nombres. Ce critère permet de limiter le nombre de résultats. a indique le résultat à partir duquel on commence l’affichage (attention, le premier résultat est numéroté 0 - zéro) ; b indique le nombre de résultats affichés.
Par exemple {0, 10} affiche les dix premiers résultats ; {4, 2}affiche les deux résultats à partir du cinquième (inclus).
- {debut_xxx, b} est une variante très élaborée de la précédente. Elle permet de faire commencer la limitation des résultats par une variable passée dans l’URL (cette variable remplace ainsi le a que l’on indiquait précédemment). C’est un fonctionnement un peu compliqué, que fort heureusement on n’a pas besoin d’utiliser trop souvent.
La variable passée dans l’URL commence forcément par debut_xxx< (où xxx est un mot choisi par le webmestre) . Ainsi, pour une page dont l’URL est :
spip.php?page=petition&id_article=13&debut_signatures=200 avec un squelette (petition.html) contenant par exemple :
<BOUCLE_signatures(SIGNATURES){id_article}{debut_signatures,100}>
on obtiendra la liste des 100 signatures à partir de la 201-ième [rappel].
Avec l’URL : spip.php?page=petition&id_article=13&debut_signatures=300 on obtient la liste des 100 signatures à partir de la 301-ième [rappel].
- {a, n-b} est une variante de {a, b} qui limite l’affichage en fonction du nombre de résultats dans la boucle. a est le résultat à partir duquel commencer à faire l’affichage ; b indique le nombre de résultats à ne pas afficher à la fin de la boucle.
{0, n-10} affichera tous les résultats de la boucle sauf les 10 derniers.
{5, n} affichera les résultats du 6ème au dernier.
Attention :
si « a » et « b » sont à remplacer par des nombres, c’est bien la lettre « n » qu’il faut utiliser quand nécessaire.
- {n-a, b} est le pendant de {a, n-b}. On limite à b résultats en commençant l’affichage au ae résultat avant la fin de la boucle.
Par exemple : {n-20,10} affichera 10 résultats en partant du 20e résultat avant la fin de la boucle.
Attention :
les critères {a, n}, {a, n-b} et {n-a, b} ne fonctionnent pas s’ils sont utilisés avec le critère {pagination} et retournent des résultats inconséquents !
- {a/b} où a et b sont des chiffres. Ce critère permet d’afficher une partie a (proportionnellement) des résultats en fonction d’un nombre de « tranches » b.
Par exemple : {1/3} affiche le premier tiers des résultats. Ce critère est surtout utile pour présenter des listes sur plusieurs colonnes. Pour obtenir un affichage sur deux colonnes, il suffit de créer une première boucle, affichée dans une case de tableau, avec le critère {1/2} (la première moitié des résultats), puis une seconde boucle dans une seconde case, avec le critère {2/2} (la seconde moitié des résultats).
Attention. L’utilisation du critère {doublons}
avec ce critère est périlleuse. Par exemple :
<BOUCLE_prem(ARTICLES){id_rubrique}{1/2}{doublons}>
<li> #TITRE
</BOUCLE_prem>
<BOUCLE_deux(ARTICLES){id_rubrique}{2/2}{doublons}>
<li> #TITRE
</BOUCLE_deux>
…n’affichera pas tous les articles de la rubrique ! Imaginons par exemple qu’il y ait au total 20 articles dans notre rubrique. La BOUCLE_prem va afficher la première moitié des articles, c’est-à-dire les 10 premiers, et interdire (à cause de {doublons}) de les réutiliser. La BOUCLE_deux, elle, va récupérer la deuxième moitié des articles de cette rubrique qui n’ont pas encore été affichés par la BOUCLE_prem ; donc, la moitié des 10 articles suivants, c’est-à-dire les 5 derniers articles de la rubrique. Vous avez donc « perdu » 5 articles dans l’opération...
Affichage entre les résultats
{"inter"} permet d’indiquer un code HTML (ici, inter) inséré entre les résultats de la boucle. Par exemple, pour séparer une liste d’auteurs par une virgule, on indiquera :
<BOUCLE_auteurs(AUTEURS){id_article}{", "}>
Divers
{logo} permet de ne sélectionner que les articles (ou rubriques, etc) qui disposent d’un logo.
Le critère inverse {!logo} liste les objets qui n’ont pas de logo.
Il fonctionne aussi dans la boucle (HIERARCHIE).