Coder ses squelettes avec des INCLURE

I. INTRODUCTION

La documentation officielle de SPIP :

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.

... Lire la suite ...

II. DÉBUTER AVEC LES INCLURES

Indispensable pour prendre un bon départ, et maîtriser les bases.
Cette section (II.) présente la gestion des INCLURES selon l’ancienne méthode. La troisième section présente la gestion des INCLURES telle qu’elle est utilisé aujourd’hui.

II.1 En pratique : Créer son premier INCLURE

Nous allons créer ici un premier INCLURE ...

Dans le dossier contenant vos squelettes, il vous suffit de créer deux fichiers :

inc_entete.php3 et inc_entete.html

Le fichier inc_entete.php3 doit contenir

<?php
$fond = "inc_entete";
$delais = 24*3600;
include ("inc-public.php3");
?>

I
et le fichier inc_entete.html lui contient (par exemple)

Mon premier inclure ... Le fichier html peut contenir des boucles spip, du php etc ...

Puis par exemple dans votre fichier article.html, il vous suffit de placer le code :

<INCLURE(inc_entete.php3)>

Maintenant, charger votre page article.html depuis votre navigateur internet, recalculer éventuellement cette page, vous devriez voir apparaître « Mon premier inclure ... Le fichier html peut contenir des boucles spip, du php etc ... » ...

Vous avez réalisé votre premier INCLURE.

II.2 Application n°1 : INCLURE la gestion des feuilles de style

Dans chacun de vos fichiers html, vous avez une ligne qui fait un appel à vos feuilles de style CSS.

<link rel="stylesheet" type="text/css" href="#DOSSIER_SQUELETTE/feuille_de_style.css" />

Ainsi, dans vos fichiers article.html , rubrique.html , auteur.html etc. il y a une ligne contenant cet inclusion html à la feuille de style.

Dans chacun de vos fichier, remplacer cette ligne par :

<INCLURE(inc_css.php3)>

puis créer le couple inc_css.php3 et inc_css.html .

inc_css.php3 contient alors

<?php
$fond = "inc_css";
$delais = 24*3600;
include ("inc-public.php3");
?>

et inc_css.html contient :

<link rel="stylesheet" type="text/css" href="#DOSSIER_SQUELETTE/feuille_de_style.css" />

Désormais, vos feuilles de styles sont gérés par le fichier inc_css.html , et si vous voulez modifier l’accès à votre feuilles de style (par exemple son nom du fichier, ou son chemin), il vous suffit de modifier un seul fichier, le fichier inc_css.html .

II.3 Explications complémentaires

A ce stade du tutorial, il est important de revenir sur quelques points importants laissés délibérément en suspend.

Le nom des fichiers inclus : Le nom des exemples de fichier inclus précédemment étudiés commence toujours par inc_, il s’agit là d’une disposition pratique non obligatoire, mais qui permet de clarifier le statut de chaque fichier. Ce n’est pas obligatoire, mais fortement conseillé.

Gestion du cache : $delais permet de gérer le cache. Vous pouvez modifier ce paramètre, mais il est conseillé de le laisser à 24*3600 sauf cas spécifiques.

Le nom du fichier .php3 et celui du .html peuvent être différents ...

Aussi il est possible de faire :

<INCLURE(inc_la_tete.php3)>

Avec inc_la_tete.php3 contenant :

<?php
$fond = "inc_a_toto";
$delais = 24*3600;
include ("inc-public.php3");
?>

Et inc_a_toto.html contenant :

bla bla quelconque ...

Mais ce dernier cas étant plus compliqué, et son utilité plus subtile, on ne l’utilisera pas dans la suite de nos exemples.

IMPORTANT :
1. Dans la suite du tutorial (uniquement pour la section II.) , lorsqu’il sera marqué « Créer le fichier inc_bidule.html  » il est sous entendu que vous devrez aussi créer le fichier inc_bidule.php3 qui lui contiendra :

<?php
$fond = "inc_bidule";
$delais = 24*3600;
include ("inc-public.php3");
?>

Et si vous oubliez, et bien tout simplement cela ne marchera pas ...

2. Avant de crier au loup (ça ne marche pas) il peut être utile de vider le cache ...

II.4 Application n°2 : INCLURE la gestion des métas

Dans chacun de vos fichiers html, vous avez une ou plusieurs lignes qui gèrent les balises métas, surtout si vous voulez optimiser le référencement de votre site.

Par exemple, dans article.html vous pouvez avoir ceci :

<BOUCLE_article_metas(ARTICLES) {id_article}>
	[<meta name="Description" content="(#INTRODUCTION|textebrut|entites_html)" />]
</BOUCLE_article_metas>

Et dans rubrique.html ceci :

<BOUCLE_rubrique_metas(RUBRIQUES) {id_rubrique}>
	<meta name="Description" content="[(#DESCRIPTIF|textebrut|entites_html)][ (#TEXTE|textebrut)]" />
</BOUCLE_rubrique_metas>

Le problème est alors de savoir comment coder le fichier INCLURE pour gérer les métas dans un seul fichier ...

LA SOLUTION :

Dans article.html remplacer le code gérant les métas par :

<INCLURE(inc_metas.php3) {id_article}>

Dans rubrique.html remplacer le code gérant les métas par :

<INCLURE(inc_metas.php3) {id_rubrique}>

Puis créer le fichier inc_metas.html (Et relisez donc le début de cette article ... surtout le message commençant par « Dans toute la suite de l’exposé ») contenant :

<BOUCLE_rubrique(RUBRIQUES) {id_rubrique}>
	<meta name="Description" content="[(#DESCRIPTIF|textebrut|entites_html)][ (#TEXTE|textebrut)]" />
</BOUCLE_rubrique>

<BOUCLE_article(ARTICLES) {id_article}>
	[<meta name="Description" content="(#INTRODUCTION|textebrut|entites_html)" />]
</BOUCLE_article>

Et voilà, vos métas sont désormais gérés par un unique fichier, et suivant le paramètre qui a été transmis à ce fichier inclus, les boucles seront exécutés ou pas.

II.5 Application n°3 : INCLURE « l’entête » et le « pied de page » de votre site sous spip

Cette application est particulièrement importante, car correctement réalisée, elle vous permet de rendre votre site modulable, et d’y intégrer facilement d’autres applications php ...

Pour un visiteur, un site web est bien lisible lorsqu’il est composé d’un entête (avec menu de navigation), d’un pied de page, et d’une section centrale contenant le texte, les images etc.

Aussi, il peut être intéressant de coder vos squelettes de manières à inclure le même « entête », et le même « pied de page », les mêmes feuilles de style...

-  Un entête
-  Une partie principale
-  Un pied de page

Aussi, dans tous les fichiers de votre squelette (article.html, rubrique.html, auteur.html ...), il devrait y avoir ceci :

<INCLURE(inc_structure_entete.php3)>

bla bla local, soit on affiche un article si on est dans le fichier "article.html", soit on liste les rubriques si on est dans le fichier rubrique.htm ...

<INCLURE(inc_structure_pieddepage.php3)>

De cette manière, sur toutes les pages du site, l’entête et le pied de page sont rigoureusement identiques, cela facilite la navigation et clarifie la cohérence de votre site.

II.6 Application 4 : INCLURE des données statistiques

Supposons que sur les pages article.html et plan.html, vous listez les articles, et que vous marquez à côté de chaque article sa popularité.

Comme les deux pages article.html et plan.html n’ont probablement pas été calculé au même moment par le moteur de spip, et donc mise en cache simultanément, il est probable que vous obteniez ceci sur votre navigateur Internet :

Consultation de article.html depuis votre navigateur Internet :
-  Titre de l’article 1 , puis son descriptif, (22 visiteurs aujourd’hui)
-  Titre de l’article 2 , puis son descriptif, (10 visiteurs aujourd’hui)
-  Titre de l’article 3 , puis son descriptif, (8 visiteurs aujourd’hui)
-  Titre de l’article 4 , puis son descriptif, (42 visiteurs aujourd’hui)

Consultation de plan.html depuis votre navigateur Internet :
-  Titre de l’article 1 (25 visiteurs aujourd’hui)
-  Titre de l’article 2 (8 visiteurs aujourd’hui)
-  Titre de l’article 3 (9 visiteurs aujourd’hui)
-  Titre de l’article 4 (36 visiteurs aujourd’hui)

Et si un visiteur remarque cette incohérence, ça ne fait vraiment pas très sérieux...

Face à ce problème, certain proposeront de réduire le cache des fichiers article.html et plan.html, ce qui est une très mauvaise solution, car cela ralentira votre site, et risque de contrarier votre hébergeur.

LA SOLUTION :

Dans vos fichiers article.html et plan.html il vous suffit de remplacer la balise #POPULARITE_ABSOLUE par <INCLURE(inc_popularite.php3) {id_article}>.

Puis de créer le fichier inc_popularite.html contenant ceci :

<BOUCLE_article_decompte_popularite(ARTICLES) {id_article}>
	#POPULARITE_ABSOLUE
</BOUCLE_article_decompte_popularite>

et vous n’aurez plus de problème de gestion du cache et de désynchronisation des statistiques.
Cette technique peut-être utilisé également pour le décompte des commentaires, le décompte des visiteurs ...

Remarques :
A. Vous noterez que le fichier inc_popularite.html ne contient pas seulement la balise #POPULARITE_ABSOLUE, mais une boucle, car lorsque le fichier inc_popularite.html est chargé (inclus), on est plus au sein d’une boucle, et ce même si le <INCLURE(inc_popularite.php3) {id_article}> a été placé au milieu d’un boucle dans le fichier parent.
B. Le délai du cache du fichier inc_popularite.html se règle dans inc_popularite.php3, et ici il parait adapté de le réduire un peu (par exemple 6*3600 au lieu 24*3600)

II.7 Bien gérer ces inclusions

A. Bien nommer ses inclusions
Tout fichier inclus devrait commencer par inc_ pour être facilement repérable.
Tout fichier inclus devrait avoir un nom explicite. Ainsi, pour un fichier inclus renvoyant la popularité d’un article, il est préférable de le nommer inc_article_popularite.html au lieu de inc_popularite.html car cela est plus explicite, et cela peut aussi signifier qu’il faut faire passer le paramètre id_article dans l’inclusion.
De préférence, les fichiers .html et .php3 devrait avoir le même nom.

B. Bien organiser ses inclusions
En usant et abusant des inclusions, vous risquez d’avoir un nombre important de fichier inclus commençant par inc_ et il peut être alors intéressant de déplacer tous ces fichiers dans un sous dossier. (Dans cette exemple, ce sous dossier sera appelé « inclusions »)
Ainsi, les fichiers inc_nomdufichier.html et inc_nomdufichier.php3 seront tous deux stockés dans un sous dossier du répertoire contenant vos squelettes , et de tels fichiers seront alors inclus par <INCLURE(inclusions/inc_nomdufichier.php3)>, et le fichier inc_nomdufichier.php3 contiendra logiquement $fond = "inclusions/inc_nomdufichier" .

C. Ne pas abuser des arguments inutiles
La tentation est grande de passer un maximum d’argument par les inclusions, tel {id_article} ou {id_rubrique}
Le problème est alors que si vous avez 500 articles, vous allez créer dans le cache autant de fichiers que d’articles... Si vous avez 10 inclusions avec le paramètre {id_article}, il y aura jusqu’à 10*500=5000 fichiers générés dans le cache...

II.8 CONCLUSION

Les INCLURE, c’est formidable ...

Cela facilite les mises à jour,
Cela permet d’extraire des bouts de code et de les mutualiser (tel le projet de noisettes sur spip-zone),
Cela permet de contourner des problèmes de désynchronisation lié au cache,
Cela autorise un réglage fin des délais de cache, car on peut fixer le cache de chaque fichier inclus à sa convenance,
Et surtout en codant son entête et son pied de page via des inclures, on peut sans grand effort intégrer graphiquement SPIKINI ou SEDNA par exemple... (Ce sera l’objet de deux autres articles)

Pour débuter et apprendre à maîtriser ces inclusions, je ne serais trop vous conseiller de partir d’un squelette déjà existant, et je vous recommande le squelette Maiis
 [1] qui est complet mais reste assez simple.
Si vous maîtriser bien le système d’inclusion, alors testez donc le squelette BLiP (Bon courage ...)

III. GÉRER LES INCLURES SANS LES FICHIERS PHP3

Cette section présente comment créer et gérer ses inclures sans utiliser de fichier .php3, c’est la méthode recommandée actuellement pour coder des squelettes.

III.1 Comment court-circuiter le fichier .php3

Vous avez sans doute compris, qu’un INCLURE nécessitait deux fichiers, un fichier .html et un fichier .php3.

Pour chaque :

<INCLURE(inc_bisounours.php3)>

vous devez alors créer le fichier inc_bisounours.php3 contenant en gros :

<?php
$fond = "inc_bisounours";
$delais = 24*3600;
include ("inc-public.php3");
?>

Et bien sur le fichier inc_bisounours.html contenant votre code, du html, des boucles spip, du php etc ...

Il existe un moyen de se passer du fichier .php3 et donc d’avoir deux fois moins de fichiers à créer : c’est l’utilisation du fichier page.php3 tel que défini sur l’article Comment faire un squelette facile à installer....

Explications :

Il suffit de remplacer :

<INCLURE(inc_bisounours.php3) >

Par :

<INCLURE(page.php3){fond=inc_bisounours}>

et de créer la page inc_bisounours.html, il n’y a plus besoin de créer de page inc_bisounours.php3.

Le fichier page.php3 se charge alors d’inclure le fichier inc_bisounours.html.

III.2 Reprise de l’application n°1 : INCLURE la gestion des feuilles de style

Le titre II.2 de cette article proposait d’inclure la gestion des feuilles de style, en créant le couple de fichier inc_css.php3 et inc_css.html .

En utilisant le fichier page.php3, il suffit désormais de faire :

Dans chacun de vos fichiers, remplacer la ligne contenant

<link rel="stylesheet" type="text/css" href="#DOSSIER_SQUELETTE/feuille_de_style.css" />

par :

<INCLURE(page.php3){fond=inc_css}>

puis créer le fichier inc_css.html contenant :

<link rel="stylesheet" type="text/css" href="#DOSSIER_SQUELETTE/feuille_de_style.css" />

(Et le fichier inc_css.php3 est devenu obsolète, il est inutile de le créer.)

III.3 Reprise de l’application n°2 : INCLURE la gestion des métas

Dans chacun de vos fichiers html, vous avez une ou plusieurs lignes qui gèrent les balises métas, surtout si vous voulez optimiser le référencement de votre site.

Par exemple, dans article.html vous pouvez avoir ceci :

<BOUCLE_article_metas(ARTICLES) {id_article}>
	[<meta name="Description" content="(#INTRODUCTION|textebrut|entites_html)" />]
</BOUCLE_article_metas>

Et dans rubrique.html ceci :

<BOUCLE_rubrique_metas(RUBRIQUES) {id_rubrique}>
	<meta name="Description" content="[(#DESCRIPTIF|textebrut|entites_html)][ (#TEXTE|textebrut)]" />
</BOUCLE_rubrique_metas>

Le problème est alors de savoir comment coder le fichier INCLURE pour gérer les métas dans un seul fichier ...

LA SOLUTION :

Dans article.html remplacer le code gérant les métas par :

<INCLURE(page.php3){fond=inc_metas}{id_article}>

Dans rubrique.html remplacer le code gérant les métas par :

<INCLURE(page.php3){fond=inc_metas}{id_rubrique}>

Puis créer le fichier inc_metas.html (Et il n’est pas nécessaire de créer le .php3 correspondant) contenant :

<BOUCLE_rubrique(RUBRIQUES) {id_rubrique}>
	<meta name="Description" content="[(#DESCRIPTIF|textebrut|entites_html)][ (#TEXTE|textebrut)]" />
</BOUCLE_rubrique>

<BOUCLE_article(ARTICLES) {id_article}>
	[<meta name="Description" content="(#INTRODUCTION|textebrut|entites_html)" />]
</BOUCLE_article>

Et voilà, vos métas sont désormais gérés par un unique fichier, et suivant le paramètre qui a été transmis à ce fichier inclus, les boucles seront exécutés ou pas.

Comme on peut le constater, le fichier page.php3 permet lui aussi de transmettre des paramètres.

III.4 Gestion du cache de spip

Cette méthode ne permet pas pour l’instant de gérer le délai du cache du fichier inclus, mais cela ne serait tarder, je tiens cette information de source sure ... Et la version 1.9 de spip arrive bientôt ...

Patience donc.

III.5 Stockage des inclusions dans un sous dossier

Et maintenant, supposons que vous souhaitez stocker vos fichiers inclus dans un sous dossier, il va vous falloir user d’un peu de ruse.

Si vos fichiers inclus sont contenu dans un dossier « inclusions », sous dossier de votre répertoire contenant les squelettes, il n’est pas possible de passer ce paramètre dans l’inclusion, aussi :

<INCLURE(page.php3){fond=inclusions/inc_bisounours}>

ne marchera pas.

Par contre, vous pouvez définir ce dossier dans votre fichier « ecrire/mes_options.php3 ».

Il vous suffit alors de remplacer :

<?php
$GLOBALS[ 'dossier_squelettes' ] = "squelettes" ;
?>

par

<?php
$GLOBALS[ 'dossier_squelettes' ] = "squelettes:squelettes/inclusions" ;
?>

Ou de créer le fichier correspondant s’il n’existe pas.

Explications techniques du fonctionnement de la déclaration « dossier_squelettes » (merci à James pour ses explications éclairées) :

Dans le fichier « ecrire/mes_options.php3 », on définit une variable globale « $dossier_squelettes », cette variable est exploitée par la fonction « find_in_path », qui collectionne des répertoires où trouver des fichiers facilement, qu’INCLURE s’empresse de fouiller, pour séparer les répertoires, on fait comme sur Unix, on les sépare lors de leur déclaration par un ’ :’
On peut donc définir de multiples dossiers en les séparants par des ’ :’, et le moteur de spip les explorera à la recherche du fichier défini par la variable « fond ».

III.6 CONCLUSION

La méthode utilisant le fichier page.php3 (telle que défini dans la section III.) est la méthode que nous vous conseillons d’utiliser, elle limite la création de fichier .php3.

Maintenant, il ne vous reste plus qu’à mettre les mains dans le code, et mettre à jour vos squelettes, s’ils n’utilisent pas cette méthode.

Pour poursuivre votre réfléxion, quelques articles à lire ou relire :

• Déjà proposé, mais incontournable : Comment faire un squelette facile à installer...
• Réflexions de fond de Romy sur le codage des squelettes : Monter son squelette en kit, Partager facilement ses noisettes