Les filtres de SPIP

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

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.

-  |heures affiche les heures d’une date (les dates fournies par SPIP contiennent non seulement le jour, mais également les horaires).

-  |minutes affiche les minutes d’une date.

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

-  |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

Voir aussi l’article consacré aux filtres de texte.

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

-  |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})].

-  |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 paramètre, 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

-  |?{vrai,faux} est une version évoluée de |sinon. Il prend un ou deux paramètres :

• vrai est la valeur à afficher à la place de l’élément filtré si celui-ci est non vide.
• faux 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.

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

-  |oui retourne un espace ou rien. C’est équivalent à |?{' ',''} ou |?{' '} et permet de retourner un contenu non vide (un espace) pour signaler que les parties optionnelles des balises doivent s’afficher.

-  |non est l’inverse de |oui et est équivalent à |?{'',' '}

-  |et permet de vérifier la présence de 2 éléments

-  |ou vérifie la présence d’un des deux éléments

- |xou vérifie la présence d’un seul de deux éléments.

Par ailleurs, SPIP comprendra les équivalent anglais « yes », « not », « or », « and » et « xor »

// affiche le chapeau s'il existe, sinon le début du texte
[(#CHAPO|sinon{#TEXTE|couper{200}})]
 // affiche "Ce titre est long" seulement si le titre fait plus de 30 caracteres
[(#TITRE|strlen|>{30}|oui) Ce titre est long ]
 
[(#CHAPO|non) Il n'y a pas de chapo ]
[(#CHAPO|et{#TEXTE}) Il y a un chapo, et un texte ]
[(#CHAPO|et{#TEXTE}|non) Il n'y a pas les deux ensemble ]
[(#CHAPO|ou{#TEXTE}) Il y a soit un chapo, soit un texte, soit les deux ]
[(#CHAPO|ou{#TEXTE}|non) Il y a ni chapo, ni texte ]
[(#CHAPO|xou{#TEXTE}) Il y a soit un chapo, soit un texte (mais pas les deux, ni aucun) ]
[(#CHAPO|xou{#TEXTE}|non) Il y a soit rien, soit tout, mais pas l'un des deux ]

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

Filtres de logos

Les filtres de logos ont la même syntaxe que tous les autres :
[(#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.

-   Les filtres |hauteur et |largeur 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 :

[(#LOGO_ARTICLE|right|image_reduire{130})]

Dans cet exemple, le logo de l’article apparaît aligné à droite, à une taille maximale de 130 pixels.
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,

[(#TEXTE|image_reduire{600,0})]

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.

Filtres 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,...} 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} 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} 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} 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} 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} Par exemple [(#URL_ARTICLE|ancre_url{ancre})].

Filtres techniques

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

-  |liens_absolus 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 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 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 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" />.

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

Ajouter ses propres filtres

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 :

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.

Il peut se situer :

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

Il est possible 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

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{'.?!'})].

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