Tunecity.net

Objectif de cet article

Il s’agit de mettre ici quelques informations de base , préalablement à la réalisation d’une documentation (qui manque je sais).

Avant tout, je ne peut que recommander tout auteur de MOD de :
  "voir" comment fonctionne SpipEM (au moins consulter les articles à ce sujet),
  "editer", tester les MODs déjà disponible en particulier le MOD de test.

Composition d’un paquetage MOD

Un fichier MOD est une archive (paquetage) zip ou tar (compressé éventuellement) comprendant 1 ou plusieurs fichiers, le tout situé dans un sous-répertoire les contenant.

Exemple : ecrire/spipem/mods va contenir (après depaquetage et téléchargement) :

On a donc :
  un répertoire principal (contenant tous les fichiers du MOD et sous répertoire éventuels à l’exception de backup et processed qui sont réservés), du nom du mod en général : spip_phpbb dans notre exemple.
dans la suite tous les fichiers sont situés dans ce répertoire principal (ou l’un de ses sous-répertoires).

  un fichier .mod (ou .txt pour les anciennes versions) dont le nom est le même que celui du sous-répertoire (de préférence) : spip_phpbb.mod dans notre exemple . C’est le squelette du MOD et le seul fichier obligatoire dans un MOD (fichier texte, 7 bits si possible).

  l’archive peut contenir d’autres fichiers qui seront au choix :

• des fichiers de licence ou Readme divers (non gérés par SpipEM),
• des fichiers à copier par SpipEM (dont on retrouvera le répertoire et le nom dans le fichier squelette .mod),
  NB : Attention ! Ne surtout pas mettre de fichiers de SPIP parmis ceux-ci. Seuls de nouveaux fichiers (html ou php par exemple) sont bienvenu, par exemple une nouvelle librairie, fonction ... non présente dans Spip. Si vous voulez modifier un fichier propre à SPIP (core) il faut le faire au sein du fichier squelette .mod (voir ci-après).

Composition du fichier squelette

Comme on l’a vu c’est le fichier au cœur d’un MOD. Comment est-il composé ? On prendra pour exemple celui du MOD de test.

Le fichier (texte) est composé de deux parties principales :

1. des déclarations en tête de fichiers précédées par les caractères ## définissant une zone de commentaire dans ce fichier
2. des ordres/actions à réaliser composés eux-mêmes de deux parties : l’action et sa description.

En-tête / Description

  dans cette partie sont requis (au minimum) :

Champ	Fonction	Requis
Mod Title :	Court titre du mod, généralement du meme nom que le répertoire	Oui
Mod Author :	Auteur du MOD et/ou du code apporté	O
Mod Description :	Brève description indiquant ce que fait ce MOD	O
Mod Version :	La version de votre MOD sous la forme xx.yy	Y
SpipEM Required Version :	La version de SpipEM requise pour installer ce MOD : all ou >,<,<= et une version xx.yy	Non
SPIP Required Version :	La version de SPIP requise pour installer ce MOD, sous la forme : all (valeur par défaut) ou >,<,<= et une version xx.yy	Non
Installation Level :	Niveau de difficulté pour ceux qui veulent faire les opérations à la main	N
Installation Time :	Temps estimé pour faire à la main	N
Files To Edit :	en colonne la liste des fichiers qui seront modifiés	N (*)
Included Files :	en colonne la liste des fichiers inclus dans le MOD	N (*)

  Les autres lignes précédées de ## sont considérées comme des commentaires et vous pouvez les utiliser pour vos propres commentaires. Essayez cependant de ne pas introduire de déclaration ou d’éléments qui pourraient déstabiliser l’analyseur de SpipEM.

  (*) Attention ! Pour le moment ces informations sont optionnelles mais elles pourront devenir obligatoires dans une prochaine version (pour ajouter un niveau de controle d’intégrité par exemple).

Actions/opérations à réaliser

Toutes les actions sont en deux parties :

  le nom de l’action a réaliser sous la forme :
#-----[ ACTION ]------------------------------------------
  la description des action a réaliser :
Par exemple :
copy spipem_test.php.txt to ecrire/spipem/spipem_test.php

  liste des actions existantes :

nom	fonction	condition d’usage	stable
PRE	exécute le(s) fichier(s) php donné en paramètre avant le début de l’installation	pas encore définie - ne pas utiliser	Non
POST	exécute le(s) fichier(s) php donné en paramètre après la fin de l’installation	pas encore définie - ne pas utiliser	Non
COPY	copie les fichiers donnée dans la liste (un par un)	la description doit etre sous la forme : copy nom_source to chemin/nom_destination	Oui
SQL	réalise les commandes SQL données	les commandes ne sont pas testées et doivent etre du SQL valide	Non
OPEN	Ouvre le fichier donné en description pour le modifier	Le traitement précédent doit être terminé	Oui
FIND	Recherche la ou les lignes données en description	suivi de AFTER, BEFORE, REPLACE WITH, IN-LINE FIND	Oui
AFTER, ADD	Ajoute la ou les lignes données dans la description	Ajout après le bloc trouvé par la commande FIND	O
BEFORE, ADD	Ajoute la ou les lignes données dans la description	Ajout avant le bloc trouvé par la commande FIND	O
IN-LINE FIND	Recherche une zone au sein de la ligne ou du bloc trouvé par FIND	Obligatoirement suivi de « IN-LINE AFTER, ADD » ou « IN-LINE BEFORE, ADD »	O
IN-LINE AFTER, ADD	Ajoute le texte donné en description	Le texte est ajouté après le bloc trouvé par IN-LINE FIND	O
IN-LINE BEFORE, ADD	Ajoute le texte donné en description	Le texte est ajouté avant le bloc trouvé par IN-LINE FIND	O
REPLACE WITH	Remplace le bloc trouvé par la ou les lignes données dans la description	Remplace le bloc trouvé par la commande FIND. Commande à proscrire. Lui préférer les AFTER, BEFORE et INLINE !!	O
SAVE/CLOSE ALL FILES	Termine le traitement du MOD	Requis à la fin du MOD	O

  les autres lignes précédées d’un # positionné en première colonne sont considérées comme des commentaires et ne sont pas traitées par SpipEM.

  les fichiers .mod les plus simples contiennent outre l’en-tête : une suite OPEN, FIND, « AFTER, ADD », « SAVE/CLOSE ALL FILES » et parfois un bloc COPY.

Fichiers sources (php et html)

Parfois pour rendre une modification opérationnelle, vous aurez besoin d’ajouter de nouveaux fichiers. Vous pouvez inclure ceux-ci dans l’archive, et les installer par le biais de la commande COPY présente dans le fichier .mod.

Notez cependant que :
  il est préférable que les fichiers php (ou php3) aient un extension non visible et surtout non exécutable (.tmp, .txt) juste au cas où.
  de même pour les fichiers .html.
  vous pourrez changer le nom et surtout l’extension du fichier avec copy nom_fichier_source to chemin_nom_fichier_destination .

Autres recommandations, trucs et astuces...

Lors de la contruction du fichier squelette, n’oubliez pas que les parties que vous modifiez dans les fichiers core de SPIP peuvent être modifiées par d’autres MODs avant ou après le votre !!!

Donc essayez de prendre des zones potentiellement stables comme repère pour les bloc FIND et IN-LINE FIND. Souvent les débuts "<?" et fin de fichiers " ?>" php sont pratiques et certains commentaires aussi.

Vous pouvez comparer l’évolution du fichier en question entre deux version de SPIP pour "voir" si votre recherche et modification serait restée valable au cours de cette modification par exemple...

Pour finir

N’oubliez pas que lors de l’installation du MOD vous trouverez dans :
  backup : la sauvegarde de l’ensemble des fichiers modifiés
  processed : l’ensemble des fichiers qui seront/ont été installés (modifiés et nouveaux).

Vous pourrez donc aisément les comparer (manuellement ou avec des outils comme diff ou autres) pour vérifier que votre opération s’est bien réalisée.

Pour réinstaller une deuxième fois le même MOD (déjà installé). Ce qui arrive... souvent... pendant des tests :
  un mécanisme de protection pour les utilisateurs empêche littéralement de faire cela :-) , ne cherchez pas à le désactiver !
  pour faire cela :

1. restaurez les fichiers d’origine (à partir de backup) et supprimez les nouveaux fichiers (sinon la prochaine copie pourrait être bloquée),
2. supprimez la ligne correspondante dans la base de données de SPIPEM : spip_em_history (delete MySQL).

Dans un avenir plus ou moins proche, j’essairai d’écrire le code pour automatiser tout cela...