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
Aucune discussion
Ajouter un commentaire
Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :
Merci d’avance pour les personnes qui vous aideront !
Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.
Suivre les commentaires : |