I filtri di SPIP

I filtri di impaginazione

I seguenti filtri di impaginazione (majuscules, justifier...) non sono più raccomandati. Oramai si raccomanda di utilizzare gli stili CSS corrispondenti.

-  majuscules cambia il testo in maiuscolo. A differenza della funzione in PHP, majuscules si applica anche alle lettere accentate.

-  justifier giustifica il testo (<P align=justify>).

-  aligner_droite allinea il testo a destra (<P align=right>).

-  aligner_gauche allinea il testo a sinistra (<P align=left>).

-  centrer centra il testo (<P align=center>).

I filtri delle date

I seguenti filtri si applicano alle date ((#DATE per esempio).

-  affdate mostra la data sotto forma di testo, per esempio "13 gennaio 2001".

[SPIP 1.8] estende la sintassi di questo filtro. È possibile passargli un parametro di formattazione della data, corrispondente a un formato SPIP («'saison'», ecc.) oppure a un formato del comando PHP date («'Y-m-d'»). Per esempio:

• [(#DATE|affdate{'Y-m'})] visualizza numericamente l’anno e il mese separati da un trattino della data filtrata,
• la sintassi [(#DATE|affdate{'saison'})] è assolutamente equivalente a: [(#DATE|saison)].

-  Vi sono anche delle varianti di affdate che danno alcune scorciatoie:

affdate_jourcourt visualizza il nome del mese e il valore numerico del giorno, per es. «19 aprile». Se la data non è nell’anno attuale viene mostrato anche l’anno: «1 novembre 2004».

affdate_court visualizza il nome del mese e il numero del giorno, per es. «19 aprile». Se la data non è nell’anno attuale viene mostrato solo il mese e l’anno senza il numero del giorno: «Novembre 2004».

affdate_mois_annee mostra solamente il mese e l’anno: «Aprile 2005», «Novembre 2003».

-  jour mostra il giorno (in cifre).

-  mois mostra il mese (in cifre).

-  annee mostra l’anno.

-  [SPIP 1.0.2] heures mostra l’ora di una data (le date fornite da SPIP contengono sia il giorno che l’orario).

-  [SPIP 1.0.2] minutes mostra i minuti di una data.

-  [SPIP 1.0.2] secondes mostra i secondi.

-  nom_jour mostra il nome del giorno (lunedì, martedì...).

-  nom_mois mostra il nome del mese (gennaio, febbraio...).

-  saison mostra la stagione (inverno, estate...).

-  [SPIP 1.8] introduce il filtro unique che restituisce il valore dell’elemento filtrato esclusivamente se è la prima ricorrenza. Questo filtro non è limitato alle date ma è utile, per esempio, per visualizzare un elenco di articoli per data:

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

questo segnaposto visualizza la data solo ad ogni cambio di mese.

Ecco un altro esempio:

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

visualizza un elenco del tipo sotto riportato:

   2005
        marzo
                articolo di marzo
                altro articolo di marzo
        febbraio
                articolo di febbraio
   2004
        dicembre
                un articolo

Si utilizza la sintassi affdate{'Y-m'} per visualizzare il nome del mese ad ogni anno. Infatti:

• se si utilizzasse #DATE|nom_mois|unique, i nomi dei mesi sarebbero visualizzati solo nel primo anno.
• se il filtro fosse: #DATE|unique|nom_mois, si visualizzerebbero tutte le date. In effetti, #DATE restituisce una data completa che contiene anche l’ora. C’è quindi un’altissima probabilità che le date complete di due articoli pubblicati lo stesso giorno siano differenti.

Per tali ragioni si mantiene solo il mese e l’anno della data prima di passarla al filtro unique.

È possibile passare un argomento opzionale a questo filtro al fine di distinguere due utilizzi indipendenti del filtro. Per esempio: [(#DATE|affdate_mois_annee|unique{qui})] non avrà alcuna influenza su [(#DATE|affdate_mois_annee|unique{la})].

Filtri di testo

La maggior parte di questi filtri è stata introdotta con la versione [SPIP 1.4]

-  liens_ouvrants trasforma i link di SPIP che mandano a siti esterni in link di tipo "popup", che aprono una nuova finestra; è l’equivalente di target=blank dell’HTML. N.B.: gli sviluppatori di SPIP ritengono che in generale ciò siai una scortesia, perché chi naviga in Internet sa bene se vuole aprire un’altra finestra o meno – invece questo sistema li obbliga. Ma la richiesta era troppo forte, e abbiamo ceduto ;-)

-  supprimer_numero serve a eliminare il numero di un titolo, se per esempio si vuole ordinare gli articoli {par num titre} ma non mostrare i numeri (poiché servono solo a ordinare gli articoli). Il formato dei prefissi numerici è "XX. titolo", dove XX è un numero a n cifre (illimitato).

-  PtoBR trasforma i salti di paragrafo in semplici ritorni a capo, il che permette di “comprimere" un’impaginazione, per esempio all’interno di un sommario

-  taille_en_octets permette di trasformare un numero di byte (octets in francese) (25678906) in una stringa di caratteri più esplicita ("24,4 Mb").

-  supprimer_tags è un modo semplice e brutale di eliminare tutti i <...>

-  textebrut parente del filtro supprimer_tags, ma agisce in maniera più raffinata, trasformando soprattutto i paragrafi e i <br> in interlinea, e gli spazi indivisibili in spazi normali. Utilizzato, per esempio, per fare una descrizione META a partire da #DESCRIPTIF: [<meta name='descrizione' content='(#DESCRIPTIF|textebrut)'>]

-  texte_backend può essere utilizzato per trasformare un testo e renderlo compatibile con un flusso xml. Questo filtro è utilizzato, ad esempio, nel modello backend.html che genera il flusso RSS del sito.

-  couper taglia un testo dopo un certo numero di caratteri. Esso tenta di non tagliare le parole e rimuove la formattazione applicata al testo. Se il testo è troppo lungo alla fine verranno aggiunti i puntini di sospensione «(...)». La lunghezza predefinita è di 50 caratteri. Tuttavia, è possibile specificare un’altra lunghezza passando un parametro al filtro, per esempio: [(#TEXTE|couper{80})].

Filtri di test

-  [SPIP 1.6] introduce il filtro |sinon, che indica quel che si deve visualizzare nel caso l’elemento «filtrato» sia vuoto: così [(#TEXTE|sinon{"nessun testo"})] visualizza il testo; se esso è vuoto visualizza «nessun testo».

-  [SPIP 1.8] introduce il filtro |?{se sì,altrimenti} che è una versione evoluta di |sinon. Esso prende uno o due parametri:

• se sì è il valore da visualizzare al posto dell’elemento filtrato se quest’ultimo non è vuoto.
• altrimenti è opzionale. Rappresenta il valore da visualizzare se l’elemento filtrato è vuoto. [(#TEXTE|?{#TEXTE,"nessun testo"})] è l’equivalente dell’esempio dato per il filtro |sinon.

-  [SPIP 1.8] introduce un set di filtri per fare confronti con valori:

• |=={valore} e |!={valore} permettono di verificare, rispettivamente, l’uguaglianza o la non uguaglianza tra l’elemento filtrato e il valore. Per esempio: <li [(#TITRE|=={editoriale}) id="editoriale">]#TITRE</li>
• |>{valore}, |>={valore}, |<{valore} et |<={valore} confrontano l’elemento filtrato (che deve essere un numero) con un valore numerico.
  Per esempio:

  [(#TOTAL_BOUCLE) [(#TOTAL_BOUCLE|>{1}|?{'articoli','articolo'})] in questa rubrica.]
  

  Nota Bene: In generale, tutti gli operatori di confronto del PHP possono essere utilizzati come filtri in [SPIP 1.8].

Filtri dei logo

-  fichier [SPIP 1.4]. Assegnato a un logo, questo filtro permette di recuperare direttamente il nome del file corrispondente al logo.

-  ||autres filtres Contrariamente alle versioni precedenti, [SPIP 1.4] permette di inviare dei filtri "personalizzati" sui logo: la logica è un po’ ostica, poiché deve rispettare la compatibilità con la versione SPIP 1.3. L’analisi si svolge nella maniera seguente:

• se il primo "filtro" non è un allineamento, SPIP considera che si tratti di una URL e fa un link del logo verso questo indirizzo;
• se il primo filtro è un allineamento, SPIP considera che il secondo "filtro" è una URL;
• i filtri seguenti sono veri filtri nel senso corrente (compresi i filtri "personalizzati" dichiarati in mes_fonctions.php3;
• per applicare un filtro qualsiasi senza mettere l’URL, è necessario mettere due barre. Per esempio: <?php $logo = '[(#LOGO_RUBRIQUE||texte_script)]'; ?> permette di recuperare il logo nella variabile PHP $logo, per un’analisi ulteriore (vedi sotto per il significato di |texte_script).

-  [SPIP 1.8] introduce i filtri hauteur e largeur che restituiscono le informazioni sulla dimensione (ovvero, Altezza e Larghezza) dell’elemento filtrato se esso è un’immagine.

È poco utile applicare questi filtri direttamente a un logo di documento poiché per i documenti ci sono già a disposizione i segnaposti #HAUTEUR e #LARGEUR. Al contrario, è possibile applicare tali filtri dopo il filtro reduire_image per conoscere la dimensione esatta dell’immagine ridotta.

Più in generale, è possibile applicarli su qualsiasi segnaposto (o filtro) che restituisce un tag HTML <img ...>.

-  reduire_image{larghezza,altezza} :SP<font color="yellow">IP 1.7.1 introduce il filtro reduire_image, che permette di forzare una dimensione massima di visualizzazione delle immagini e dei logo.

Questo filtro si utilizza per esempio su un logo dell’articolo nel modo seguente:

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

In questo esempio, il logo dell’articolo appare allineato a destra, con una dimensione massima di 130 pixel.

Dalla versione [SPIP 1.8.2] questo filtro può prendere 2 argomenti: larghezza ed altezza. Se uno dei due argomenti è uguale a 0, SPIP tinene conto solo dell’altro e calcola questa dimensione conservando le proporzioni dell’immagine. Inoltre, questo filtro si applica anche al segnaposto #TEXTE, nel qual caso vengono ridimensionate tutte le immagini che il redattore ha inserito nel testo grazie alle scorciatoie di SPIP. Quindi ad esempio:

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

visualizza tutte le immagini inserite nel corpo del testo con una larghezza massima di 600px. In tal modo non si rovina l’impaginazione ed il redattore non è costretto a ridimensione le immagini prima di farne l’upload.

N.B. Se l’opzione "creazione di miniature" è attivata nella configurazione del sito, questi logo ridotti saranno dei file di immagine specifici calcolati automaticamente dal server (idealmente, con l’estensione GD2 installata sul server), per i formati accettati dal server (con GD2, solitamente, i formati JPG e PNG). Altrimenti, viene visualizzata una versione completa dell’immagine, ma con una dimensione di visualizzazione impostata direttamente in HTML.

Altri filtri

-  traduire_nom_langue si applica al segnaposto #LANG e restituisce la traduzione del codice di lingua dato dal segnaposto (fr, en, it, ecc..) nella stessa lingua.

Nota bene: le traduzioni dei codice vengono effettuate nella lingua rappresentata dal codice e seguono le sue convenzioni di scrittura.

Quindi “fr” sarà tradotto “français” in minuscolo, mentre “es” sarà tradotto “Español” con la maiuscola.

-  alterner{a,b,c} [SPIP 1.8.2] si applica ad un segnaposto numerico (in generale a #COMPTEUR_BOUCLE o #TOTAL_BOUCLE) e visualizza l’argomento corrispondente al valore di questo segnaposto. In questo modo è possibile creare una visualizzazione alternante in un ciclo. Ad esempio, [(#COMPTEUR_BOUCLE|alterner{'white','grey'})] visualizza « white » alla prima iterazione del ciclo, « grey » alla seconda, « white » alla terza, « grey » alla quarta, ecc. Così si può creare una lista di articoli che utilizza un colore differente per le linee pari e dispari:

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

-  inserer_attribut{attributo,valore} [SPIP 1.8.2] consente di aggiungere un attributo html in un segnaposto html creato da SPIP. Ad esempio: [(#LOGO_DOCUMENT|inserer_attribut{'alt',#TITRE})] inserisce l’attributo “alt” con il titolo del documento nel segnaposto “img” del logo.

-  extraire_attribut{attributo} [SPIP 1.8.2] è l’opposto del precedente. Consente di leggere un attributoda un segnaposto html generato da SPIP. Ad esempio, è possibile estrarre il percorso della miniatura generata dal filtro reduire_image: <div style="background: url([(#LOGO_ARTICLE||reduire_image{90}|extraire_attribut{src})]) left;"]>#TEXTE</div>

-  parametre_url{parametro,valore} [SPIP 1.8.2] è un filtro che consente di aggiungere dei parametri in una url generata da un segnaposto di SPIP. Se valore vale ’’ il filtro cancella il parametro dall’url. Se valore non è specificato, il filtro ritorna il valore corrente del parametro. Ad esempio, il segnaposto #SELF restituisce l’url della pagina corrente, quindi:

* [(#SELF|parametre_url{'id_article'})] restituisce l’id_article presente nell’url, * [(#SELF|parametre_url{'id_article','12'})] inserisce nell’url la variabile id_article uguale a 12, * [(#SELF|parametre_url{'id_article',''})] cancella l’id_article presente nell’url.

Si può utilizzare ad esempio per creare dei bottoni per navigare tra i documenti di una pagina:

<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="precedente">
     [(#LOGO_DOCUMENT|reduire_image{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="seguente">
     [(#LOGO_DOCUMENT|reduire_image{70})]
   </a>
 </li>
 </BOUCLE_suivant>
 </ul>
</BOUCLE_actuel>

Filtri tecnici

Questi filtri sono stati introdotti da [SPIP 1.4].

-  entites_html trasforma un testo in entità HTML, che quindi può essere usato in un form, esempio: [<textarea>(#DESCRIPTIF|entites_html)</textarea>]

-  texte_script trasforma qualsiasi campo in una stringa utilizzabile in PHP o Javascript completamente sicura, esempio: <?php $x = '[(#TEXTE|texte_script)]'; ?>. Attenzione: utilizzare il carattere ' e non ": in effetti, nel secondo caso, se il testo contiene il simbolo $, il risultato può essere catastrofico (visualizzazione parziale, visualizzazione di altri dati, il php si pianta, ecc.).

-  attribut_html rende una stringa utilizzabile senza danno come attributo HTML; per esempio, se si vuole aggiungere un testo di roll-over al normale link verso un articolo si utilizzerà:

<a href="#URL_ARTICLE" [ title = "(#DESCRIPTIF|supprimer_tags|attribut_html)" ]>#TITRE</a>.

-  liens_absolus [SPIP 1.8.2] si applica ad un segnaposto testuale e trasforma tutti i link che contiene in link assoluti (con l’url completa del sito). Questo filtro è particolarmente utile per i modelli dei flussi RSS ad esempio.

-  url_absolue [SPIP 1.8.2] funziona come il filtro precedente, ma si applica ad un segnaposto che restituisce una url (ad esempio #URL_ARTICLE).

-  abs_url [SPIP 1.8.2] combina i due filtri precedenti e quindi si può applicare ad un testo o ad un segnaposto che restituisce una url.

Aggiungere le proprie funzioni

I filtri di SPIP sono delle funzioni PHP che ricevono il segnaposto a cui sono applicati come primo parametro e restituiscono un testo da visualizzare. È possibile utilizzare direttamente le funzioni solite di PHP, ma è anche possibile creare le proprie, sul modello:

<?php
function mio_filtro($texte){
    $texte = (un po’ di smanettamento in PHP) ...;
    return $texte;
}
?>

Al fine di non dover modificare i file di SPIP (che rischierebbero di essere cancellati durante un prossimo aggiornamento), è possibile inserire le proprie funzioni personalizzate in un file chiamato mes_fonctions.php3: se SPIP trova un file con questo nome lo include automaticamente.

Per esempio, ARNO* ha sviluppato il filtro enlettres, che non è incluso nella distribuzione standard di SPIP. Questo filtro trasforma un numero scrivendolo in lettere ( [(#DATE|annee|enlettres)] = " due mila due ") ; questo filtro può essere scaricato da http://www.uzine.net/spip_contrib/a... ; per utilizzarlo basterà aggiungerlo al file mes_fonctions.php3.

Filtri con parametri

Dalla versione [SPIP 1.5], è possibile passare dei parametri nei filtri. La sintassi è

[(#SEGNAPOSTO|filtro{arg1, arg2}|...)]

Il filtro deve essere definito nel file mes_fonctions.php3 nella maniera seguente:

function filtro($texte, $arg1='valore di default1', $arg2='valore di default 2')
{
    ....calcoli....
    return (una stringa di caratteri);
}

È altresì possibile chiamare una qualsiasi funzione in PHP, o appoggiarsi alle funzioni definite all’interno di SPIP o nel file mes_fonctions.php3, purché esse rispettino l’ordine degli argomenti (il testo da manipolare deve essere obbligatoriamente il primo argomento). Per esempio, per eliminare i punti alla fine di un testo è possibile scrivere: [(#TEXTE|rtrim{'.?!'})].

Dalla versione [SPIP 1.8], gli argomenti dei filtri possono essere segnaposti (senza codice opzionale né filtri). Per esempio:[(#TOTAL_BOUCLE|=={#COMPTEUR_BOUCLE}|?{'Fine.',''})]

Dalla versione [SPIP 1.8.2] è possibile inserire un segnaposto con notazione estesa come parametro. Ad esempio: [(#DESCRIPTIF|sinon{[(#CHAPO|sinon{#TEXTE}|couper{300})]})]