Création d’un plugin

admin_themes & squelettes

Retour d’expérience sur la création d’un plugin.

L’écriture de plugins n’est pour moi qu’un moyen de découvrir les nouvelles fonctionnalités de SPIP depuis sa version 1.9. Il existe déjà d’autres plugins sans doute plus perfomants qui font ce que mes plugins proposent.

Le moment venu, je me pencherai sur des plugins développés sur la Zone et qui ont pour vocation d’être enrichis de manière collective.

En septembre dernier, je me suis lancé dans la création d’un plugin. Comme je venais de tester un blog proposé par mon hébergeur et propulsé par wordpress, je me suis dis qu’il serait intéressant d’avoir un outil d’installation de thèmes, un peu comme celui proposé par ce dit blog. (Il est parfois plus difficile de définir les besoins que de développer)

Sommaire

  1. Premier pas
  2. Le fichier plugin.xml
  3. Fichier utilisé dans le plugin admin_themes & squelettes
  4. La mise en place d’un bouton
  5. La mise en place d’onglets
  6. Conclusion

Premiers pas

Trouver de la documentation sur la création de plugins - les exemples / explications sur la création de plugins sont à rechercher sur :

-  Tutoriaux pour Plugins
-  SPIP 1.9 - Les Plugins
-  http://www.spip.net/fr_article3448.html
-  http://www.spip.net/fr_article3458.html

Depuis il est possible de trouver d’autres liens.

Une intervention de F. Ducas sur le même sujet voir http://spip.graphismes.free.fr/spip... sur [Spip-Dev] le 13 septembre 2006 m’a vraiment éclairé :

Je vais le mettre sur la doc des plugins quand j’ai le temps. Moi je suis parti de là : http://www.spip-contrib.net/SPIP-1-...

C’est vrai que c’est un peu touffu comme système. En fait, tu as quatre façons de faire tourner un plugin :

1. tu recrées dans ton dossier de plugin l’architecture originale de spip.

Par exemple, tu peux modifier (c’est un exemple) le fichier ecrire/exec/articles_forum.php et tu le mets dans plugins/TonPlugin/exec/articles_forum.php : quand ton plugin sera activé, c’est ce fichier qui sera lu et non le fichier natif de SPIP. Quand les concepteurs de spip modifieront le fichier ecrire/exec/articles_forum.php dans la version de développement, tu devras adapter ton fichier plugins/TonPlugin/exec/articles_forum.php pour qu’il soit identique (moins tes modifs) au nouveau fichier ecrire/exec/articles_forum.php : on appelle ça “suivre la SVN” (insérer les modifs apportées par la version de développement de SPIP à ton fichier de plugin, pour autant que ton fichier - celui qui porte le même nom que le tiens - ait été modifié dans la version de développement).

2. tu peux utiliser les pipelines.

J’avoues m’être cassé les dents sur l’organisation des pipelines. Ce que j’en ai compris, c’est que tu définis dans ton fichier plugin.xml le pipeline que tu veux utiliser, puis tu mets dans un fichier php, dont tu as donné le nom à plugin.xml pour le pipeline en question, la fonction qui insère ce que tu veux dans un pipeline. Bref, une analogie sera mieux… un pipeline c’est comme si tu envoies ce qu’on appelait un pneu il y a quelques temps : tu mets un courrier à un bout du tuyau, et le courrier ressort chez le destinataire à l’autre bout du tuyau (où si tu veux du plus djeunes : tu as une porte d’entrée sur un monde parallèle qui t’emmène dans un autre monde quand tu la traverses). En d’autres termes, les concepteurs ont inclus dans le code de SPIP une variable “machin” (un “pipeline” machin), et la variable machin est définie dans ton plugin et nulle part ailleurs : si un plugin défini “machin”, “machin” sera inséré dans le coeur de SPIP là où la place de la variable est écrite (d’où des incompatibilités de plugins si deux plugins définissent “machin”) ; si aucun plugin ne définit “machin”, le code de SIP n’est pas modifié. J’ai compris ça en lisant cette doc et en essayant d’abord d’insérer une nouvelle icône à l’espace privé (bon exemple pour comprendre comment ça fonctionne) : SPIP 1.9 - Les Plugins

3. tu peux utiliser ton propre script tout neuf et quasiment indépendant du code de SPIP.

Pour cela, il faut comprendre comment tu ajoutes un bouton et comment ce bouton exécute une page (en gros on exécute une page via l’insertion d’un bouton - voir le lien donné au 2). Cette page contient une fonction qui s’éxécute, et après tu peux à peu près faire tout ce que tu veux. C’est comme ça que mon plugin “habillages” insère un nouvel onglet, lequel onglet exécute un script dans le répertoire exec de mon plugin, et que vogue la galère.

4. tu indiques dans plugin.xml le fichier d’options

(chargé à chaque hit, donc exécutant son contenu à chaque hit) - attention : toutes les options classiques de mes_options.php ne fonctionnent pas dans ce fichier, comme pour redéfinir l’img_pack - et le fichier de fonctions (jamais utilisé).

Le fichier plugin.xml

La présence de ce fichier est indispensable. Il doit suivre une syntaxe particulière. Les points indispensables : cf spip.net

<plugin>
 <nom>Mon premier plugin</nom>
 <version>1.0</version>
 <prefix>demo</prefix>
</plugin>

Fichier utilisé dans le plugin admin_themes & squelettes

<plugin>

    <nom>Admin themes</nom>
    <auteur>Jacques Jermer </auteur>
	<version> Novembre 2006</version>
    <etat>test</etat>
    <description>Permet à l'administrateur de selectionner l'apparence du site a l'aide des themes<br />
	Activer ou desactiver/choisir son squelette.<br />
	Il est preferable d'activer le plugin desactiver_cache<br />
	Ajoute un bouton dans le sous menu Configuration<br />
	Affiche une copie d'ecran par theme/squelette, si image presente<br />
	sinon une image par defaut 		
	Pour la mise en place, lire le fichier alire.txt
	</description>
    <prefix>admin_themes</prefix>
	<options> <!-- fichier charge a chaque hit -->
		admin_themes_options.php
	</options>
	<pipeline>
		<nom>ajouter_boutons</nom>
		<action>ajouter_boutons</action>
		<inclure>admin_themes_boutons.php</inclure>
	</pipeline>
	<pipeline>
		<nom>ajouter_onglets</nom>
		<action>ajouter_onglets</action>
		<inclure>admin_themes_boutons.php</inclure>
	</pipeline>
    
</plugin>

Plus de détails sur doc.spip|Doc.spip.orgfr->http:...

La mise en place d’un bouton

Dans le fichier de création de bouton vous aurez un code semblable à celui-ci :

$boutons_admin[{{’naviguer’}}]->sousmenu[”gestion”]= new Bouton(
“../”._DIR_PLUGIN_GESTION.”/img_pack/gestion_base-24.gif”, // icone
_T(”gestion:Gestion des tables”) //titre
);

Il faut décider à quel endroit le nouveau bouton (sous menu) apparaitra. Dans l’exemple donné, il sera placé dans Edition grâce à la valeur ‘naviguer’ de $boutons_admin

Petit tableau récapitulatif :

-  $boutons_admin[’accueil’] => A suivre
-  $boutons_admin[’naviguer’] => Edition
-  $boutons_admin[’forum’] => Forum
-  $boutons_admin[’auteurs’] => Auteurs
-  $boutons_admin[’statistiques_visites’] => Statistiques
-  $boutons_admin[’configuration’] => Configuration
-  $boutons_admin[’aide_index’] => Aide
-  $boutons_admin[’visiter’] => Visiter

La création de boutons ou d’onglets implique la création d’un répertoire /exec dans le répertoire du plugin, d’un fichier .php contenant une fonction exec_prefix retenu pour le plugin dans notre cas function exec_admin_themes().

Dans cette fonction sera placé le code d’exécution de notre plugin, ou tout du moins une partie du code, le reste se trouvant dans d’autres fichiers qui seront inclus ou appelés.

La mise en place d’onglets

Pour voir des onglets, il suffit de cliquer sur « Configuration » : il s’agit par exemple de ’Contenu du site’, ’Interactivité’, ’Fonctions avancées’.

Dans notre exemple, une page est crée dans la partie privée du site pour afficher un choix possible de thèmes. Un thème est composé au minimum de deux fichiers :
-  plugin.xml
-  habillage.css
A ceux-ci peuvent se rajouter
-  impression.css
-  des images...

Pour ma part, je rajoute un fichier .png, du même nom que le thème, qui me permet d’afficher une vignette représentant le thème. Si ce fichier est absent, une image est affichée par défaut. Comme cela, la sélection d’un thème est facilitée.

Extrait du code :

	
function admin_themes_ajouter_onglets($flux) {
  if($flux['args'] == 'configuration')
	return $flux;
	
  if($flux['args'] == 'plugin'){
		$flux['data']['themes']= new Bouton(
		"../"._DIR_PLUGIN_ADMIN_THEMES."/img_pack/
gestion-themes-24.gif", 'Th&egrave;mes',
											  generer_url_ecrire("admin_themes"));
	$flux['data']['squelette']= new Bouton(
		"../"._DIR_PLUGIN_ADMIN_THEMES."/img_pack/
gestion-squelette-24.gif", 'Squelette',
											  generer_url_ecrire("admin_squelette"));
  return $flux;

  
  }
 

La fonction reprend le ’prefix’ du plugin auquel on ajoute _ajouter_onglets (le nom de l’action déclarée dans plugin.xml). Le paramètre $flux représente le flux (dans notre cas vide) auquel on rajoute les informations pour l’affichage de l’onglet (Bouton) telles l’image, le titre affiché et le lien sur un fichier php dont on ne donne que le nom sans son extension, ce fichier étant placé dans le répertoire /exec du plugin.

Si par exemple vous voulez rajouter un onglet à ’Configuration’, cette fonction ajoutera dans le flux retouné un onglet avec ses propriétés (image, titre, lien).

Conclusion

En espérant que ces explications vous aurons donné envie de passer à la création de plugins, je vous recommande si vous hésitez encore, de regarder le code des plugins proposés. Par exemple, après être resté dans la partie privée du site, je me suis inspiré du plugin jQuery pour « pluginiser » un code javascript qui permet d’arrondir les angles d’une div, d’un form et d’y incorporer une image en fond dans la partie publique du site.

Le plugin admin_themes&squelettes est téléchargeable ici
sa documentation

Discussion

Aucune discussion

Ajouter un commentaire

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

  • Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
  • Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
    • version de SPIP, en bas de la partie privée
    • version du plugin testé et des éventuels plugins nécessités
    • version de PHP (exec=info en partie privée)
    • version de MySQL / SQLite
  • Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
  • En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparaît.

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.

Qui êtes-vous ?
[Se connecter]

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom