Lorsque l’on a des éléments de texte et des boucles communs à plusieurs fichiers, on peut vouloir extraire ces éléments des pages où ils se trouvent, les installer dans un fichier séparé, et les appeler depuis les autres squelettes. De cette façon, le code commun est regroupé dans un unique fichier, ce qui facilite notamment les modifications qui concernent plusieurs squelettes d’un seul coup.
On installe ainsi typiquement, dans de tels fichiers séparés appelés depuis de nombreux squelettes, des éléments tels que :
— les déclarations d’entête des pages HTML (appel des javascript, des feuilles de style...),
— les éléments de navigation communs à la plupart des pages (en haut de page, en colonne de gauche...), bannière supérieure (logo, liens vers les crédits du site, la page de contact...),
— un pied de page...
Syntaxe d’inclusion
Les habitués de PHP connaissent la fonction
include, dont le principe est similaire à ce qui est présenté ici.
On peut appeler un squelette depuis un autre squelette grâce à la balise <INCLURE> (on peut aussi utiliser <INCLUDE>, qui est identique). Sa syntaxe générale est :
<INCLURE{fond=squelette, param}>
<INCLURE{fond=squelette, param1,param2}>
<INCLURE{fond=squelette, param1,param2}{param3=#LISTE{valA,valB}}>
Le « squelette » est le nom du fichier (on parle aussi de noisette :) que l’on veut intégrer dans sa page.
Par exemple, imaginons que toutes les pages du site affichent les mêmes informations en bas de page. On regroupe alors le code SPIP et HTML de ce « pied de page » dans un fichier « pied.html ». Il suffit d’ajouter la ligne suivante, à l’endroit voulu, dans chacun des squelettes voulant afficher le bas de page :
<INCLURE{fond=pied}>
Inclusions dépendant du contexte
Certaines inclusions peuvent dépendre du contexte. Par exemple, imaginons un squelette « hierarchie », qui affiche le chemin menant à une rubrique depuis la racine du site ; on appelerait cette page par une URL de la forme : « spip.php?page=hierarchie&id_rubrique=xxx ».
Dans les squelettes voulant afficher la hiérarchie à partir de la rubrique courante, il faut donc indiquer que le paramètre concerné est {id_rubrique} ; si nécessaire, on aura créé une boucle permettant de récupérer le numéro de la rubrique concernée, et on placera le code suivant à l’intérieur de cette boucle :
<INCLURE{fond=hierarchie, id_rubrique}>
Note : dans ce cas, le squelette
hierarchie.htmlcommencera certainement par une boucle rubriques avec le critère{id_rubrique}...
On peut imaginer que, dans certains squelettes, on désire récupérer non pas la hiérarchie en fonction d’une rubrique « variable » (au gré du contexte, par exemple le paramètre passé dans l’URL), mais en fonction d’une rubrique dont on connaît à l’avance le numéro. Pour cela, on peut fixer la valeur du paramètre ainsi :
<INCLURE{fond=hierarchie, id_rubrique=5}>
N.B. Il est possible d’indiquer plusieurs paramètres dans la balise <INCLURE> ; cependant ce cas est très rare en pratique. Evitez d’ajouter des paramètres inutiles, qui rendront le cache moins efficace et votre site plus lent.
N.B. Le fichier inclus étant lui-même un squelette, il disposera donc de sa propre valeur de #CACHE [1]
Transmettre tout le contexte en cours
Le paramètre env permet de transmettre le contexte de compilation du squelette en cours à celui inclus.
<INCLURE{fond=squelette, env}>
Dans un contexte multilingue
Si le multilinguisme de SPIP est activé, il est possible de définir la langue de l’environnement d’un squelette inclus en utilisant le paramètre {lang}.
- S’il n’y a pas de paramètre de langue utilisé, c’est-à-dire sous la forme <INCLURE{fond=pied}>, le squelette inclus est appelé en utilisant la langue par défaut du site ;
- <INCLURE{fond=pied, lang=es}> appelle le squelette en espagnol. Bien sûr, vous pouvez remplacer « es » par le code ISO de la langue souhaitée : en pour l’anglais, fr pour le français, vi pour le vietnamien, etc. (voir : « Internationaliser les squelettes ») ;
- <INCLURE{fond=pied, lang}> appelle le squelette dans la langue courante du contexte d’inclusion.
Il convient de noter que cela rend possible l’utilisation des codes de fichiers de langue dans les squelettes inclus (voir : « Internationaliser les squelettes »).
Les squelettes inclus supportent les mêmes mécanismes de sélection par langue que les squelettes de « premier niveau ». En d’autres termes les squelettes inclus (ici pied.html) peuvent être déterminés par rapport à une certaine langue (pied.es.html, par exemple) de la même manière que tout autre squelette. Encore une fois, voir « Internationaliser les squelettes » pour plus de détails.
#INCLURE en statique
Avec cette balise, il devient possible d’appliquer des filtres sur le squelette inclus :
[(#INCLURE{fond=lettre, env}|version_texte)]
De plus l’inclusion est réalisée lors du calcul du squelette, et son résultat est stocké dans le cache de la page appelante. Avec ce système, on ne peut plus gérer une durée de vie (#CACHE{}) réduite pour un squelette inclus.
Attention : le résultat de l’inclusion étant stocké en cache, il ne faut donc pas que l’#INCLURE contienne d’éléments dynamiques, en particulier pas de balise #FORMULAIRE_XYZ.
<INCLURE{fond=..}> et [(#INCLURE{fond=..})] ont donc des fonctionnements différents :
- avec
<INCLURE{fond=..}>chaque squelette inclus a un cache indépendant. Autrement dit, cette syntaxe provoque l’inclusion des pages à chaque visite d’un internaute, que celle-ci concerne une page déjà en cache ou non. - avec
[(#INCLURE{fond=..})], la page principale appelante contient, en cache, l’intégralité du code généré, et les fichiers inclus n’ont pas de cache séparé.
Remarque : Par défaut, 3 variables d’environnement sont automatiquement transmises à l’évaluation de l’inclusion :
lang, date et date_redac. On peut éviter ces ajouts à l’environnement en utilisant l’étoile : #INCLURE*. Il devient alors possible d’utiliser des critères conditionnels sur ces variables dans le squelette inclus.
<INCLURE> et {doublons}
Il existe un critère de boucle {doublons}. Or, si on utilise un <INCLURE> dans un squelette, les doublons mémorisés ne sont pas transmis au squelette inclus.
Il est possible de contourner ce problème. Il suffit pour cela de rajouter le paramètre {doublons}> à l’appel du squelette à inclure. Par exemple <INCLURE{fond=mapage, doublons}>.
Notons toutefois que les doublons sélectionnés dans le squelette inclus ne "remontent" pas dans le squelette incluant.
<INCLURE> et ajax
Il est possible d’utiliser facilement la technologie ajax, qui permet de cliquer sur un lien et de ne rafraichir dans la page que la zone qui changerait si on ré-affichait toute la page avec les nouveaux paramètres. Pour plus de détails, voir l’article `ajax` pour les `inclure`.
#INCLURE un fichier qui n’est pas un squelette
La balise #INCLURE permet également d’inclure un fichier qui n’est pas un squelette : pour cela, il faut simplement indiquer le fichier inclus directement en premier argument, en omettant le "fond=" qui est utilisé pour inclure des squelettes. Le fichier est alors lu et son contenu est restitué dans le contexte appelant sans être interprété par SPIP.
Exemple d’usages dans différents fichiers SPIP ou plugins :
- dans sedna.js.html : [(#INCLURE{javascript/sedna.js}|...]
- dans adminer.html : [<style type="text/css">(#INCLURE{adminer.css}|compacte{css})</style>]
- dans portfolio_document.html : [(#INCLURE{javascript/medias_edit.js}|compacte{js})]
- dans gis.js.html : [(#INCLURE{lib/leaflet/dist/leaflet-src.js})]
La plupart de ces usages concernent des fichiers javascript ou CSS, mais il est possible d’inclure d’autres types de fichiers :
- dans favicon.ico.html : [(#INCLURE{favicon.ico}|sinon{#INCLURE{spip.ico}})]
Voir aussi
- `ajax` pour les `inclure`
- Les aides au débuggage de squelettes et plus particulièrement l’appel de « var_mode=inclure »
Sur Programmer.spip.net