Els filtres d’SPIP

Els filtres de configuració de la pàgina

Els filtres de configuració de la pàgina següents (majuscules, justifier...) no són massa aconsellables. Es recomanable preferir, d’ara en endavant, la utilització dels estils CSS corresponents.

-  majuscules passa el text a majúscules. Si ho comparem amb la funció de PHP, podem adonar-nos que el filtre majuscules s’aplica també a les lletres accentuades.

-  justifier passa el text a justificació total (<P align=justify>).

-  aligner_droite fa passar el text a justificació alineada a la dreta (<P align=right>).

-  aligner_gauche fa passar el text a justificació alineada a l’esquerre (<P align=left>).

-  centrer centra el text (<P align=center>).

Els filtres de les dates

Els filtres següents s’apliquen a les dates ((#DATE per exemple).

-  affdate visualitza la data en forma de text, per exemple “13 gener 2001”.

[SPIP 1.8] eixampla la notació d’aquest filtre. Li podem passar un paràmetre de formatatge de la data, corresponent a un format spip («'saison'», etc.) o a un format de l’ordre php date («'Y-m-d'»). Per exemple:

• [(#DATE|affdate{'Y-m'})] mostrarà numèricament l’any de la data filtrada separats per un guionet,
• la notació [(#DATE|affdate{'saison'})] és totalment equivalent a: [(#DATE|saison)].

-  Existeix també variants de affdate qui proporcionen dreceres:

affdate_jourcourt mostra el nom del mes i el valor numèric del dia, per exemple «19 Abril». Si la data no es troba dins l’any en curs, aleshores es mostra també l’any: «1 Novembre 2004».

affdate_court mostra el nom del mes i el número del dia, per exemple «19 Abril». Si la data no es troba dins l’any en curs, llavors mostra només el mes i l’any sense el número del dia: «Novembre 2004».

affdate_mois_annee mostra únicament el mes i l’any: «Abril 2005», «Novembre 2003».

-  jour mostra el dia (en números).

-  mois mostra el mes (en números).

-  annee mostra l’any.

-  [SPIP 1.0.2] heures mostra les hores d’una data (els camps de dates registrades automàticament per l’SPIP a la seva base comprenen no només la data en sí, sinó també l’hora exacta).

-  [SPIP 1.0.2] minutes mostra els minuts.

-  [SPIP 1.0.2] secondes permet visualitzar els segons.

-  nom_jour mostra el nom del dia (dilluns, dimarts, dimecres,...).

-  nom_mois mostra el nom del mes (gener, febrer, març ...).

-  saison mostra l’estació de l’any (primavera, estiu,...).

[SPIP 1.8] introdueix el filtre unique que retorna el valor de l’element filtrat només si és la primera vegada que es troba. Aquest filtre no està limitat només a les dates però és interessant, per exemple, per mostrar una llista d’articles per data:

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

aquesta etiqueta només mostrarà la data quan hi hagi un canvi de mes.

Heus aquí un altre 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>

mostrarà una llista que s’assemblarà a:

   2005
        març
                article de març
                un altre article de març
        febrer
                article de febrer
   2004
        desembre
                un article

Farem servir la notació affdate{'Y-m'} per mostrar el nom del mes a cada any. De fet:

• si només poséssim #DATE|nom_mois|unique, els noms del mes només es mostrarien el primer any.
• si el filtrage hagués estat: #DATE|unique|nom_mois, es mostrarien totes les dates. De fet, #DATE retorna una data completa que conté també l’hora. Tenim per tant la gran sort que les dates completes de dos articles publicats el mateix dia siguin diferents.

És justament per això que es guarda el mes i l’any de la data abans de passar-la al filtre unique.

Es pot afegir un argument opcional a aquest filtre per tal de diferenciar dues utilitzacions independents del filtre. Per exemple: [(#DATE|affdate_mois_annee|unique{ici})] no tindrà incidència en [(#DATE|affdate_mois_annee|unique{la})].

Filtres de text

La major part d’aquests filtres van ser introduïts a la versió SPIP 1.4.

-  liens_ouvrants transforma els enllaços SPIP que van cap a llocs Web externs en enllaços del tipus «popup», que s’obren en una nova finestra; és l’equivalent al target=blank de l’HTML. N.B.: els desenvolupadors de l’SPIP estimen que aquest comportament en una pàgina web és, en general, una mica descortès ja que l’internauta sap, si així ho desitja, obrir una altra finestra fàcilment sense que el sistema li imposi. Però la insistència era massa forta i nosaltres hem cedit... ;-).

-  supprimer_numero serveix per eliminar el número d’un títol, si per exemple es vol classificar els articles par num titre però no es volen visualitzar aquests números (donat a que la seva finalitat només és la d’ordenar els articles). El format dels prefixes numerats és «XX. títol», XX és un número de n xifres (il·limitat).

-  A partir d’SPIP 1.0, PtoBR transforma els salts de paràgraf en simples canvis de línia, cosa que permet «estrènyer» una configuració de la pàgina, per exemple a l’interior d’un sumari.

-  taille_en_octets permet de transformar un número de bytes o octets (25678906) en una cadena de caràcters més explícita (« 24.4 MB »).

-  supprimer_tags és una supressió bàsica i dràstica de tots els <...>.

-  textebrut s’assembla al filtre supprimer_tags, però actua de manera més subtil, transformant sobretot els paràgrafs i els <br> en canvis de línia, i els espais indivisibles en espais simples. S’utilitza, per exemple, per fer una descripció META: [<meta name="description" content="(#DESCRIPTIF|textebrut)">]

-  texte_backend es pot utilitzar per transformar un text i fer-lo compatible amb els flux XML. Aquest filtre s’utilitza, per exemple, en l’esquelet backend.html que és el que genera el fil RSS del lloc.

-  couper talla un text després d’un cert número de caràcters. Intenta no tallar les paraules i treu el format del text. Si el text és massa llarg, llavors afegeix «(...)» al final. Aquest filtre talla per defecte a 50 caràcters, però es pot especificar una altra llargada posant un paràmetre al filtre, per exemple: [(#TEXTE|couper{80})].

-  lignes_longues, introduït per SPIP 1.9, talla les paraules «massa llargues» (útil si tenim, per exemple, URLs a publicar en una columna estreta). Aquest filtre talla, per defecte, a 70 caràcters, però es pot especificar una altra llargada si li passem un paràmetre al filtre, per exemple: [(#URL_SITE|lignes_longues{40})].

-  match fa servir una expressió habitual (cf. preg_match()) per extreure un patró a dins del text si hi és present, sense retornar res si no hi és. Per exemple per recuperar la primera paraula del títol [(#TITRE|match{^\w+?})]. Això pot ser un text simple, publicar "toto" si es troba a dins del títol: [(#TITRE|match{toto})]

-  replace fa servir també una expressió habitual (cf. preg_replace()) per suprimir o substituir totes les ocurrències d’un patró a dins del text. Amb un sol paràmetre, una expressió habitual, el patró serà substituït per una cadena, és a dir suprimit. Per exemple per suprimir tots els "notaXX" del text [(#TEXTE|replace{nota\d*})]. Quan li proporcionem un segon paràmetre, les ocurrències del patró seran substituïdes per aquest valor. Per exemple per substituir tots els 2005 o 2006 del text en 2007 [(#TEXTE|replace{200[56],2007})]. Això pot ser des de textos simples, substituir tots els "au temps" per "autant": [(#TEXTE|replace{au temps,autant})]

Filtres de test

-  [SPIP 1.6] introdueix el filtre |sinon, que indica què cal mostrar si l’element «filtrat» està buit: d’aquesta manera [(#TEXTE|sinon{"pas de texte"})] mostra el text; si aquest està buit, mostra «cap text».

-  [SPIP 1.8] introdueix el filtre |?{sioui,sinon} que és una versió evolucionada de |sinon. Agafa un o dos paràmetres:

• sioui és el valor a mostrar en el lloc de l’element filtrat si aquest no està buit.
• sinon és opcional. És el valor a mostrar en el lloc de l’element filtrat si aquest no és buit. [(#TEXTE|?{#TEXTE,"pas de texte"})] és equivalent a l’exemple que ja hem donat pel filtre |sinon.

-  [SPIP 1.8] introdueix un joc de filtres per fer comparacions amb els valors:

• |=={valeur} i |!={valeur} permeten verificar, respectivament, la igualtat o la diferència entre l’element filtrat i valeur. Per exemple: <li [(#TITRE|=={édito}|?{'id="edito"',''})]>#TITRE</li>

• |>{valeur}, |>={valeur}, |<{valeur} i |<={valeur} comparen l’element filtrat (que ha de ser numèric) amb un valor numèric.
  Per exemple:

  [(#TOTAL_BOUCLE) [(#TOTAL_BOUCLE|>{1}|?{'articles','article'})] dans cette rubrique.]
  

  Advertència: En general, tots els operadors de comparació de php es poden fer servir com a filtres a [SPIP 1.8].

Filtres de logotips

-  fichier [SPIP 1.4]. Destinat a un logotip, aquest filtre permet recuperar directament el nom de fitxer corresponent al logotip.

-  ||autres filtres Contràriament a les versions anteriors, [SPIP 1.4] permet posar filtres «personalitzats» als logotips: la lògica és una mica retorçada perquè fa falta respectar la compatibilitat amb l’SPIP 1.3. L’anàlisi es desenvolupa d’aquesta manera:

• si el primer « filtre » no és un alineació, SPIP considera que es tracta d’un URL i fa un enllaç des del logotip cap a aquesta adreça;
• si el primer filtre és una alineació, SPIP considera que el segon «filtre» és un URL;
• els filtres següents són veritables filtres en el sentit més habitual (i comprenen els filtres «personalitzats» definits a mes_fonctions.php;
• per aplicar un filtre qualsevol sense posar un URL, cal posar dues barres. Per exemple: <?php $logo = '[(#LOGO_RUBRIQUE||texte_script)]'; ?> permet recuperar el logotip en la variable php $logo, per un tractament posterior (veure més avall el significat de |texte_script).

A partir d’SPIP 2.1 els filtres de logos tenen la mateixa sintaxi que tots els altres. N’hi ha prou amb una única barra: [(#LOGO_XXX|filtre)]

Però:
-  #LOGO_XXX** torna el fitxer
-  #LOGO_XXX{top/left/right/center/bottom} genera un alineament
-  #LOGO_XXX{url} genera un logo que apunta cap a l’url.

-  [SPIP 1.8] introdueix els filtres hauteur i largeur que retornen les informacions sobre la mida (i.e. alçada i amplada) de l’element filtrat si és una imatge.

Aquests filtres tenen ben poc interès quan són aplicats directament a un logotip d’un document ja que aquest ja té #HAUTEUR i #LARGEUR a disposició pels documents. Al contrari, es poden aplicar després del filtre image_reduire per tal de conèixer la mida exacta de la imatge reduïda.

En general, les podem aplicar sobre qualsevol etiqueta (o filtre) que retorni una etiqueta HTML <img ...>.

-  |image_reduire{largeur,hauteur} permet forçar una mida màxima de publicació de les imatges i dels logotips.

Aquest filtre s’utilitza, per exemple, en un logotip d’article de la següent manera:

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

En aquest exemple, el logotip de l’article apareix alineat a la dreta i la seva mida serà de 130 píxels com a màxim.

A partir d’[SPIP 1.8.2], aquest filtre pot tenir dos arguments: amplada i alçada. Si un d’aquests dos arguments és igual a 0, SPIP només té en compte l’altre i calcula aquesta dimensió conservant les proporcions de la imatge. A més, aquest filtre s’aplica també a l’etiqueta #TEXTE i, en aquest cas, es redueixen totes les imatges que el redactor introdueixi en el text gràcies a les dreceres SPIP.

D’aquesta manera, per exemple,

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

mostra totes les imatges inserides al llarg d’un text amb una amplada màxima de 600 píxels. Això permet conservar la configuració de la pàgina sense que el redactor s’hagi de preocupar de la mida de les imatges que descarrega al lloc Web.

NB. Si la opció «creació de vinyetes» està activada a la configuració del lloc, aquests logotips reduïts seran fitxers d’imatges específiques calculades automàticament pel servidor (idealment, amb l’extensió GD2 instal·lada en el servidor), pels formats acceptats pel servidor (amb GD2, habitualment, els formats JPG i PNG). Sinó, és una versió complerta de la imatge la que es mostrarà, però amb una mida de publicació fixada directament en HTML.

Històric : SP<font color="yellow">IP 1.7.1 introdueix el filtre |reduire_image. Amb SPIP 1.9, aquest esdevé |image_reduire (els filtres de tractament d’imatge comencen tots d’aquesta manera per |image_).

Els filtres matemàtics

SPIP 1.9 introdueix una colla de filtres d’operacions matemàtiques.

-  |plus{xx}, |moins{xx} i |mult{xx} corresponen respectivament a la suma, la resta i la multiplicació.

-  |div{xx} correspon a la divisió no-euclidiana ("després de la coma").

-  |modulo{xx} correspon a la resta de la divisió euclidiana per xx d’un nombre.

Per exemple [(#COMPTEUR_BOUCLE|modulo{5})] compta de 0 a 4 i després torna a 0 etc.

A més, el conjunt de funcions matemàtiques PHP es poden utilitzar com a filtres.

Altres Filtres

-  traduire_nom_langue s’aplica a l’etiqueta #LANG i torna una traducció del codi de llengua que aquesta retorna (fr, en, it, ca, etc.) en aquesta llengua.

Nota: Les traduccions dels codis estan fetes en la llengua que representa aquest codi i seguint les convencions d’escriptura d’aquesta llengua.

D’aquesta manera «fr» es traduirà «français» en minúscula, mentre que «es» serà traduït «Español» amb una majúscula.

-  alterner{a,b,c,...} [SPIP 1.8.2] s’aplica a una etiqueta numèrica (en general #COMPTEUR_BOUCLE o #TOTAL_BOUCLE) i mostra l’argument corresponent al valor d’aquesta etiqueta . D’aquesta manera es pot alternar una presentació en un bucle. Per exemple, [(#COMPTEUR_BOUCLE|alterner{'white','yellow'})] mostrarà «white» à la primera iteració del bucle, «yellow» a la segona, «white» a la tercera, «yellow» a la quarta, etc. D’aquesta manera, es pot fer una llista d’articles que utilitzi un color diferent a les files parells i imparells:

<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 afegir un atribut html en una etiqueta html generada per SPIP. Per exemple: [(#LOGO_DOCUMENT||inserer_attribut{'alt',#TITRE})] afegirà un atribut «alt» amb el títol del document a l’etiqueta «img» del logotip.

-  extraire_attribut{attribut} [SPIP 1.8.2] és l’invers del filtre anterior. Permet recuperar un atribut d’una etiqueta html generada per SPIP. Per exemple, es pot trobar la ruta de la miniatura generada pel filtre

-  vider_attribut{attribut}SPIP 1.9 és una variant d’inserer_attribut. Permet suprimir els atributs html. Exemple [(#LOGO||vider_attribut{width})] treure l’atribut ’width’ de l’imatge d’un logotip (quina idea!)

image_reduire:

<div style="background: url([(#LOGO_ARTICLE||image_reduire{90}|extraire_attribut{src})]) left;"]>#TEXTE</div>

-  parametre_url{parametre,valeur} [SPIP 1.8.2] és un filtre que permet afegir paràmetres en una url generada per una etiqueta SPIP. Si valeur val '' el filtre suprimeix un paràmetre actualment a l’url. Per exemple, l’etiqueta #SELF retorna el url de la pàgina actual, per tant:

• [(#SELF|parametre_url{'id_article','12'})] situarà una variable id_article igual a 12 a l’url,
• [(#SELF|parametre_url{'id_article',''})] esborrarà l’id_article que hi ha actualment a l’url.

Utilitzat amb un sol paràmetre el filtre es comporta de manera diferent: #URL...|parametre_url{x} extreu el paràmetre ’x’ de l’url i en retorna el valor.

Es pot utilitzar, per exemple, per fer botons per navegar entre els documents d’una pàgina:

<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 afegeix un modifica una àncora a un url. Par exemple [(#URL_ARTICLE|ancre_url{ancre})].

Filtres tècnics

Aquests filtres han estat introduïts per [SPIP 1.4].

-  entites_html transforma un text en entitats HTML, que es poden inserir en un formulari, per exemple: [<textarea>(#DESCRIPTIF|entites_html)</textarea>]

-  texte_script transforma qualsevol etiqueta en una cadena utilitzable en PHP o en Javascript amb total seguretat, per exemple: <?php $x = '[(#TEXTE|texte_script)]'; ?>. Atenció: utilitzeu correctament el caràcter ' i no ": en efecte, en el segon cas, si el vostre text conté el símbol $, el resultat pot ser desastrós (visualització parcial, que es mostri una altra cosa, fallada del php, etc.).

-  attribut_html retorna una cadena utilitzable sense perjudici com atribut HTML; per exemple, si es vol afegir un text al passar per sobre el ratolí a l’enllaç normal cap a un article, utilitzarem <a href="#URL_ARTICLE"[ title="(#DESCRIPTIF|attribut_html|couper{80})"]>#TITRE</a>. A les versions anteriors a SPIP 1.9.2, s’havia d’afegir el filtre |supprimer_tags.

-  liens_absolus [SPIP 1.8.2] s’aplica en una etiqueta de text i transforma tots els enllaços que aquest conté en enllaços absoluts, prefixant el protocol (http o https) i el nom de domini actual. Aquest filtre és particularment útil, per exemple, en els esquelets de fil rss. Per forçar un URL concret de base, és possible passar-li en argument, per exemple #TEXTE|liens_absolus{#URL_SITE_SPIP}

-  url_absolue [SPIP 1.8.2] funciona de la mateixa manera que el filtre anterior, però s’aplica a una etiqueta que retorni un url (per exemple #URL_ARTICLE). Igual com en el liens_absolus, aquest filtre accepta un URL de base com a paràmetre opcional.

-  abs_url [SPIP 1.8.2] combina les dues etiquetes precedents i, per tant, es pot aplicar a un text o a una etiqueta d’url. Accepta el mateix paràmetre opcional.

-  form_hidden SPIP 1.9 Si es fa un formulari que utilitza com acció un enllaç que comprengui arguments (per exemple, quand s’utilitza l’etiqueta #SELF amb el tipus d’url per defecte), cal tornar a posar aquests valors a dins dels camps hidden; aquesta funció calcula els camps en qüestió. Fer-ho servir, per exemple:

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

-  El filtre |compacte permet reduir la mida d’un CSS o d’un javascript suprimint tots els comentaris. El filtre agafa d’entrada el nom del fitxer, i produeix un nou fitxer del que en reenvia el nom <link rel="stylesheet" href="[(#CHEMIN{spip_style.css}|compacte)]" type="text/css" media="all" />. (Filtre afegit a SPIP 1.9.2)

-  Trobareu referenciats aquí un bon nombre d’altres filtres tècnics.

Afegir les pròpies funcions

Els filtres de l’SPIP són funcions PHP que reben l’etiqueta sobre la que s’apliquen com a primer paràmetre i retornen el text a mostrar. Podeu fer servir directament les funcions habituals de PHP, però també podeu crear els vostres propis models:

<?php
funcio meu_filtre($text){
   $text = (algunes operacions en PHP) ...;
   return $text;
}
?>

Per no modificar arxius de l’SPIP (que hi hauria el risc que fossin esborrats en una propera actualització), podeu instal·lar les vostres funcions personalitzades en un fitxer mes_fonctions.php: si SPIP localitza un fitxer que porta aquest nom, l’inclou automàticament.

Històric : A les versions anteriors a [SPIP 1.9] aquest fitxer s’ha d’anomenar mes_fonctions.php

En general, fins a [SPIP 1.9], els fitxers d’SPIP tenien una extensió en .php3 i no en .php.

A partir d’[SPIP 1.8] es pot situar:

• a l’interior de la carpeta on hi tingueu emmagatzemats les vostres plantilles (esquelets)
• a l’arrel del lloc Web Però mai als dos llocs a la vegada.

Per exemple, ARNO* ha desenvolupat el filtre enlettres, que no s’inclou a la distribució estàndard de l’SPIP. Aquest filtre escriu un nombre amb totes les lletres ( [(#DATE|annee|enlettres)] = « dos mil dos ») ; aquest filtre el podeu baixar de http://www.uzine.net/spip_contrib/a...; n’hi ha prou d’afegir-lo al vostre fitxer mes_fonctions.php per a poder-lo utilitzar.

És possible (a partir d’SPIP 2.0) definir filtres aplicables només a un esquelet en concret.
Per exemple, crearem, en un fitxer article_fonctions.php, filtres que només seran efectius a l’esquelet article.html. _Atenció: aquest fitxer xxxx_fonctions.php s’haurà de trobar al mateix nivell (a dins del mateix directori) que l’esquelet xxxx.html.

Filtres amb paràmetres

A partir de [SPIP 1.5], és possible passar paràmetres dins dels filtres. La sintaxi és:

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

El filtre ha de ser definit de la manera següent a mes_fonctions.php:

function filtre ($text, $arg1='valeur par defaut1', $arg2='valeur par defaut2')
{
    ....càlculs....
    return (una cadena de caràcters);
}

Així, podem cridar qualsevol funció php, o recolzar-nos en funcions definides en l’SPIP o en mes_fonctions.php, per poc que respectin l’ordre dels arguments (el text a tractar ha de ser, forçosament, el primer argument). Par exemple, per treure els punts al final del text, podríem fer: [(#TEXTE|rtrim{'.?!'})].

A partir de [SPIP 1.8], els arguments dels filtres poden ser etiquetes (sense codis opcionals ni filtres). Per exemple:
[(#TOTAL_BOUCLE|=={#COMPTEUR_BOUCLE}|?{'Fin.',''})]
A partir d’[SPIP 1.8.2] es pot posar una etiqueta amb notació estesa en paràmetre. Per exemple:
[(#DESCRIPTIF|sinon{[(#CHAPO|sinon{#TEXTE}|couper{300})]})]