Inspiré des modèles de Wikipédia, le système des modèles offre de nouvelles capacités aux webmestres et aux rédacteurs.
Les modèles sont une extension des classiques raccourcis <img1> et <doc1>. Ceux-ci correspondent désormais aux modèles /plugins-dist/medias/modeles/img.html et /plugins-dist/medias/modeles/doc.html.
Leur syntaxe a été étendue, et il est possible de spécifier, outre l’alignement (<img1|left>, <img1|right> ou <img1|center>), une classe plus générique, qui soit correspond à un squelette précis, s’il existe, soit à une classe CSS (<img1|classe> ira chercher le modele modeles/img_classe.html, si ce fichier existe, sinon utilisera le modèle modeles/img.html, mais avec un paramètre class="classe").
Mais les modèles ne se limitent pas aux images et documents ; il est ainsi possible de créer de nouveaux raccourcis de la forme <modele1>, simplement en ajoutant un squelette dans le répertoire modeles/ de son dossier de squelettes !
On prendra soin de nommer son fichier en lettres minuscules (« bas de casse »). Pour éviter les différenciations sur certains systèmes serveur entre le_fichier01.html et Le_Fichier01.html, SPIP ne recherchera que des fichiers nommés en minuscules.
En l’absence de tout modèle correspondant au raccourci indiqué (par exemple,
<breve1>), le gestionnaire de modèle de SPIP regarde s’il connaît l’objet demandé (ici,breve), et si ce dernier a une URL.<breve1> Dans ce cas (vérifié ici, car les brèves sont connues du système et disposent d’une fonction d’URL), SPIP remplace le raccourci
<breve1>par un petit encadré flottant, avec un lien vers la brève, et l’affichage de son titre, comme si l’on avait indiqué[->breve1].Si l’objet n’est pas connu, SPIP laisse le raccourci intact, pour qu’il soit éventuellement traité par la suite (par un plugin ou un filtre supplémentaire), ou tout simplement ignoré.
Il est par ailleurs possible de passer des paramètres supplémentaires aux modèles. La syntaxe en est généralisée et accepte même du HTML, comme dans l’exemple :
<son19|couleur=#ff0000
|legende=Le grand <i>Count Basie</i>
|photo=12>
qui pourrait appeler un modèle modeles/son.html, lequel exploiterait les paramètres pour afficher la photo numéro 12, dans un cadre de couleur #ff0000, avec une légende comportant des mots en italique.
Des usages multiples
- Changer l’aspect des raccourcis de documents. Il suffit de recopier plugins-dist/medias/modeles/img.html dans un sous-répertoire modeles/ de son répertoire de squelettes, et de modifier ce fichier. Idem pour les raccourcis <doc1> et <emb1>, bien que ce dernier soit d’une complexité qui peut rebuter...
Attention : ne vous lancez pas dans la modification des modèles pour des modifications mineures du rendu de ces raccourcis — il est souvent plus facile de modifier les styles spip_documents_xx à partir des fichiers CSS de votre site.
- Afficher un tableau CSV (Excel). Il suffit de charger le fichier, puis de l’appeler avec ainsi <emb12> pour afficher les données du fichier CSV sous forme de tableau HTML !
- Associer un site à un article. En ajoutant dans ses squelettes un modèle modeles/site_box.html, on crée immédiatement un nouveau raccourci <site1|box>. On écrit alors le modèle (avec des boucles classiques) de manière à lui faire afficher le nom du site, suivi de liens vers les 3 derniers articles syndiqués, dans une boîte flottant sur la droite, et voici une infobox facile à placer dans un article. Un paramètre pourrait indiquer le nombre d’articles à afficher, la présence ou non de résumés, etc.
- Afficher une image timbrée. Une fois qu’on sait faire un squelette qui affiche une photo sous forme de timbre-poste (voir Un site dûment timbré), il suffit de le nommer modeles/timbre.html pour créer le raccourci <timbre12>. Avec, pourquoi pas, des paramètres de taille, de couleur, de choix du tampon, etc [1].
Bien entendu on peut imaginer de la même façon des modèles affichant les images en sépia, en version réduite, etc. Gageons que tout cela sera rapidement disponible sous forme de plugins.
- Créer un article composite. Supposons qu’on ait besoin d’un article composé du « chapo » de l’article 1 et du texte de l’article 2. Rien de plus simple : on crée deux modèles, qui renvoient tout simplement, pour l’un, le chapo de l’article demandé, pour l’autre son texte, et dans notre article composite on indique, dans le champ chapo : <article1|chapo>, et dans le champ texte : <article2|texte>. On peut y ajouter filtres, balises et bidouilles à volonté...
- Installer un article dans plusieurs rubriques. En programmant des modèles <article1|chapo>, <article1|texte> etc, il devient envisageable de mettre une copie d’un article dans un autre article, sans dupliquer les données. On obtient ainsi un article « fantôme » qu’on peut installer dans une nouvelle rubrique (avec, en plus, la possibilité de le titrer différement ou de lui ajouter des éléments).
- Faire un sondage. Le plugin Formidable, qui permet de créer des formulaires et de les exploiter dans des articles avec le raccourci <formulaire|formidable|id=34>, a été réécrit à partir des modèles.
- Afficher une citation aléatoire. Si on a mis des citations dans ses brèves, un raccourci <citation|aleatoire> peut en extraire une au hasard (critère {par hasard}{0,1} sur une boucle de brèves), et l’afficher dans un encadré flottant à côté du paragraphe courant.
- Insérer un document dans une autre langue que la langue de l’article. Les modèles fonctionnant comme des inclusions, le paramètre lang=xx y est toujours disponible. Si l’un de vos documents est bilingue (par exemple avec un « bloc multi » dans le descriptif), vous pouvez afficher le descriptif en espéranto, dans un article en japonais, en appelant <doc1|left|lang=eo>. Si le squelette du modèle contient des chaînes de langue, elles seront interprétées, le cas échéant, dans la langue passée en paramètre.
- Afficher un graphique. On passe une table de données au modèle, qui se débrouille ensuite pour créer le graphique et l’insérer dans le flux de texte.
- Un intertitre sous forme d’image. Pourquoi ne pas envisager un raccourci <imagetypo|texte=Mon intertitre> ?
En pratique
Pour éviter toute collision avec les balises HTML, un modèle ne peut pas être appelé par un raccourci comme <modele> !
Pour appeler un modèle simple sans paramètre il faut nécessairement :
- soit lui affecter un identifiant numérique :
<le_modele1>; - soit faire suivre son nom d’un pipe
|:<le_modele|>)
Dans le premier cas, l’identifiant passé sera récupérable à l’intérieur du squelette le_modele.html avec #ENV{id} ou encore #ENV{id_le_modele} (qui vaudront donc « 1 » dans notre exemple) ;
Dans le second cas #ENV{id} comme #ENV{id_le_modele} vaudront respectivement « 0 » (zéro).
Des paramètres à foison
La syntaxe des raccourcis de modèles est de la forme
-
<modele12> -
<modele|parametre1=valeur|parametre2=valeur> -
<modele12|filtre|parametre1=valeur>.
Les paramètres peuvent être composés de HTML et de raccourcis SPIP (à condition, bien sûr, que les modèles appelés aient prévu de les traiter).
Les paramètres peuvent s’étendre sur plusieurs lignes, ce qui permet l’écriture relativement aérée :
<modele 10
|pays=Allemagne
|population=82000000
|superficie=357027
|classement=63
|hymne=<i>Das Lied der Deutschen</i>
|url=http://fr.wikipedia.org/wiki/Allemagne
>
Le squelette récupère tous ces paramètres dans la balise #ENV, ainsi #ENV{population} vaut 82000000. Cette balise étant sécurisée contre toute injection de javascript, si on veut permettre du HTML dans un paramètre, il convient d’utiliser la notation #ENV*{hymne} ; si l’on veut en plus appliquer la typographie de SPIP, on peut employer [(#ENV*{hymne}|typo)] ou [(#ENV*{hymne}|propre)].
Le paramètre principal (ici, 10), est passé sous deux formes : #ENV{id}=10, et #ENV{id_modele}=10. Ce qui permet d’accéder, pour un modèle appelé par <article3|chapo>, au chapo de l’article 3 en faisant :
<BOUCLE_a(ARTICLES){id_article}>#CHAPO</BOUCLE_a>
ou bien aux brèves liées au mot-clé numéro 3, par ;
<BOUCLE_b(BREVES){id_mot=#ENV{id}}>#TITRE</BOUCLE_b>
Comme on le voit, chaque modèle devra avoir sa propre documentation, car le raccourci n’indique rien en lui-même sur l’exploitation faite des éléments passés par le raccourci.
Un emploi possible dans les squelettes
Les modèles ne sont pas limités à des raccourcis dans les articles. Il est possible de les appeler depuis un squelette, en utilisant la balise #MODELE{modele}.
Exemple :
[(#MODELE{modele, p1=truc, p2=chose, p3=etc}|filtre...)]
Note : c’est équivalent à une inclusion (statique) de squelette également permise par la balise #INCLURE. Cet inclusion étant statique (= stockée en cache) on veillera à ne pas mettre d’éléments dynamiques dans un modèle, en particulier pas de balises #FORMULAIRE_XYZ.
Les modèles par défaut
SPIP est livré avec les modèles suivants :
- img, doc, emb,
- article_mots et article_traductions, qui donnent respectivement la liste des mots-clés associés à un article, et de ses traductions (raccourcis : <article1|mots> et <article1|traductions>, mais ces modèles sont aussi appelés par le squelette par dist/article.html) ;
- lesauteurs, qui définit le produit de la balise #LESAUTEURS, mais ne peut pas être appelé comme un raccourci ;
- et une série de modèles de pagination (voir Le système de pagination).
Les formulaires
Il est également possible d’appeler les formulaires en tant que modèles insérés dans un contenu éditorial.
Exemple :
<formulaire|login>
Quelques conseils pour écrire un modèle
Il est conseillé de commencer par réfléchir à la syntaxe que l’on veut adopter : ce modèle est-il lié à un article précis ? Si oui, on partira sur un <article1|xxx>.
Une fois cette syntaxe établie, on crée le fichier modeles/article_xxx.html, et on y entre simplement la balise suivante : #ENV. Puis, dans un article de test, on tape notre raccourci <article1|xxx|param=x...> ; on voit alors (sous une forme un peu cryptique, il s’agit d’un tableau sérialisé) l’environnement tel qu’il est passé au modèle. On peut par exemple y distinguer notre identifiant d’article (sous le nom #ENV{id} et #ENV{id_article}).
Ensuite on peut commencer à entrer le squelette de notre fragment de page :
<BOUCLE_x(ARTICLES){id_article}>
ou
<BOUCLE_x(ARTICLES){id_article=#ENV{id}}>
. Et c’est parti...
Pour que notre modèle soit complet, il faut essayer les syntaxes <article1|xxx|left> et [<article1|xxx>->www.spip.net].
Dans le premier cas, c’est le paramètre align=left qui est passé au modèle (et il est souhaitable que le modèle s’aligne alors du côté demandé).
Dans le second cas, le lien est passé dans un paramètre lien=http://www.spip.net, et la classe du lien dans lien_class=spip_out. Il est recommandé de prendre en compte l’url demandée, en la transformant en lien, quelque part dans le modèle (par exemple sur le titre ou l’icone) ; dans ce cas, il faut ajouter dans la première balise HTML du modèle une class="spip_lien_ok", qui signalera au gestionnaire de modèle que le lien a été pris en compte (faute de quoi le gestionnaire ajoutera un <a href=...>...</a> autour du modèle produit.
En ce qui concerne les paramètres, la balise #ENV{x} a été conçue de manière à éviter toute injection de HTML ou de javascript non désirée. Dans un modèle, on peut souhaiter autoriser le HTML dans les paramètres : il faut alors utiliser #ENV*{x} pour récupérer les données, et éventuellement les filtrer par |propre ou |typo, selon le type de données (texte pouvant comporter plusieurs paragraphes, ou simple ligne de texte).
Sur le plan de la programmation, il est recommandé de concevoir ses modèles tout en boucles, sans aucun code php ni balise dynamique. A noter toutefois : dans un modèle comportant du php, c’est le résultat du calcul qui est mis en cache, et non le script lui-même (comme c’est le cas avec les squelettes).
Voir aussi
- <INCLURE> d’autres squelettes
- La balise #ENV
Lors du déploiement de SPIP 4.0, un gros travail a été fait sur les documents et logos. Retrouver les explications détaillées des changements ici :