SPIP

[ar] [ast] [bg] [br] [ca] [co] [cpf] [cs] [da] [de] [en] [eo] [es] [eu] [fa] [fon] [fr] [gl] [id] [it] [ja] [lb] [nl] [oc] [pl] [pt] [ro] [ru] [sk] [sv] [tr] [vi] [zh] Espace de traduction

Télécharger

Les filtres de SPIP

Mai 2001 — mis à jour le : 14 janvier

Toutes les versions de cet article :


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

Les filtres de mise en page suivants (majuscules, justifier...) ne sont plus conseillés. Il est recommandé de leur préférer, désormais, l’utilisation des styles CSS correspondants.

-  |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 (<P align=justify>).

-  |aligner_droite fait passer le texte en justification à droite (<P align=right>).

-  |aligner_gauche fait passer le texte en justification à gauche (<P align=left>).

-  |centrer centre le texte (<P align=center>).

Les filtres des dates

Les filtres suivants s’appliquent aux dates ([(#DATE|affdate)] par exemple).

-  |affdate affiche la date sous forme de texte, par exemple « 13 janvier 2001 ».

[SPIP 1.8] étend la notation de ce filtre. On peut lui passer un paramètre de formatage de la date, correspondant à un format spip (« 'saison' », etc.) ou à un format de la commande php date (« 'Y-m-d' »).
Par exemple :

  • [(#DATE|affdate{'Y-m'})] affichera numériquement l’année et le mois de la date filtrée séparés par un tiret,
  • la notation [(#DATE|affdate{'saison'})] est totalement équivalente à : [(#DATE|saison)].

-  Il existe aussi des variantes de affdate qui fournissent des raccourcis :

|affdate_jourcourt affiche le nom du mois et la valeur numérique du jour, e.g. « 19 Avril ». Si la date n’est pas dans l’année actuelle, alors l’année est aussi affichée : « 1 Novembre 2004 ».

|affdate_court affiche le nom du mois et le numéros du jour, e.g. « 19 Avril ». Si la date n’est pas dans l’année actuelle, alors on affiche seulement le mois et l’année sans le numéros du jour : « Novembre 2004 ».

|affdate_mois_annee affiche seulement le mois et l’année : « Avril 2005 », « Novembre 2003 ».

|affdate_heure affiche la date suivie de l’heure : « 3 Avril 2005 à 20h00min ».

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

-  [SPIP 1.8] introduit le filtre |unique qui retourne la valeur de l’élément filtré seulement si c’est la première fois qu’elle est rencontrée. Ce filtre n’est pas limité aux dates mais est intéressant pour, par exemple, afficher une liste d’articles par date :

<BOUCLE_blog(ARTICLES){par date}{inverse}{"<br>"}>
[<hr /><h1>(#DATE|affdate_mois_annee|unique)</h1>]
#TITRE ...
</BOUCLE_blog>

cette balise n’affichera la date qu’à chaque changement de mois.

Voici un autre exemple :

<BOUCLE_blog2(ARTICLES){par date}{inverse}>
   [<hr /><h1>(#DATE|annee|unique)</h1>]
       [<h2>(#DATE|affdate{'Y-m'}|unique|nom_mois)</h2>]
            <a href="#URL_ARTICLE">#TITRE</a><br />
</BOUCLE_blog2>

affichera une liste ressemblant à :

  2005
       mars
               article de mars
               autre article de mars
       février
               article de février
  2004
       décembre
               un article

On utilise la notation |affdate{'Y-m'} pour afficher le nom du mois à chaque année. En effet :

  • si l’on ne faisait que #DATE|nom_mois|unique, les noms de mois ne seraient affichés que la première année.
  • si le filtrage était : #DATE|unique|nom_mois, on afficherait toutes les dates. En effet, #DATE retourne une date complète qui contient aussi l’heure. Il y a donc une grande chance que les dates complètes de deux articles publiés le même jours soient différentes.

C’est pourquoi on garde juste le mois et l’année de la date avant de la passer au filtre unique.

On peut passer un argument optionnel à ce filtre pour différencier deux utilisations indépendantes du filtre. Par exemple : [(#DATE|affdate_mois_annee|unique{ici})] n’aura pas d’incidence sur [(#DATE|affdate_mois_annee|unique{la})].

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). Le format des préfixes numerotés est « XX. titre », XX étant un nombre à n chiffres (illimité).

-  Depuis SPIP 1.0, |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 <br> en sauts de ligne, et les espaces insécables en espaces simples. Il s’utilise, par exemple, pour faire un descriptif META : [<meta name="description" content="(#DESCRIPTIF|textebrut)">]

-  |texte_backend peut être utilisé pour transformer un texte et le rendre compatible avec des flux XML. Ce filtre est utilisé, par exemple, dans le squelette backend.html qui génére le fil RSS du site.

-  |couper coupe un texte après un certain nombre de caractères. Il essaie de ne pas couper les mots et enlève le formatage du texte. Si le texte est trop long, alors « (...) » est ajouté à la fin. Ce filtre coupe par défaut à 50 caractères, mais on peut spécifier une autre longueur en passant un paramètre au filtre, par exemple : [(#TEXTE|couper{80})].

-  |lignes_longues, introduit par SPIP 1.9, coupe les mots « trops longs » (utile si l’on a, par exemple, des urls à afficher dans une colone étroite). Ce filtre coupe par défaut à 70 caractères, mais on peut spécifier une autre longueur en passant un paramètre au filtre, par exemple : [(#URL_SITE|lignes_longues{40})].

-  |match utilise une expression rationnelle (cf. preg_match()) pour extraire un motif dans le texte si il est présent, ne retourne rien sinon. Par exemple pour récupérer le premier mot du titre [(#TITRE|match{^\w+?})]. Ce peut être un texte simple, afficher "toto" si dans le titre : [(#TITRE|match{toto})]

-  |replace utilise aussi une expression rationnelle (cf. preg_replace()) pour supprimer ou remplacer toutes les occurences d’un motif dans le texte. Avec un seul parametre, une expression rationnelle, le motif sera remplacé par une chaîne, c’est à dire supprimé.
Par exemple pour supprimer tous les "notaXX" du texte [(#TEXTE|replace{nota\d*})]. Lorsqu’un deuxiéme paramètre est fourni, les occurences du motif seront remplacées par cette valeur. Par exemple pour remplacer tous les 2005 ou 2006 du texte en 2007 [(#TEXTE|replace{200[56],2007})]. Ce peut être des textes simples, remplacer tous les "au temps" par "autant" : [(#TEXTE|replace{au temps,autant})]

Filtres de test

-  [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 ».

-  [SPIP 1.8] introduit le filtre |?{sioui,sinon} qui est une version évoluée de |sinon. Il prend un ou deux paramètres :

  • sioui est la valeur à afficher à la place de l’élément filtré si celui-ci est non vide.
  • sinon est optionnel. C’est la valeur à afficher si l’élément filtré est vide. [(#TEXTE|?{#TEXTE,"pas de texte"})] est équivalent à l’exemple donné pour le filtre |sinon.

-  [SPIP 1.8] introduit un jeu de filtres pour faire des comparaisons avec des valeurs :

  • |=={valeur} et |!={valeur} permettent de vérifier, respectivement, l’égalité ou l’inégalité entre l’élément filtré et valeur. Par exemple : <li [(#TITRE|=={édito}|?{'id="edito"',''})]>#TITRE</li>
  • |>{valeur}, |>={valeur}, |<{valeur} et |<={valeur} comparent l’élément filtré (qui doit être numérique) avec une valeur numérique.
    Par exemple : [(#TOTAL_BOUCLE) [(#TOTAL_BOUCLE|>{1}|?{'articles','article'})] dans cette rubrique.]
    Remarque : De manière générale, tous les opérateurs de comparaison de php peuvent être utilisés comme filtres dans [SPIP 1.8].

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 : entre SPIP 1.4 et [SPIP 2.1] exclus, 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.php ;
  • pour appliquer un filtre quelconque sans mettre d’URL, il faut mettre deux barres. Par exemple : <?php $logo = '[(#LOGO_RUBRIQUE||texte_script)]'; ?> 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).

Depuis SPIP 2.1 les filtres de logos ont la même syntaxe que tous les autres. Un seul pipe suffit : [(#LOGO_XXX|filtre)]

Mais :
-  #LOGO_XXX** renvoie le fichier
-  #LOGO_XXX{top/left/right/center/bottom} génère un alignement
-  #LOGO_XXX{url} génère un logo qui pointe vers l’url.

-  [SPIP 1.8] introduit les filtres |hauteur et |largeur qui retournent les informations sur la taille (i.e. Hauteur et Largeur) de l’élément filtré si c’est une image.

Ces filtres n’ont qu’un intérêt moyen à être appliqués directement à un logo de document puisqu’il y a déjà #HAUTEUR et #LARGEUR à disposition pour les documents. Par contre, on peut les appliquer après le filtre |image_reduire pour connaître la taille exacte de l’image réduite.

Plus généralement, on peut les appliquer sur n’importe quelles balises (ou filtre) retournant un balise HTML <img ...>.


-  |image_reduire{largeur,hauteur} permet de forcer une taille maximale d’affichage des images et des logos.

Ce filtre s’utilise par exemple sur un logo d’article de la façon suivante :

Dans cet exemple, le logo de l’article apparaît aligné à droite, à une taille maximale de 130 pixels.

Depuis [SPIP 1.8.2], ce filtre peut prendre deux arguments : largeur et hauteur. Si l’un de ces deux arguments est égal à 0, SPIP ne tient compte que de l’autre et calcule cette dimension en conservant les proportions de l’image. De plus, ce filtre s’applique aussi à la balise #TEXTE et ce sont alors toutes les images que le rédacteur introduit dans le texte grâce aux raccourcis SPIP qui sont alors réduites.

Ainsi, par exemple,

affiche toutes les images insérées dans le fil du texte à une largeur maximale de 600 pixels. Cela permet de préserver la mise en page même sans que le rédacteur ait à se soucier de la taille des images qu’il télécharge sur le site.

NB. Si l’option « création de vignettes » est activée dans la configuration du site, ces logos réduits seront des fichiers d’images spécifiques calculés automatiquement par le serveur (idéalement, avec l’extension GD2 installée sur le serveur), pour les formats acceptés par le serveur (avec GD2, habituellement, les formats JPG et PNG). Sinon, c’est une version complète de l’image qui est affichée, mais avec une taille d’affichage fixée directement en HTML.


Historique : SPIP 1.7.1 introduit le filtre |reduire_image. Avec SPIP 1.9, celui-ci devient |image_reduire (les filtres de traitement d’image commencent ainsi tous par |image_).

Les filtres mathématiques

SPIP 1.9 introduit une série de filtres d’opérations mathématiques.

-  |plus{xx}, |moins{xx} et |mult{xx} correspondent respectivement à l’addition, la soustraction et la multiplication.

-  |div{xx} correspond à la division non-euclidienne ("après la virgule").

-  |modulo{xx} correspond au reste de la division euclidienne par xx d’un nombre.

Par exemple [(#COMPTEUR_BOUCLE|modulo{5})] compte de 0 à 4 puis revient à 0 etc

De plus l’ensemble des fonctions mathématiques PHP peuvent être utilisées comme filtres.

Autres Filtres

-  |traduire_nom_langue s’applique à la balise #LANG et retourne un traduction du code de langue qu’elle retourne (fr, en, it, etc.) dans cette langue.


Remarque : Les traductions des codes sont faites dans la langue que représente ce code et suivent les conventions d’écriture de cette langue.

Ainsi « fr » sera traduit « français » en minuscule, alors que « es » sera traduit « Español » avec une majuscule.

-  |alterner{a,b,c,...} [SPIP 1.8.2] s’applique à une balise numérique (en général #COMPTEUR_BOUCLE ou #TOTAL_BOUCLE) et affiche l’argument correspondant à la valeur de cette balise
. On peut ainsi alterner un affichage dans une boucle. Par exemple, [(#COMPTEUR_BOUCLE|alterner{'white','yellow'})] affichera « white » à la première itération de la boucle, « yellow » à la deuxième, « white » à la troisième, « yellow » à la quatrième, etc. Ainsi, on peut faire une liste d’article qui utilise une couleur différente pour les lignes paires et impaires :

<B_lesarticles>
  <ul>
<BOUCLE_lesarticles(ARTICLES) {par titre}>
  <li style="background: [(#COMPTEUR_BOUCLE|alterner{'white','yellow'})]">#TITRE</li>
</BOUCLE_lesarticles>
  </ul>
</B_lesarticles>

-  |inserer_attribut{attribut,valeur} [SPIP 1.8.2] permet d’ajouter un attribut html dans une balise html générée par SPIP. Par exemple : [(#LOGO_DOCUMENT||inserer_attribut{'alt',#TITRE})] va ajouter un attribut « alt » avec le titre du document dans la balise « img » du logo.

-  |extraire_attribut{attribut} [SPIP 1.8.2] est l’inverse du filtre précédent. Il permet de récupérer un attribut d’une balise html générée par SPIP. Par exemple, on peut trouver le chemin de la vignette générée par le filtre :
<div style="background: url([(#LOGO_ARTICLE||image_reduire{90}|extraire_attribut{src})]) left;"]>#TEXTE</div>

-  |vider_attribut{attribut} SPIP 1.9 est une variante de inserer_attribut. Il permet de supprimer les attribut html. Exemple [(#LOGO||vider_attribut{width})] enlever l’attribut ’width’ sur l’image d’un logo (quelle idée !)

-  |parametre_url{parametre,valeur} [SPIP 1.8.2] est un filtre qui permet d’ajouter des paramètres dans une url générée par une balise SPIP. Si valeur vaut '' le filtre supprime un paramètre actuellement dans l’url. Par exemple, la balise #SELF retourne l’url de la page actuelle, donc :

  • [(#SELF|parametre_url{'id_article','12'})] placera une variable id_article égale à 12 dans l’url,
  • [(#SELF|parametre_url{'id_article',''})] effacera l’id_article actuellement dans l’url.

Employé avec un seul paramètre le filtre agit différemment :
#URL...|parametre_url{x} extrait le parametre ’x’ de l’url et en retourne la valeur.

On peut par exemple l’utiliser pour faire des boutons pour naviguer parmi les documents sur une page :

<BOUCLE_actuel(DOCUMENTS) {id_document}>
 #LOGO_DOCUMENT
 <ul>
 <BOUCLE_precede(DOCUMENTS) {par date} {age_relatif <= 0} {0,1} {exclus}>
 <li>
   <a href="[(#SELF|parametre_url{'id_document',#ID_DOCUMENT})]" title="précédent">
     [(#LOGO_DOCUMENT||image_reduire{70})]
   </a>
 </li>
 </BOUCLE_precede>
 <BOUCLE_suivant(DOCUMENTS) {par date} {age_relatif > 0} {0,1}>
 <li>
   <a href="[(#SELF|parametre_url{'id_document',#ID_DOCUMENT})]" title="suivant">
     [(#LOGO_DOCUMENT||image_reduire{70})]
   </a>
 </li>
 </BOUCLE_suivant>
 </ul>
</BOUCLE_actuel>

|ancre_url{ancre} SPIP 1.9.1 ajoute ou modifie une ancre d’url. Par exemple [(#URL_ARTICLE|ancre_url{ancre})].

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 : [<textarea>(#DESCRIPTIF|entites_html)</textarea>]

-  |texte_script transforme n’importe quel champ en une chaîne utilisable en PHP ou Javascript en toute securité, exemple : <?php $x = '[(#TEXTE|texte_script)]'; ?>. 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 <a href="#URL_ARTICLE"[ title="(#DESCRIPTIF|attribut_html|couper{80})"]>#TITRE</a>. Dans les versions antérieures à SPIP 1.9.2, il fallait ajouter le filtre |supprimer_tags.

-  |liens_absolus [SPIP 1.8.2] s’applique sur une balise de texte et transforme tous les liens que celui-ci contient en liens absolus, en préfixant le protocole (http ou https) et le nom d’hôte courants. Ce filtre est particulièrement utile dans des squelettes de fil rss par exemple. Pour forcer une certaine URL de base, il est possible de la passer en argument, par exemple #TEXTE|liens_absolus{#URL_SITE_SPIP}

-  |url_absolue [SPIP 1.8.2] marche de la même façon que le filtre précédent, mais s’applique à une balise qui retourne une url (par exemple #URL_ARTICLE). Tout comme le filtre liens_absolus, ce filtre accepte une URL de base comme paramètre optionnel.

-  |abs_url [SPIP 1.8.2] combine les deux balises précédentes et peut donc s’appliquer à un texte ou à une balise d’url. Il accepte le même paramètre optionnel.

-  |form_hidden SPIP 1.9 Si on fait un formulaire qui utilise comme action un lien comprenant des arguments (par exemple, quand on utilise la balise #SELF avec le type d’url par defaut), il faut remettre ces valeurs dans des champs hidden ; cette fonction calcule les champs en question. A utiliser par exemple :

<form action="#SELF">
[(#SELF|form_hidden)]
...
</form>

-  Le filtre |compacte permet de réduire la taille d’un CSS ou d’un javascript en supprimant tout les commentaires. Le filtre prend en entrée le nom du fichier, et produit un nouveau fichier dont il renvoie le nom <link rel="stylesheet" href="[(#CHEMIN{spip_style.css}|compacte)]" type="text/css" media="all" />. (Filtre ajouté dans SPIP 1.9.2)

-  Un nombre d’autres filtres techniques sont référencés sur cette page et sur code.spip.net.

Ajouter ses propres fonctions

Les filtres de SPIP sont des fonctions PHP qui reçoivent la balise sur laquelle ils sont appliqués en premier paramètre et retournent le texte à afficher. Vous pouvez utiliser directement les fonctions habituelles de PHP, mais également créer les vôtres, sur le modèle :

<?php
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.php : si SPIP repère un fichier ayant ce nom, il l’inclut automatiquement.


Historique :
Dans les versions antérieures à [SPIP 1.9] ce fichier doit s’appeler mes_fonctions.php3

De façon générale jusqu’à [SPIP 1.9] , les fichiers de spip avaient une extension en .php3 et non en .php.

Depuis [SPIP 1.8] il peut se situer :

  • dans le dossier où sont stockés vos squelettes
  • à la racine du site Mais jamais dans les deux à la fois.

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.php pour l’utiliser.

Il est possible (depuis SPIP 2.0) de définir des filtres applicables uniquement à un squelette particulier.
Pour cela, on créera, dans un fichier article_fonctions.php, des filtres qui ne seront effectifs que dans le squelette article.html.
attention : ce fichier xxxx_fonctions.php devra se trouver au même niveau (dans le même répertoire) que le squelette xxxx.html.

Filtres avec des paramètres

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.php :

function filtre($texte, $arg1='valeur par defaut1', $arg2='valeur par défaut2')
{
   ....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.php, pour peu qu’elles respectent l’ordre des arguments (le texte à traiter doit être impérativement le premier argument). Par exemple, pour enlever les points à la fin d’un texte, on pourra faire : [(#TEXTE|rtrim{'.?!'})].

Depuis [SPIP 1.8], les arguments des filtres peuvent être des balises (sans codes optionnels ni filtres). Par exemple :
[(#TOTAL_BOUCLE|=={#COMPTEUR_BOUCLE}|?{'Fin.',''})]
Depuis [SPIP 1.8.2] on peut mettre un balise avec notation étendue en paramètre. Par exemple :
[(#DESCRIPTIF|sinon{[(#CHAPO|sinon{#TEXTE}|couper{300})]})]


Voir le squelette de cette page Site réalisé avec SPIP | Espace de traduction | Espace privé