uZine 3

Les critères communs à toutes les boucles

l'équipe de SPIP — 2001-05-04T22:00:00Z

Certains critères s'appliquent à (presque) tous les types de boucles. Ce sont des critères destinés à restreindre le nombre de résultats affichés ou à indiquer l'ordre d'affichage. On peut sans difficulté combiner plusieurs de ces critères de sélection.

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.

Classer par numéro. (SPIP 1.3) 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 (remarque : l'option {par num titre} ne fonctionne pas pour les plus anciennes versions de MySQL, antérieures à la version 3.23).

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.

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.

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. (SPIP 1.2) On peut utiliser la notation {xxx != yyy}, le ! correspondant à la négation (opérateur logique NOT).

<BOUCLE_art(ARTICLES){titre!==^[aA]}>

sélectionne les articles dont le titre ne commence pas par « a » ou « A ».

<BOUCLE_art(ARTICLES){id_secteur != 2}>

sélectionne les articles qui n'appartiennent pas au secteur numéro 2.

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éménts 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)...

(SPIP 1.3) Â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.

Affichage d'une partie des résultats

{a,b} où a et b sont des chiffres. 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 (celle 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 :

petition.php3?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 200-ième. Avec l'URL :

petition.php3?id_article=13&debut_signatures=300

on obtient la liste des 100 signatures à partir de la 300-ième.

{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}{", "}>

Les filtres de SPIP

l'équipe de SPIP — 2001-05-02T22:00:00Z

Nous avons vu dans la syntaxe des balises SPIP qu'il était possible de modifier le comportement et l'affichage des balises en leur attribuant des filtres.

[ option avant (#BALISE|filtre1|filtre2|...|filtren) option après ]

Les filtres 1, 2, ..., n sont appliqués successivement à la #BALISE.

Les filtres de mise en page

majuscules fait passer le texte en majuscules. Par rapport à la fonction de PHP, majuscules s'applique également aux lettres accentuées.

justifier fait passer le texte en justification totale (

aligner_droite fait passer le texte en justification à droite (

aligner_gauche fait passer le texte en justification à gauche (

centrer centre le texte (

Les filtres des dates

Les filtres suivants s'appliquent aux dates ((#DATE par exemple).

affdate affiche la date en français, par exemple « 13 janvier 2001 ».

jour affiche le jour (en nombre).

mois affiche le mois (en nombre).

annee affiche l'année.

[SPIP 1.0.2] heures affiche les heures d'une date (les dates fournies par SPIP contiennent non seulement le jour, mais également les horaires).

[SPIP 1.0.2] minutes affiche les minutes d'une date.

[SPIP 1.0.2] secondes affiche les secondes.

nom_jour affiche le nom du jour (lundi, mardi...).

nom_mois affiche le nom du mois (janvier, février...).

saison affiche la saison (hiver, été...).

Filtres de logos

fichier [SPIP 1.4]. Affecté à un logo, ce filtre permet de récupérer directement le nom de fichier correspondant au logo.

||autres filtres Contrairement aux versions précédentes, [SPIP 1.4] permet de passer des filtres « maison » sur les logos : la logique est un peu tordue, car il fallait respecter la compatibilité avec SPIP 1.3. L'analyse se déroule comme suit :

si le premier « filtre » n'est pas un alignement, SPIP considère qu'il s'agit d'un URL et fait un lien du logo vers cette adresse ;
si le premier filtre est un alignement, SPIP considère que le deuxième « filtre » est un URL ;
les filtres suivants sont de vrais filtres au sens habituel (y compris des filtres « maison » déclarés dans mes_fonctions.php3 ;
pour appliquer un filtre quelconque sans mettre d'URL, il faut mettre deux barres. Par exemple :
permet de récupérer le logo dans la variable php $logo, pour traitement ultérieur (voir ci-dessous pour la signification de |texte_script).

Filtres de texte

La plupart de ces filtres ont été introduits dans la version [SPIP 1.4]

liens_ouvrants transforme les liens SPIP qui donnent vers des sites extérieurs en liens de type « popup », qui ouvrent dans une nouvelle fenetre ; c'est l'équivalent du target=blank du HTML. N.B. : les développeurs de SPIP estiment qu'il s'agit en général d'une impolitesse, car les internautes savent très bien s'ils ont envie ou pas d'ouvrir une nouvelle fenêtre - or ce système le leur impose. Mais la demande était trop forte, et nous avons craqué ;-)

supprimer_numero sert à éliminer le numéro d'un titre, si par exemple on veut faire des tris d'articles {par num titre} mais ne pas afficher les numéros (car ils ne servent qu'à ordonner les articles).

PtoBR transforme les sauts de paragraphe en simples passages a la ligne, ce qui permet de « resserrer » une mise en page, par exemple à l'intérieur d'un sommaire

taille_en_octets permet de transformer un nombre d'octets (25678906) en une chaîne de caractères plus explicite (« 24.4 Mo »).

supprimer_tags est une suppression basique et brutale de tous les <...>

textebrut s'apparente au filtre supprimer_tags, mais il agit de manière un peu plus subtile, transformant notamment les paragraphes et en sauts de ligne, et les espaces insécables en espaces simples. Utilisation, par exemple, pour faire un descriptif META à partir du #DESCRIPTIF : []

Filtres techniques

Ces filtres ont été introduits par [SPIP 1.4].

entites_html transforme un texte en entités HTML, que l'on peut donc implanter dans un formulaire, exemple : [(#DESCRIPTIF|entites_html)]

texte_script transforme n'importe quel champ en une chaîne utilisable en PHP ou Javascript en toute securité, exemple : . Attention : utilisez bien le caractère ' et non " : en effet, dans le second cas, si votre texte contient le symbole $, le résultat peut être catastrophique (affichage partiel, affichage d'autre chose, plantage php, etc.).

attribut_html rend une chaîne utilisable sans dommage comme attribut HTML ; par exemple, si l'on veut ajouter un texte de survol au lien normal vers un article, on utilisera

#TITRE.

[SPIP 1.6] introduit le filtre |sinon, qui indique ce qu'il faut afficher si l'élément « filtré » est vide : ainsi [(#TEXTE|sinon{"pas de texte"})] affiche le texte ; si celui-ci est vide, affiche « pas de texte ».

Ajouter ses propres fonctions

Les filtres de SPIP sont des fonctions PHP à une seule variable. Vous pouvez utiliser directement les fonctions habituelles de PHP, mais également créer les vôtres, sur le modèle :

 function mon_filtre($texte){
 $texte = (bidouillages en PHP) ...;
 return $texte;
 }
 ?>

Afin de ne pas avoir à modifier des fichiers de SPIP (qui risqueraient d'être écrasés lors d'une prochaine mise à jour), vous pouvez installer vos fonctions personnelles dans un fichier mes_fonctions.php3 : si SPIP repère un fichier ayant ce nom, il l'inclut automatiquement.

Par exemple, ARNO* a développé le filtre enlettres, qui n'est pas inclus dans la distribution standard de SPIP. Ce filtre écrit un nombre en toutes lettres ( [(#DATE|annee|enlettres)] = « deux mille deux ») ; ce filtre peut être téléchargé sur http://www.uzine.net/spip_contrib/a... ; il suffit de l'ajouter dans votre fichier mes_fonctions.php3 pour l'utiliser.

Depuis [SPIP 1.5], il est possible de passer des paramètres dans les filtres. La syntaxe est

[(#BALISE|filtre{arg1, arg2}|...)]

Le filtre doit être défini de la manière suivante dans mes_fonctions.php3 :

function filtre($texte, $arg1='valeur par defaut1', $arg2='valeur par défaut 2') { ....calculs.... return (une chaine de caractères); }

On peut ainsi appeler n'importe quelle fonction php, ou s'appuyer sur des fonctions définies dans SPIP ou dans mes_fonctions.php3, pour peu qu'elles respectent l'ordre des arguments (le texte à traiter doit être impérativement le premier argument). Par exemple, pour couper le texte à une longueur donnée (50 caractères), on pourra utiliser [(#TEXTE|couper{50})].