Intégrer un module back-office v1 en v2
Un article de DocAstairs.
Sommaire |
[modifier] Introduction
Pour le back-office de la v2, la page d'accueil présentant les différentes fonctionnalités de la plate-forme(Ressources humaines, Ressources pédagogiques et Ressources Administratives) est générée dynamiquement.
De même, quand les liens de cette page d'accueil affichent un menu (que l'on appelera menu de module, celui-ci est aussi généré dynamiquement.
Erreur lors de la création de la miniature : convert: unable to open image `/usr/local/www/mediawiki/images/b/b0/Menu_module_1.jpg': No such file or directory. convert: missing an image filename `/usr/local/www/mediawiki/images/thumb/b/b0/Menu_module_1.jpg/100px-Menu_module_1.jpg'. |
Ces générations automatiques se font grace à l'introduction d'une nouvelle notion qui n'existait pas auparavant: la notion de module.
Ce HOWTO décrit donc les modifications à apporter aux fichiers et repertoires de la v1 pour qu'ils fonctionnent en v2 avec cette gestion de modules. Ainsi, une fois ces modifications apportées aux fichiers et repertoires, les liens et les menus auxquels ils correspondent seront automatiquement ajoutés.
[modifier] Les concepts de Module
Un module peut se définir par:
un ensemble de scripts php présentant un ensemble de fonctionnalités communes.
Le module est un concept plutot que quelque chose de clairement défini. Il sera donc plus facile de le comprendre avec des exemples.
Sur la v1 on faisait facilement l'analogie suivante: module=repertoire.
Ce principe est conservé sur la v2, donc on pourra dans un premier temps conserver la définition module = répertoire Cependant, avec un peu de recul, on peut s'apercevoir qu'un repertoire en v1 peut contenir plusieurs modules, et meme que certains repertoires pourraient être regroupé.
Voici un exemple concret pour ce qui est des séries d'évaluations:
Sur Astairs, il y a plusieurs sortes de séries:
- les séries (simples)
- les séries aléatoires
- les séries bloquantes
De plus, il y a aussi plusieurs sortes de séries aléatoires:
- les séries aléatoires configurées
- les séries aléatoires multithèmes
- les séries aléatoires multiséries
On peut donc remarquer finalement que les séries présentent une arborescence. Il est donc assez simple de ressortir l'arborescence suivante:
Erreur lors de la création de la miniature : convert: unable to open image `/usr/local/www/mediawiki/images/4/44/Arborescence_modules_series.jpg': No such file or directory. convert: missing an image filename `/usr/local/www/mediawiki/images/thumb/4/44/Arborescence_modules_series.jpg/400px-Arborescence_modules_series.jpg'. |
Ainsi, on a ici défini 6 modules:
- les séries
- les séries aléatoires
- les séries bloquantes
- les séries aléatoires configurées
- les séries aléatoires multithèmes
- les séries aléatoires multiséries
En v2, on aura donc 6 répertoires:
- serie
- serie_aleatoire
- serie_aleatoire_configuree
- serie_aleatoire_multithemes
- serie_aleatoire_multiseries
- serie_bloquante
[modifier] Un module: ses proriétés
Maintenant que nous avons une idée de ce à quoi correspond un module, voyons ses propriétées.
[modifier] Les sous modules
Nous allons introduire ici la notion de sous module.
Avec l'exemple des séries, on a vu que les modules peuvent être hierarchisés, sous la forme d'une arborescence. Un sous module est donc un module hierarchiquement juste en dessous d'un autre module. On peut donc aussi dire qu'un module possède d'autres modules, ses sous modules.
Ainsi, en reprenant notre exemple:
Le module série à pour sous modules: * série aléatoire * série bloquante
et encore:
Le module série aléatoire à pour sous modules
- série aléatoire configuree
- série aléatoire multithemes
- série aléatoire multiseries
[modifier] Les pages
Nous allons ici introduire la notion de page. Tout d'abord, précisons que l'on ne parle pas de "page html" et qu'il s'agit de définir la notion de page au sens module du terme.
Reprenons notre définition de module:
Un module peut se définir par un ensemble de scripts php présentant un ensemble de fonctionnalités communes.
Un module est donc un ensemble de fonctionnalités. Pour le module série, ses fonctionnalités, si l'on reprend le back-office de la v1, sont:
- Créer une série (Nouvelle série)
- Lister les séries (Liste des séries)
En effet, il y a bien une page dans laquelle on affiche le formulaire de création d'une série et une autre page dans laquelle on affiche la liste des séries.
Il y a bien sûr d'autres pages pour gérer les séries, mais elles ne correspondent pas à des fonctionnalités. En effet, prenons l'exemple de la création d'une série. Celle-ci se fait en 2 étapes (création de la série et association de ses évaluations) et l'on doit donc afficher 2 pages. Sur la plate-forme, les 2 sont pages sont liées. Cela correspond donc à une seule page au sens module du terme.
[modifier] Comment créer un module
Maintenant que nous avons défini les concepts liés au module, voici comment ces concepts sont mis en oeuvre, et donc comment faire pour créer son propre module.
[modifier] 1) Créer un répertoire
La première étape de création d'un module est l'application stricte de la définition simplifiée de module que nous nous sommes donné: module=repertoire.
Pour créer un module de back-office, il faut donc créer un répertoire, dans la racine du back-office. On respectera les conventions établies en nommant le repertoire avec un ou plusieurs mots séparés par des '_' (underscore).
[modifier] 2) Créer le manifest.xml
Nous avons vu aussi qu'un module était principalement composé de sous modules (ie: d'autres modules) et de pages. Il faut donc stocker ces informations, ce que nous ferons dans un fichier XML qui sera systématiquement nommé manifest.xml.
Donc, pour compléter notre création de module, nous ajouterons un fichier nommé manifest.xml à la racine du répertoire.
A ce stade, le gestionnaire de module implémenté dans le framework Astairs est capable de détecter la présence de notre nouveau module. Il reste donc à écrire le contenu du fichier manifest afin de donner les informations nécessaire à l'exploitation de notre module, et donc qu'il apparaisse dans le menu de back-office approprié avec l'ensemble des liens nécesssaires à son utilistation.
[modifier] Comment écrire un manifest
Le manifest, fichier nommé manifest.xml, est donc localisé à la racine d'un repertoire de module et doit contenir les informations nécessaires à son utilisation au sein de la plate-forme Astairs.
Voyons l'exemple du fichier manifest du module série:
<?xml version="1.0"?> <!DOCTYPE module SYSTEM "../lib/module/astairs_module_1.0.dtd"> <module> <title id="serie" version="1.00" type="RP"> Gestion des séries </title> <pages> <module id="serie_bloquante" version="1.00" type="RP">RQ Séries bloquantes</module> <module id="serie_aleatoire" version="1.00" type="RP">RQ Séries aléatoires</module> <page type="ADD" title="$MSG_1364" description="$BULLE_01">serie.php?action_serie=ajout_modification_serie</page> <page type="LST" title="$MSG_1365" description="$BULLE_01">serie.php?action_serie=lister_serie</page> </pages> </module>
Note: le fichier est ici épuré des balises non encore implémentées et ne concernant pas l'intégration d'un module telle que nous sommes entrain de la voir
[modifier] Le type de document et le DTD
Les 2 premières lignes du fichier manifest sont obligatoires dans tous les documents XML. Elles servent à indiquer le type du fichier et la version de XML utilisée, ainsi que le DTD qui contient les informations sur la structure des balises XML. Pour la plateforme, nous avons donc les lignes suivantes:
<?xml version="1.0"?> <!DOCTYPE module SYSTEM "../lib/module/astairs_module_1.0.dtd">
Elles indiquent donc que le fichier est écrit en XML 1.0 et que le DTD se trouve dans le reperoire ../lib/module/ et qu'il se nomme astairs_module_1.0.dtd Vous n'aurez pas à modifier ces lignes, excepté peut-etre le chemin du DTD si l'emplacement de votre manifest le requiert.
Pour information, le DTD va permettre la vérification du manifest.xml et donc d'éviter toute erreur de syntaxe qui pourrait avoir été faite lors de la saisie. (Il ne permet bien évidement pas la vérification valeurs saisies telles que les liens ou les messages de langue)
[modifier] Les balises <module> </module>
La première balise <module> est obligatoire. Elle permet d'indiquer au gestionnaire de module qu'il est bien entrain d'analyser un fichier contenant une description de module.
Ainsi, le ficher manifest.xml doit commencer par la balise <module> et finir par la balise </module>. L'ensemble du contenu du manifest devra être écrit entre ces 2 balises.
[modifier] Les balises <title> </title>
La balise <title> permet d'indiquer les propriétés principales du module. Voyons en détail comment sont écrites ces propriétés en reprennant notre exemple.
Nous avons donc la balise <title> suivante:
<title id="serie" version="1.00" type="RP"> Gestion des séries </title>
Tout d'abord, les attributs de la balise:
- id: Indique l'identifiant unique du module commun à toutes les plates-formes Astairs. Ce code doit donc être unique à chacun des modules et compréhensible afin que l'on sache à quoi sert le module. Par convention, on choisira le nom du repertoire du module, mais ce n'est pas obligatoire.
- version: Celà n'est pas encore implémenté et servira plus tard à gerer les versions des modules. Pour l'instant, mettons systématiquement "1.0", nous y reviendrons quand la fonctionnalité sera implémentée.
- type : Cet attribut permet de spécifier un type pour le module. Le type du module permet de grouper des modules, et donc au gestionnaire de menu de regrouper les modules en sous menus. (ex: Ressources humaines, Ressources pédagogiques, Ressources administratives.)
Voici le constructeur de l'objet AccueilBoMenuStruct(){ définissant ces types:
function AccueilBoMenuStruct(){ parent::ModuleMenuStruct(); $this->module_menus[]=new ModuleMenu("RH", MENU_2,"ressourcesHumaines"); //1er param: Type dans manifest.xml $this->module_menus[]=new ModuleMenu("RP", MENU_13,"ressourcesPedagogiques");//2eme param: message de langue affiché $this->module_menus[]=new ModuleMenu("RA", MENU_33,"ressourcesAdministratives");//3eme param: code, non géré actuellement }
Le libéllé entre le 2 balises est le libéllé qui sera affiché, dans les menus ou comme titre de page par exemple. Le libéllé est ici un texte en clair, il devra etre remplacé par un message de langue afin de supporter le multilingue. Ce remplacement devra être fait à l'implémentation de la fonctionnalité.
[modifier] Les balises <pages> </pages>
Nous avons vu qu'un module peut posséder des sous modules ou des pages. Cette balise indique donc ses éléments. Elle est unique pour un module.
Ainsi, on aura toujours, au minimum ces balises:
<module> <title> </title> <pages> </pages> </module>
[modifier] Contenu des balises <pages> </pages>
Ces balises peuvent contenir:
- aucune balise: Dans ce cas, le module n'a pas de pages ni de sous module. Celà signifie donc qu'il n'y a aucun lien vers les scripts php de ce module. Cela sera à utiliser pour les librairies.
- une ou plusieurs balises <module> </module> : Dans ce cas, il s'agit d'un module fictif, c'est à dire qu'il n'est composé que de sous-modules. Celà sera utilisé pour regrouper plusieurs modules. Par exemple, on créera un module fictif evaluations pour regrouper dans la page d'accueil les modules qcm, séries, remplir les blancs.
- une ou plusieurs balises <page> </page>: Dans ce cas, le module aura des liens vers des pages. Selon que le module soit un sous module, ou qu'il contienne des sous modules, les liens vers les pages apparaitrons à des endroits différents dans les menus de la plateforme (parge d'accueil ou menu de module par exemple).
- des balises <module> </module> et <page> </page> : Celà correspond au cas où le module contient des pages et des sous modules. C'est le cas pour notre exemple série. Là encore, ce cas présente des affichages différents selon les pages qui exploitent ce module. Actuellement, ce cas est utilisé dans les menus de modules, et pas en page d'accueil.
[modifier] Les balises <module> </module>
La balise <module> au sein des balises <pages> permettent d'indiquer la présence d'un sous module. Voyons en détail comment sont écrites ses propriétés en reprennant notre exemple.
Nous avons, pour notre exemple, donc la balise <module> suivante:
<module id="serie_bloquante" version="1.00" type="RP">RQ Séries bloquantes</module>
Tout d'abord, les attributs de la balise:
- id: Indique l'identifiant unique du module commun à toutes les plates-formes Astairs. Ce code doit donc correspondre à l'identifiant unique d'un module. On parle bien ici d'un module et non d'un sous module. C'est à dire qu'il s'agit de la valeur de l'attribut "id" d'une balise <title>.
- version: Celà n'est pas encore implémenté et servira plus tard à gerer les versions des modules. Pour l'instant, mettons systématiquement "1.0", nous y reviendrons quand la fonctionnalité sera implémentée.
- type : Cet attribut permet de spécifier un type pour le module. Le type du module permet de grouper des modules, et donc au gestionnaire de menu de regrouper les modules en sous menus. (ex: Ressources humaines, Ressources pédagogiques, Ressources administratives.) Ici, le type n'est acuellement pas utilisé, il le sera par la suite. Pour l'instant, nous mettrons le type du module auquel ce sous module fait référence.
Voici le constructeur de l'objet AccueilBoMenuStruct(){ définissant ces types:
function AccueilBoMenuStruct(){ parent::ModuleMenuStruct(); $this->module_menus[]=new ModuleMenu("RH", MENU_2,"ressourcesHumaines"); //1er param: Type dans manifest.xml $this->module_menus[]=new ModuleMenu("RP", MENU_13,"ressourcesPedagogiques");//2eme param: message de langue affiché $this->module_menus[]=new ModuleMenu("RA", MENU_33,"ressourcesAdministratives");//3eme param: code, non géré actuellement }
Les valeurs de la balise type possibles sont donc RH,RP et RA.
Le libéllé entre les 2 balises est un libéllé qui n'est ni affiché, ni utilisé actuellement. Celà sera certainement utilisé par la suite et nous préciserons son utilisation à l'implémentation de la fonctionnalité. Actuellement, nous recommandons de l'utiliser pour y mettre un libéllé à l'usage des développeurs, plus explicite que le l'id.
[modifier] Les balises <page> </page>
La balise <page> au sein des balises <pages> permettent d'indiquer la présence d'une Page dans le module. Voyons en détail comment sont écrites ses propriétés en reprennant notre exemple.
Nous avons, pour notre exemple, donc la balise <page> suivante:
<page type="LST" title="$MSG_1365" description="$BULLE_02">serie_aleatoire.php?action_serie=lister_serie_configuree&mode=0</page>
- type : Cet attribut permet de spécifier un type pour le sous module. Le type du module permet de grouper des modules, et donc au gestionnaire de menu de regrouper les modules en sous menus. Celà est utilisé par les menus de module pour afficher les liens part type (ex: Lister, créer, éditer, configurer, etc...) .
Voici le constructeur de l'objet ModuleBoModuleMenuStruct définissant ces types:
function ModuleMenuBoMenuStruct(){ parent::ModuleMenuStruct(); $this->module_menus[]=new ModuleMenu("ADD", MENU_2495,"aj"); //1er param: Type dans manifest.xml $this->module_menus[]=new ModuleMenu("LST", MENU_2496,"lst"); //2eme param: message de langue affiché $this->module_menus[]=new ModuleMenu("MOD", MENU_2497,"modif"); //3eme param: code, non géré actuellement $this->module_menus[]=new ModuleMenu("GEST", MENU_2498,"gestion"); $this->module_menus[]=new ModuleMenu("PARAM", MENU_2499,"param"); $this->module_menus[]=new ModuleMenu("CONF", MENU_2500,"conf"); }
Les valeurs de la balise type possibles sont donc ADD,LST,MOD,GEST,PARAM et CONF.
- title: Indique la valeur du message de langue pour afficher le libéllé du lien.
- description: Indique la valeur du message de langue pour afficher le message affiché dans la bulle du lien, c'est à dire la décription de la fonctionnalité apportant ainsi une aide à l'utilisateur.
Le texte entre les 2 balises est l'URL de la page vers laquelle on veut faire le lien.
Il est à noter que ce lien est un lien relatif calculé à partir du chemin du module et donc que le nom du fichier php doit correpondre à un fichier se trouvant à la racine du module.
De plus, le caractère '&' n'est pas autorisé naturelement dans le fichier XML, un traitement a été ajouté dans le parseur XML (ModuleLoader) afin de traiter ce caractère spécial (il est pratique de le savoir au cas ou d'autres caractères poseraient problème).
[modifier] L'exemple des séries
Reprenons notre exe
<pages> <module id="serie_bloquante" version="1.00" type="RP">RQ Séries bloquantes</module> <module id="serie_aleatoire" version="1.00" type="RP">RQ Séries aléatoires</module> <page type="ADD" title="$MSG_1364" description="$BULLE_01">serie.php?action_serie=ajout_modification_serie</page> <page type="ADD" title="$MSG_1504" description="$BULLE_01">../serie_bloquante/serie_bloquante.php</page> <page type="ADD" title="$MSG_1503" description="$BULLE_01">../serie_aleatoire/serie_aleatoire.php</page> <page type="LST" title="$MSG_1365" description="$BULLE_01">serie.php?action_serie=lister_serie</page> <page type="PARAM" title="$MSG_307" description="$BULLE_01">../baremes/bareme.php</page> <page type="PARAM" title="$MSG_327" description="$BULLE_01">../commentaire/commentaire.php</page> </pages>
[modifier] Comment faire fonctionner les scripts?
Il y a fort heureusement très peu de modifications à faire dans les scripts. Ces modifications sont OBLIGATOIRES et doivent être faites dans leur intégralité:
[modifier] Le début des scripts
[modifier] En V1
On trouve généralement celà au début des scripts PHP:
require('../dbpostgres.php3'); $db=pg_connect($server,"","","","$nombase"); require("$chemin_bo/lib/lib_calendrier.php"); require("$chemin_bo/lib/obj_formation.php"); require("./functions.inc.php");
[modifier] En V2
On remplacera par:
$dbpath="../.."; //le dbpath sert à maintenir les inclusions à partir du $chemin_bo include("$dbpath/en_tete.php"); //contient les traitements communs à l'ensemble du FrameWork Astairs include("../en_tete_back.php"); //contient les traitements communs à l'ensemble du BackOffice Astairs require("$root/lib/lib_langue.php");
Il y a fort heureusement très peu de modifications à faire dans les scripts. Ces modifications sont OBLIGATOIRES et doivent être faites dans leur intégralité:
[modifier] La fin des scripts
[modifier] En V1
On trouve généralement celà à la fin des scripts PHP:
include('../piedpage.php3');
[modifier] En V2
On remplacera par:
include("$dbpath/pied_page.php");
[modifier] Les autres modifications
C'est tout!
On veillera cependant à faire attention au modification de chemin entre V1 et V2, notamment:
* $chemin_bo et $chemin_fo: Ils sont conservés mais ne font plus référence à 2 arborescences distinctes, mais à 2 repertoire de la racide de la PGR. * plus de cas particuliers pour les PGR, toutes les plates-formes sont des PGR. * une nouvelle variable $root, indique le chemin racide de la PGR, où sont localisés les répertoires $chemin_bo et $chemin_fo. * Les libraires (repertoires lib et lib_graphique ne sont plus dans le BO ($chemin_bo) mais à la racine de la PGR (dans $root)
[modifier] Pour finir
Intégrez les modules v1 sur la v2 au fur et à mesure de vos besoins.
Il s'agit d'une intégration partielle, vous permettant de disposer de modules back-office sur la v2. Lorsque les fonctionnalités manquantes de la gestion des modules sera terminée, et que cette doc sera complétée, nous finirons completement l'intégration.
N'hésitez pas à modifier cette documentation si besoin et d'y reporter les indications supplémentaires que vous obtiendrez si vous me posez des questions(en cas de besoin).
Bon courage.
Rémi Cocquet 23 octobre 2007 à 16:29 (CEST)