[Agora-generale] Création d'un module
Douarche Olivier
odouarche at sqli.com
Mar 17 Jan 17:40:25 CET 2006
Bonjour,
> possédez-vous des informations / liens / pistes sur les différents
éléments me permettant d'envisager la création d'un module ?
> J'imagine qu'il existe une nomenclature qu'il convient de respecter
mais je ne trouve pas grand chose...
> Si je réalise un module et que je le verse à la communauté, quelle
sont les limites de mon implication ?
> Mon intervention s'arrête-t'elle à la correction des bugs ? Est-ce
uniquement à moi de réaliser ces opérations ?
Je ne peux répondre qu'à la première partie de votre question, la
seconde étant plutôt une question d'organisation et je pense que le
bureau des mainteneurs doit se prononcer sur la question.
En ce qui concerne la gestion des modules implémentée dans la branche
SPIP-1-3-AGORA_SIST du CVS, vous trouverez un fichier readme.txt
présents dans le répertoire /modules qui explique comment doivent être
construits les modules, avec en exemple concret, le module Hubble
(moteur de recherche fédérée) livrée dans cette branche.
Le fichier readme.txt est également fourni en pièce jointe de ce mail.
J'espère que les informations fournies dans ce fichier + l'exemple
seront suffisants pour développer de nouveaux modules.
Sachez également que la remontée des modules :
- Wiki
- Moissonneur OAI
- Abonnement
- MySqlFinder
sera effective en fin de semaine sur la branche HEAD du CVS.
Cordialement,
Olivier Douarche
-------------- section suivante --------------
*****************************************************************************
*** GESTION DES MODULES AVEC SPIP-AGORA **
*****************************************************************************
S O M M A I R E
-------------------
1/ CREATION D'UN MODULE
2/ LA PARTIE FRONT-OFFICE : [NOM_MODULE].php
3/ LA PARTIE BACK-OFFICE : [NOM_MODULE]Admin.php
4/ LE FICHIER DE LIAISON [NOM_MODULE]Param.inc
a. Description du composant.
b. Initialisation et inclusion diverses
5/ INSTALLATION DU MODULE
6/ UTILISATION DU MODULE DANS LES SQUELETTES
1/ CREATION D'UN MODULE
----------------------------------
a. Commencer par créer un répertoire dans le dossier /modules.
A T T E N T I ON !!!
LE NOM DU REPERTOIRE DEVIENDRA LE NOM DU MODULE : [NOM_MODULE]
b. Dans ce répertoire 3 fichiers sont nécessaires :
[NOM_MODULE].php et [NOM_MODULE]Admin.php
- [NOM_MODULE].php correspond à la partie front-office du module
- [NOM_MODULE]Admin.php correspond à la partie backt-office du module
- [NOM_MODULE]Param.inc correspond à un fichier de paramétrage qui présente le module et qui fait le lien avec Spip-Agora,
notamment au niveau du contexte et des variables d'environnement
ex : Si je créée un module Wiki, j'aurai donc :
- Un dossier "Wiki", dans lequel je vais trouver 3 fichiers :
* Wiki.php
* WikiAdmin.php
* WikiParam.inc
c. Dans le cas d'un module multilangue un dossier "Langue" pourra être créé.
Il devra alors contenir des fichiers de la forme :
[NOM_MODULE]_[LANGUE].inc
ou [LANGUE] est le code langue de SPIP-Agora en majuscule.
Dans la partie d'administration du module ces fichiers de langue sont automatiquement chargés par le framework.
d. Après vous êtes libres de créer autant de sous-dossiers que vous voulez pour organiser votre code source
2/ LA PARTIE FRONT-OFFICE : [NOM_MODULE].php
---------------------------------------------------------------
3 règles à respecter :
- Ce fichier doit contenir la classe nommée [Nom_module] (Pre
- Cette classe doit être pourvue de l'attribut de classe $HtmlCode qui contiendra le flux html de retour à destination de Spip-Agora
- Le constructeur de la classe prendra en paramètre le code de l'action que le module doit exécuter
Ex pour un Wiki :
Class Wiki
{
var $HtmlCode = "";
function Wiki($Action)
{
switch($Action)
{
case("EDITER") :
$Html = $this->wikiEditerPage();
break;
case("VISUALISER") :
$Html = $this->wikiVisualiserPage();
break;
case("ENREGISTRER") :
$Message = $this->wikiEnregistrerPage();
$Html = $this->wikiAfficherWiki($Message);
break;
default :
$Html = $this->wikiAfficherWiki();
break;
}
$this->HtmlCode = $Html;
}
}
L'action passée au module s'effectue par l'intermédiaire de la variable ACTION[NOM_MODULE] passée dans la QUERYSTRING.
A T T E N T I O N !!!
TOUJOURS PREVOIR UN COMPORTEMENT PAR DEFAUT
Ainsi par exemple, le lien suivant :
<A href="http://monsite/mapage.php?id_article=21&ACTIONWIKI=EDITER">Editer ce Wiki</A>
Déclenchera le réaffichage de la page contenant l'article 21.
Pour peu que le squelette de cet article soit pourvu du module Wiki, l'action EDITER sera passée au constructeur de la classe du module Wiki.
La classe n'a qu'à donc exécuter l'action recommandée afin d'alimenter le buffer de sortie du module : l'attribut $HtmlCode.
A T T E N T I O N !!!!
Toutes les URLs et les liens d'action de votre composant doivent donc contenir la variable ACTION[NOM_MODULE].
Pareil pour les formulaire et leur attribut "action". Cela n'empêche pas de le faire fonctionner en "METHOD=POST".
Si la variable ACTION[NOM_MODULE] est oubliée, le module se comportera par défaut.
3/ LA PARTIE BACK-OFFICE : [NOM_MODULE]Admin.php
----------------------------------------------------------------------
Ce fichier se base sur le même principe que pour la partie front:
Il doit respecter les 3 mêmes règles :
- Ce fichier doit contenir la classe nommée [NOM_MODULE]Admin
- Cette classe doit être pourvue de l'attribut de classe $HtmlCode qui contiendra le flux html de retour à destination de Spip-Agora
- Le constructeur de la classe prendra en paramètre le code de l'action que le module doit exécuter
Ex :
class WikiAdmin
{
var $HtmlCode="";
function WikiAdmin($myChoice)
{
$this->HtmlCode = "Ce module ne contient pas de partie administrable";
}
}
4/ LE FICHIER DE LIAISON [NOM_MODULE]Param.inc
-----------------------------------------------------------------
Afin de créer des composants relativement portables d'un framework à l'autre, il faut instaurer un fichier de paramètrage qui va permettre
au composant de reconnaitre le contexte dans lequel il évolue :
- pour les accès aux données
- pour la création des chemins et des URLS
- etc
Vu que Spip-Agora est pourvu d'une installation automatique, il serait dommage de venir paramétrer "à la main", pour chaque composant installé, les
différentes variables d'environnement.
C'est l'intérêt de ce fichier.
a. Description du composant.
------------------------------------------
Ce fichier contient 2 variables Globales :
- $GLOBALS[ [NOM_MODULE]]["VERSION"]
- $GLOBALS[ [NOM_MODULE]"]["DATE"]
- $GLOBALS[ [NOM_MODULE]]["AUTHOR"]
Ces variables seront enregistrées en base lors de l'installation du composant dans la partie d'administration.
b. Initialisation et inclusion diverses
------------------------------------------
Le reste du fichier vous appartient.
Celui-ci sera chargé à chaque appel du composant que ce soit dans la partie front-office ou back-office de Spip-Agora.
Vous pouvez donc utiliser vos propres variables de session ou globales à l'intérieure de votre composant.
Ou faire vos propres inclusion de fichiers.
Ce fichier permettra de les initialiser avec celle du framework.
par exemple :
$_SESSION["LANGUE"] = strtoupper($GLOBALS["spip_lang"]);
Dans notre composant ce sera donc la variable de session "LANGUE" qui sera utilisée plutôt que la globale "spip_lang" du framework.
// Inclusion du fichier de paramêtrage de la base
include($_SESSION["PATH_ROOT"]."ecrire/include/bd/inc_config_metier.php");
//--------------------------------------------------------------------------
// SGBD
$_SESSION["SGBD_BASE"] = $dbName;
$_SESSION["SGBD_SERVER"] = $dbHost;
$_SESSION["SGBD_USER"] = $dbLogin;
$_SESSION["SGBD_PASSWORD"] = $dbPassword;
Ici on voit comment récupérer les paramètres de connexion de Spip-Agora
Cela permet de s'affranchir du framework et de rendre le composant portable d'un framework à l'autre.
5/ INSTALLATION DU MODULE
-----------------------------------------
L'installation du module se limite à déposer le répertoire du module dans le dossier /modules.
C'est tout.
Si les règles de nommage ont bien été respectées, vous devriez voir apparaître un bloc pour votre composant dans la partie
Administration du site > Gestion des modules.
Le composant nécessite cependant d'être référencé auprès du framework.
C'est pour cela que lors de la première visite dans l'administration du module, un bouton vous propose son installation.
Lors de l'installation 2 choses se produisent :
- Votre module est référencé dans la table spip_module
- Si un fichier [NOM_MODULE].sql existe à la racine du dossier du module, le script est exécuté.
A T T E N T I O N !!!
Le fichier SQL doit contenir 1 seule instruction par ligne pour fonctionner.
Par exemple pour notre Wiki, le fichier Wiki.sql est disponible dans /modules/Wiki/ :
CREATE TABLE WIKI ( WIKI_ID int(11) NOT NULL default '0', WIKI_VERSION int(11) NOT NULL default '0', WIKI_TITRE varchar(255) NOT NULL default '', WIKI_CONTENU text NOT NULL, WIKI_DATE datetime default NULL, WIKI_DATE_DERNIER datetime default NULL, WIKI_AUTEUR varchar(255) NOT NULL default '', PRIMARY KEY (WIKI_ID,WIKI_VERSION,WIKI_TITRE));
CREATE TABLE WIKI_COMPTE ( WIKI_COMPTE_ID int(11) NOT NULL auto_increment, WIKI_COMPTE_NOM varchar(50) default NULL, WIKI_COMPTE_MOT_PASSE varchar(50) default NULL, WIKI_COMPTE_EMAIL varchar(50) default NULL, PRIMARY KEY (WIKI_COMPTE_ID));
Lors de l'installation il sera donc exécuté est les tables de gestion du Wiki seront donc créées en base.
6/ UTILISATION DU MODULE DANS LES SQUELETTES
-----------------------------------------------------------------
Pour inclure un module dans les squelettes, rien de plus simple.
Le mot-clef <MODULE> a été ajouté.
La syntaxe d'appel d'un module est donc la suivante :
<MODULE([NOM_MODULE]){parametres}>
Par exemple pour notre Wiki la syntaxe serait :
<MODULE(Wiki){id_article}>
Plus d'informations sur la liste de diffusion Agora-generale