Geekographie Maïeulesque

Jeux de squelettes sous forme de plugin pour SPIP 3

Maïeul — 2012-07-23T15:29:48Z

Dans un précédent article, j'expliquais pourquoi et comment distribuer un jeu de squelettes sous forme de plugin. Cet article est une simple adaptation pour SPIP 3.

Les raisons de distribuer un jeux de squelette sous forme de plugin n'ont pas changé : je ne les répète donc pas. En revanche, le passage à SPIP 3 a introduit la transformation de plugin.xml à paquet.xml. Ces changements sont liés à la volonté d'avoir un formalisme plus important et plus propre. Voici donc un fichier paquet.xml minimal pour proposer un jeu de squelettes sous forme de paquet.xml. On lira les spécifications du paquet.xml pour aller plus loin.

 Nom du plugin Nom de l'auteur Licence

Selon la documentation officielle, la compatibilité prend l'une des formes suivantes :

[v1 ;v2] qui correspond à v1 <= SPIP <= v2
[v1 ;[ qui correspond à SPIP >= v1
[ ;v2[ qui correspond à SPIP < v2

et toutes les autres combinaisons avec inclusion ou pas des bornes.

Ainsi pour indiquer une compatibilité sur toute la branche SPIP 3, mettre :

À noter que ni la balise auteur ni la balise licence ne sont obligatoires, et leurs attributs sont facultatifs. En outre, on doit mettre une balise auteur par auteur.

Vous devez choisir entre l'un des trois états du squelette : dev, test, ou stable. Le prefix du squelette doit être parlant mais court. Vous pouvez préciser dans les attributs documentation et demonstration de la balise paquet l'url de la documentation et du site de démonstration.

En ce qui concerne la balise necessite, il faut en mettre une par plugin nécessaire, en mettant comme valeur de l'attribut nom le préfixe du plugin demandé.

Vous pouvez aussi préciser les versions compatibles de ces plugins, via l'attribut compatibilite, ayant la même syntaxe que pour la balise paquet.xml.

Il ne faut pas mettre de numéro de version dans le prefix ni dans le titre : l'attribut version sert à cela. Cette attribut doit avoir la forme x.y.z :

Un changement de X indique un changement majeure (rupture de compatibilité, réorganisation totale du code).
Un changement de Y indique un changement mineure (nouvelle fonctionalité).
Un changement de Z indique une correction de bug.

Il est très fortement demandée de mettre les trois chiffres pour une version d'un squelette.

Le fichier de langue

Avec paquet.xml certains éléments doivent être indiqués dans des fichiers de langue. Ces fichiers doivent être situés dans le dossier lang du plugin, et avoir un nom sous la forme : paquet-{préfixe_du_plugin}_{code_de_langue}.php. Par exemple, pour un jeux de squelette dont le prefix est toto, les chaînes de langues de descriptions du squelette seront à placer dans lang/paquet-toto_fr.php.

Il existe deux chaînes de langues quasi-obligatoires :

 'Description aussi succincte que possible du plugin, pas une documentation.', 'prefix_slogan' => 'Slogan du plugin' ); ?>

Et le fichier `options.php` ?

Dans la précédente version de cet article, je présentais rapidement un fichier options.php recommandés. Ce fichier n'a plus de sens pour une distribution minimale d'un jeu de squelette, puisque SPIP 3 s'occupe automatiquement de supprimer les numéros devant les titres.

Cependant, pour une jeu de squelette propre à votre organisation et non générique, vous pouvez mettre un fichier prefix_options.php afin d'augmenter le quotat de cache, en mettant les lignes suivantes (pour augmenter à 100 Mo le quota de cache :

Vérifier son paquet.xml

On pourra utiliser l'outil de vérification en ligne pour s'assurer de la conformité du fichier paquet.xml.

Sept bonnes pratiques de développement avec SPIP

Maïeul — 2012-01-05T00:39:57Z

Je travaille en ce moment sur un squelette qui n'est pas de moi. Il semble que la personne qui l'a créé n'était pas au courant des bonnes pratiques de développement sous SPIP. Il est vrai que ces bonnes pratiques ne sont pas nécessairement accessibles aux premiers abords de la documentation webmaster de SPIP.

Voici sept règles que je juge indispensables

1. Ne pas mettre de PHP dans les squelettes

Le but de SPIP était de permettre de ne pas avoir à connaître le PHP pour concevoir un site. Tout un système spécifique a été prévu, pour faire des requêtes SQL, mais aussi des tests. C'est parfois perturbant pour les utilisateurs venant du monde PHP.

Mais pour autant, c'est une très bonne pratique de ne quasiment-jamais mettre de PHP dans un squelette. En réalité, c'est une mauvaise pratique d'en mettre.

2. Ne rien mettre dans le dossier IMG

Le dossier IMG ne doit contenir que les images et documents ajoutés par l'utilisateur depuis l'interface privé. En aucun cas il ne doit contenir des images propres aux squelettes, qui doivent se trouver dans le même dossier que les squelettes.

Choisir de mettre les images dans IMG (comme je l'ai vu dans ce squelette), c'est compliquer les réutilisations des squelettes, et mélanger les couches utilisateurs et webmestres de SPIP.

3. Utiliser `#CHEMIN`

La balise #CHEMIN est une balise indispensable de SPIP. Elle permet d'indiquer l'adresse d'un fichier sans se préoccuper du nom du dossier parent. En effet, SPIP va cherche le fichier passé en argument dans l'ordre suivant [1] :

squelettes
plugin B dépendant du plugin A
plugin A
squelettes-dist
prive
ecrire

Exemple : j'ai une image dans le dossier squelettes, je ne fais pas :

mais bien

mieux, je met mon image toto.png dans le dossier img du dossier squelettes.

Je peux alors faire :

L'avantage d'un tel système est évident : permettre d'avoir un dossier squelettes qui ne s'appelle pas squelettes, par exemple lorsqu'on utilise ma sixième recommandation : les squelettes sous forme de plugins. Mais aussi permettre à SPIP de gérer correctement les URLS arborescentes (le cas échéant).

4. Utiliser `|balise_img`

Il est recommandé lorsqu'on insère une balise de lui mettre des attributs height et with pour améliorer les performances du navigateur lors de l'affichage de la page.

On peut bien sûr indiquer cela manuellement :

Mais supposons que je réduise la taille de toto.png : je dois dans ce cas modifier les attributs height et width à chaque fois que je l'utilise.

Pour éviter cela, SPIP prévoit le filtre |balise_img qui, lorsqu'il est appliqué au chemin d'un fichier image, crée automatiquement la balise , avec la hauteur et la largeur du fichier. Ainsi, pas besoin de corriger si on réduit la taille du fichier.

Le filtre s'utilise de manière très simple :

[(#CHEMIN{toto.png}|balise_img)]

On peut même mettre en argument le contenu de l'attribut alt

[(#CHEMIN{toto.png}|balise_img{0+0})]

Voir en deuxième argument la valeur de l'attribut class :

[(#CHEMIN{toto.png}|balise_img{0+0,blague_pour_enfants})]

Ce code au final me produit :

5. Utiliser les chaînes de langues

Bien que cela puisse paraître inutile et fastidieux pour un site monolingue, utiliser les chaînes de langue est quand même utile pour trois raisons :

on ne sait jamais : si le site devient multilingue, c'est toujours cela de fait.
il est plus facile d'uniformiser les textes.
il est plus facile de corriger en cas de faute ou de changement d'avis.

6. Utiliser

C'est un principe de base de l'informatique : dès qu'une séquence d'instructions est utilisée plusieurs fois, il faut non pas la dupliquer, mais la mettre dans un morceau qu'on appelle plusieurs fois.

En SPIP ce morceau, c'est un fichier inclus.

Typiquement supposons que j'affiche sur toutes les pages de mon site les sites amis.

Au lieux de copier-coller le code suivant dans les squelettes :

   #NOM

Je le met dans un fichier sites-amis.html, situé dans un dossier inclure du dossier contenant les squelettes.

Et je met le code suivant là où je souhaite afficher les sites amis :

Cela me permet si je dois modifier les critères de cette liste de ne les modifier qu'à un endroit [2].

La logique est donc : diviser son site en briques réutilisables. Chaque brique correspondant à fichier et à un morceau logique de page. Ensuite assembler ces briques dans des fichiers plus globaux [3].

Le modèle de squelettes Z pousse à l'extrême cette logique des inclusions. Je conseille de le suivre : on gagne largement en maintenance ce qu'on perd en temps d'apprentissage initial.

Une règle importante dans les inclusions : les balises html qui s'ouvrent dans un fichier doivent se fermer dans le même fichier. Il est très mauvais d'ouvrir une balise dans un fichier puis de la fermer dans un autre : on y est perd en lisibilité du code, et donc en maintenance [4].

7. Mettre ses squelettes sous formes de plugins

Cela peut paraître un luxe ou coquetterie, mais cela facilite énormément le déploiement d'un même squelette sur plusieurs sites ou le déménagement depuis la version locale vers la version en ligne :

en indiquant les dépendances aux plugins.
en incluant le fichier mes_options.php dans le même dossier.
en permettant même le cas échéant d'ajouter automatiquement un contenu pré-défini.

Un précédent article détaille comment fabriquer ces squelettes-plugins.

Amis SPIPeurs, j'attends vos remarques et ajouts !

[1] Liste tirée du site Programmer avec SPIP.

[2] En outre, cela diminue les requêtes SQL et donc la charge du serveur SQL, mais la contrepartie est de multiplier les fichiers de caches ainsi que les inclusions PHP.

[3] Pour comprendre comment passer des paramètres lors de ces inclusions, pour par exemple connaître l'article courant, je renvoie à mon article sur la balise #ENV. Cet article devrais être mis à jour pour parler des dernières nouveautés. Mais l'essentiel est là.

[4] J'ai crû à un moment qu'une structure html était incorrecte du fait qu'un fichier avait plus de

ouvrantes que fermantes. En réalité, le dernier

manquant se trouvait ailleurs.

Jeux de squelettes sous forme de plugin

Maïeul — 2010-12-05T15:08:14Z

Pourquoi mes squelettes sont-ils désormais entièrement sous forme de plugin ? Pourquoi n'utilise-je plus la technique classique, à savoir un dossier /squelettes à la racine de SPIP ? Pourquoi fais-je un squelettes sous forme de plugin ?

En dehors des squelettes génériques, il est utile maintenant de faire tout ses jeux de squelettes sous forme de plugin.

Pourquoi faire ?

Avoir un seul dossier qui contient les squelettes et le fichier d'options. Plus besoins d'avoir un fichier mes_options.php à part.
Disposer de la syntaxe du fichier plugin.xml pour dire les dépendances du squelettes.

Comment faire ?

Créer un dossier dans lequel vous mettrez l'ensemble de vos squelettes (comme vous faisiez classiquement avant).
Si vous êtes sous SPIP 3, reportez à l'article correspondant au paquet.xml, sinon continuez votre lecture.
Dedans y mettre le fichier plugin.xml prochainement. Cet article pourra être périmé le jour où vous le lirez.]] suivant :

 NomSquelette squelette  Votre nom  0.1 stable  Un descriptif autant complet que possible, utilisation de la syntaxe spip autorisée. prefix prefix_options

Mettez autant de nécessite que de plugin nécessaire. Attention la valeur de l'attribut id est le prefix du plugin (dans son fichier plugin.xml) pas son nom.

Remplacez prefix par un préfixe à vous. A titre d'exemple, le plugin.xml du squelette de ce site.

Dans le fichier prefix_options.php, mettez les lignes suivantes [1] :

Cela supprimera automatique les numéros dans les titres d'articles, dans les noms d'auteurs etc. La valeur de $GLOBALS['quota_cache'] est par défaut à 10 (Mo) mais si vous utilisez un squelette de type Z, ce n'est pas assez.

Copiez le dossier ainsi créé dans le dossier de plugin. Activez depuis l'espace privé de SPIP ce plugin.

Si vous avez peur que quelqu'un désactive ce plugin et mette en l'air la présentation plugin, vous pouvez à partir de SPIP 2.1 mettre dans le dossier extension, ce qui rendra non désactivable le plugin/squelette.

Pour la syntaxe complète du fichier plugin.xml c'est par là : http://doc.spip.org/@Plugin-xml

[1] Voir aussi mon précèdent article.