Avendo tratto ispirazione dai modelli di Wikipedia, il sistema di moduli offre nuove possibilità ai webmaster e ai redattori.
I moduli sono un’estensione delle classiche scorciatoie <img1> e <doc1>. Attualmente queste scorciatoie corrispondono ai moduli dist/modeles/img.html e dist/modeles/doc.html.
La sintassi è stata ampliata ed è possibile specificare, oltre all’allineamento (<img1|left>, <img1|right> o <img1|center>), una classe più generica che può corrispondere o a un modello di layout preciso, se esiste, o a una classe CSS (<img1|classe> andrà a cercare il modulo modeles/img_classe.html, se tale file è presente, altrimenti utilizzerà il modulo modeles/img.html, ma con un parametro class="classe").
Tuttavia i moduli non si limitano alle sole immagini e ai soli documenti; è anche possibile creare nuove scorciatoie sotto forma di <modulo1>, assgiungendo semplicemente un modello di layout nella cartella modeles/ nella propria cartella di modelli!
In mancanza di un modulo corrispondente alla scorciatoia indicata (per esempio,
<breve1>), il codice di gestione dei moduli di SPIP controlla se esso conosce l’oggetto richiesto (in questo caso,breve), e se tale oggetto ha un indirizzo URL.<breve1> In tal caso (verificato qui, poiché le brevi sono conosciute dal sistema e dispongono di una funzione di URL), SPIP sostituisce la scorciatoia
<breve1>da un piccolo riquadro mobile, con un link verso la breve e la visualizzazioe del titolo, come se fosse stato indicato con[->breve1].Se invece l’oggetto non è conosciuto dal sistema, SPIP lascia intatta la scorciatoia affinché sia gestita in seguito (da parte di un plugin o di un filtro personalizzato), oppure viene semplicemente ignorata.
D’altronde, è possibile passare dei parametri supplementari ai moduli (come veniva fatto per i documenti flash « embed », con la scorciatoia <emb1|autostart=true>). La sintassi è generalizzata e accetta anche codice HTML, come nell’esempio seguente:
<son19|couleur=#ff0000
|legende=Il grande <i>Conte Benso di Cavour</i>
|photo=12>
che potrebbe chiamare un modulo modeles/son.html, che sfrutterebbe i parametri per visualizzare la foto numero 12 in una cornice di colore #ff0000, e con una legenda con parole in corsivo.
Utilizzi multipli
C’è ancora molto da esplorare per quanto riguarda le applicazioni possibili dei moduli. Di seguito diamo alcune idee a cui abbiamo pensato. Se ne trovate altre non esitate a condividerle proponendo i vostri moduli su SPIP Zone/SPIP Contrib’, che hanno una rubrica dedicata a questo scopo.
- Cambiare l’aspetto delle scorciatoie dei documenti. Questa funzionalità è stata richiesta spesso, tuttavia fino ad ora era difficile da attuare perché bisognava modificare il codice PHP nei file del core di SPIP. Adesso è sufficiente ricopiare dist/modeles/img.html in una sotto-cartella modeles/ nella propria cartella di modelli di layout per poi modificare questo file. Lo stesso dicasi per le scorciatoie <doc1> e <emb1>, benché quest’ultimo sia d’una complessità tale che può spaventare...
Attenzione: non lanciatevi nella modifica dei moduli per apportare modifiche minime di queste scorciatoie — spesso è più facile modificare gli stili spip_documents_xx partendo dai file CSS del proprio sito.
- Emettere suoni con un player flash. Un modulo modeles/suono_player.html potrebbe dare una scorciatoia del tipo <suono12|player>.
- Associare un sito a un articolo. Aggiungendo nei propri modelli di layout un modulo modeles/site_box.html, si crea immediatamente una nuova scorciatoia <site1|box>. Si scive quindi il modulo (con i cicli classici) in modo da fargli visualizzare il nome del sito seguito da link verso gli ultimi 3 articoli in syndication in un riquadro mobile a destra, ottenendo così un box di informazioni facile da inserire in un articolo. Un parametro potrebbe indicare il numero di articoli da visualizzare, la presenza o meno dei riassunti, ecc.
- Visualizzare una immagine timbrata. Dopo che si sa come fare un modello di layout che mostra una foto sotto forma di un timbro postale (vedi Un site dûment timbré), è sufficiente chiamarlo modeles/timbre.html per creare la scorciatoia <timbre12>. Con, perché no?, dei parametri di dimensione, di colore, di scelta dell’inchiostro, ecc. [1].
Naturalmente è possibile immaginare allo stesso modo dei moduli che visualizzano le immagini in seppia, in versione ridotta, ecc. Scommettiamo che tra breve saranno disponibili numerosi plugin per queste funzionalità.
- Creare un articolo composito. Supponiamo che si abbia bisogno di un articolo composto dall’«introduzione» dell’articolo 1 e dal testo dell’articolo 2. Nulla di più semplice: si creano due moduli che rinviano l’uno all’introduzione dell’articolo richiesto e l’altro al testo di tale articolo, e nel nostro articolo composito si indica nel campo Introduzione: <article1|chapo>, e nel campo Testo: <article2|texte>. E’ possibile aggiungere filtri, segnaposti e hack a volontà...
- Inserire un articolo in più rubriche. Programmando i moduli <article1|chapo>, <article1|texte> ecc., diventa concepibile mettere una copia di un articolo in un altro articolo, senza duplicare i dati. In tal modo si ottiene un articolo « fantasma » che è possibile inserire in una nuova rubrica (con, inoltre, la possibilità di dargli un titolo diverso o di aggiungergli altri elementi).
- Fare un sondaggio. Il plugin Forms, che permette di creare dei form e di utilizzarli dentro gli articoli con la scorciatoia <form1>, è stato riscritto partendo dai moduli.
- Visualizzare una citazione a caso. Se si sono messe delle citazioni nelle brevi, una scorciatoia <citation|aleatoire> può estrarne una a caso (criterio {par hasard}{0,1} su un ciclo di brevi), e visualizzarla in un riquadro mobile a lato del paragrafo corrente.
- Inserire un documento in un’altra lingua diversa dalla lingua dell’articolo. I moduli funzionano come le inclusioni, il parametro lang=xx è sempre disponibile. Se uno dei propri documenti è bilingue (per esempio con un «blocco multi» nella descrizione), potete visualizzare la descrizione in esperanto, in un articolo in giapponese, chiamando <doc1|left|lang=eo>. Se il modello di layout del modulo contiene stringhe di lingua queste verranno interpretate, eventualmente, nella lingua passata dal parametro.
- Visualizzare un grafico. Si passa una tabella di dati al modulo, che si fa carico di creare il grafico e di inserirlo nel flusso del testo.
- Un titolo di paragrafo sotto forma di immagine. Perché non immaginare una scorciatoia <imagetypo|texte=Mio titolo di paragrafo>?
Parametri a vagonate
La sintassi delle scorciatoie dei moduli è nel formato <modulo12>, <modulo|parametro1=coso|parametro2=cosa> o <modulo12|allineamento|parametro1=ecc>. I parametri possono essere composti da codice HTML e da scorciatoie di SPIP (a condizione, naturalmente, che sia stato previsto che i moduli chiamati possano manipolarli).
Si noterà che, per evitare qualsiasi conflitto con i tag HTML, un modulo non può essere chiamato da una scorciatoia del tipo <modulo>, che non contiene né cifre né il simbolo |.
I parametri possono estendersi su più righe, il che permette di scrivere un codice in maniera leggibile:
<modulo 10
|paese=Germania
|popolazione=82000000
|superficie=357027
|ordine=63
|inno=<i>Das Lied der Deutschen</i>
|url=http://fr.wikipedia.org/wiki/Allemagne
>Il modello di layout preleva tutti questi parametri nel segnaposto #ENV, quindi #ENV{popolazione} ha valore 82000000. Questo segnaposto è a prova di iniezioni di javascript, se si desidera permettere di inserire un codice HTML in un parametro conviene utilizzare il formato #ENV*{inno}; se poi si desidera applicare la tipografia di SPIP, è possibile impiegare [(#ENV*{inno}|typo)] o [(#ENV*{inno}|propre)].
Il parametro principale (qui, 10), viene passato in due forme: #ENV{id}=10, e #ENV{id_modele}=10. Ciò permette di accedere, per un modulo chiamato da <article3|chapo>, all’introduzione dell’articolo 3 scrivendo:
<BOUCLE_a(ARTICLES){id_article}>#CHAPO</BOUCLE_a>
oppure alle brevi collegate alla parola chiave numero 3, mediante;
<BOUCLE_b(BREVES){id_mot=#ENV{id}}>#TITRE</BOUCLE_b>
Come si può vedere, ogni modulo dovrà avere la propria documentazione poiché la scorciatoia non indica nulla riguardo alla gestione degli elementi passati dalla scorciatoia.
Un possibile uso nei modelli di layout
I moduli non sono limitati a scorciatoie negli articoli. E’ possibile chiamarli da un modello di layout utilizzando il segnaposto #MODELE{modele} oppure [(#MODELE{modele}{p1=coso,p2=cosa}{p3=ecc}|filtro...)]; tuttavia ciò è una novità minore poiché è equivalente a una inclusione (statica) di modelli di layout (ugualmente permessa dal nuovo segnaposto #INCLURE).
I moduli di default
SPIP viene distribuito con i seguenti moduli:
- img, doc, emb,
- article_mots e article_traductions, che danno rispettivamente l’elenco delle parole chiave associate a un articolo e delle sue traduzioni (scorciatoie: <article1|traductions> e <article1|mots>, ma questi moduli vengono chiamati anche dal modello di layout tramite dist/article.html);
- lesauteurs, che definisce il prodotto del segnaposto #LESAUTEURS, ma non può essere chiamato come una scorciatoia;
- e una serie di moduli per la paginazione (vedi Il sistema di paginazione).
Alcuni consigli per scrivere un modulo
Consigliamo di cominciare con il riflettere sulla sintassi che si vuole adottare: questo modulo è legato a un articolo specifico? In caso affermativo si partira con un <article1|xxx>.
Dopo aver stabilito la sintassi si crea il file modeles/article_xxx.html, e si scrive semplicemente il segnaposto seguente: #ENV. Poi, in un articolo di test, si digita la nostra scorciatoia <article1|xxx|param=x...>; si vede quindi (in un formato un po’ criptico, si tratta di una tabella serializzata) l’ambiente come viene passato al modulo. Per esempio, si può distinguere il nostro identificativo di articolo (col nome #ENV{id} e #ENV{id_article}.
Successivamente si può cominciare a scrivere il modello di layout del nostro frammento di pagina: <BOUCLE_x(ARTICLES){id_article}> oppure <BOUCLE_x(ARTICLES){id_article=#ENV{id}}>. E si parte...
Al fine di completare il nostro modulo è necessario verificare le sintassi <article1|xxx|left> e [<article1|xxx>->www.spip.net].
Nel primo caso, è il parametro align=left che viene passato al modulo (ed è auspicabile che il modulo si allinea sul lato richiesto).
Nel secondo caso, il link viene passato in un parametro lien=http://www.spip.net, e la classe del link in lien_classe=spip_out. Si raccomanda di prendere in considerazione l’URL richiesto trasformandolo in link, da qualche parte nel modulo (per esempio sul titolo o sull’icona); in tal caso, è necessario aggiungere nel primo tag HTML del modulo un class="spip_lien_ok", che segnalerà al codice che gestisce il modulo che il link è stato preso in considerazione (in mancanza di esso il codice di gestione aggiungerà un <a href=...>...</a> intorno al modulo prodotto.
Per quel che riguarda i parametri, il segnaposto #ENV{x} è stato concepito in modo di evitare qualsiasi iniezione di codice HTML o di javascript non desiderato. In un modulo si può desiderare di autorizzare l’HTML nei parametri: in tal caso si deve utilizzare #ENV*{x} per recuperare i dati e eventualmente i filtri tramite |propre o |typo, a seconda del tipo di dati (testo che può essere di diversi paragrafi o anche di una sola riga).
Per quanto riguarda la programmazione, si raccomanda di concepire i propri moduli tutto nei cicli, senza alcun codice PHP né ciclo dinamico. Tuttavia va notato: in un modulo che comprende del codice PHP è il risultato del calcolo che viene messo nella cache, e non lo script stesso (come nel caso dei modelli di layout).