Guide de développement
Guide de développement
Introduction
définitions, vocabulaire, principes généraux, architecture & composants d'une application
Ce guide a pour objectif de proposer aux développeurs un cadre dans lequel ils peuvent développer et maintenir un module Dynacase.
Ce guide défini les processus et les outils à utiliser pour créer son module. Il ne va pas définir techniquement l'usage des outils à utiliser mais fournira des liens sur les documentations nécessaires à la maîtrise de ces outils.
Vocabulaire :
| Définition | |
|---|---|
| module | Un module Dynacase contient la définition et l'ensemble des éléments nécessaires au fonctionnement de zéro, une ou plusieurs applications. Elle contient la définition et l'ensemble des éléments nécessaires (cycle de vie, profil, ….) à l'utilisation de zéro, une ou plusieurs familles. |
| application | Une application Dynacase permet de couvrir une fonctionnalité spécifique au système documentaire (exemple: gestion des utilisateurs, administration des contrôle qualité). Une application utilise souvent une ou plusieurs familles de document afin de réaliser leurs fonctions. Une application Dynacase est composée de une à plusieurs actions. Une application possède généralement une interface principale qui permet d'accéder à l'ensemble des actions nécessaires à l'application. Une application est accessible directement par une url directe et est considéré comme autonome vis-à-vis d'autre application. |
| action | Une action Dynacase réalise une fonction d'une application. Cette action reçoit des paramètres, réalise un traitement et retourne le résultat de ce traitement. L'action Dynacase est composée de deux parties : le traitement et la représentation du résultat du traitement. Chacune de ses deux parties est optionnelle mais il en faut au moins une des deux. Le traitement est réalisé à l'aide d'une fonction PHP qui utilise des fonctions de l'API Dynacase. La représentation est réalisée à l'aide d'un template (appelé aussi layout). Ce template permet de réaliser des sorties HTML avec des parties dynamiques. |
| interface | L'interface Dynacase est la représentation d'une action. |
| template, layout | le template est le modèle de représentation. Ce modèle est généralement du HTML avec des parties dynamiques qui sont construite dans le traitement de l'action. Ce modèle peut aussi être n'importe de n'importe quel type ascii tel que csv ou xml. Le seul modèle binaire possible est le format openDocumentText. Ce type de modèle permet d'avoir des représentations utilisables pour des besoins d'impressions. Ces modèles sont utilisés pour les représentations des actions et aussi pour les vues de documents |
| zone | Une zone Dynacase est une action qui ne peut pas être appelée directement depuis l'interface principale. Une zone peut être considéré comme un fragment d'action. Sa représentation est souvent un fragment HTML (le contenu d'une DIV ou d'une TABLE). La zone est réutilisable dans différentes représentations d'actions. Elle permet de réutiliser des fragments d'interfaces dans les différentes interfaces de haut niveau. Une zone peut elle aussi faire référence à d'autres zones. On peut ainsi assembler des interfaces avec des niveaux différents réutilisable. |
| document | Le document Dynacase contient un ensemble structuré d'informations. Il peut être associé à un cycle de vie et porte ses propres paramètres de sécurité d'accès. Un document est toujours associé à une famille de document. |
| attribut | Un attribut de document défini un type syntaxique (texte, nombre, date, …) ainsi que son emplacement dans la structure d'information du document. |
| famille | La famille permet de donner une unité à un ensemble de document de même type sémantique (compte-rendu, facture, client, recette de cuisine,…). La famille défini la structure de l'information qui sera commune à l'ensemble des documents de cette famille. Cette structure est composée d'attributs du document. Elle défini aussi les règles de sécurités d'accès et l'accès au cycle de vie. |
| vues | Une vue de document désigne un représentation de celui-ci. Cette vue est généralement associé à un template qui lui confère un aspect particulier. Une permet aussi masquer ou de démasquer un ou plusieurs attributs du documents. |
| fichier | Le fichier est un type d'attribut particulier. La famille peut déclarer un ensemble d'attribut “fichier” . Le fichier n'est nullement obligatoire dans la définition d'un document. L'accès au fichier ainsi que son contrôle d'accès se fait toujours au travers du document. Les fichiers peuvent se retrouver dans des attribut tel que : “annexes”, “esquisse du modèle”, “photographie”. |
| cycle de vie | Le cycle de vie définit l'ensemble des activités à réaliser, les états et transitions possibles du documents. Un cycle peut être associé à un document; dans ce cas le document est soumis aux contrôles imposé par le cycle. à chaque changement d'état, l'ancien état du document est conservé afin de tracer et de pouvoir voir les informations des états précédents. |
| profil | Le profil d'un document décrit une matrice de droits. Les droits les plus usuel sont 'voir','modifier', 'supprimer'. Pour chacun des ces droits, le profil défini quels groupes d'utilisateurs ou quels utilisateurs en particulier ont cette habilitation. Les droits des groupes sont propagés automatiquement sur les membres de groupes et des éventuels sous-groupes. Le même profil peut être partagé par plusieurs documents. Cela permet de modifier plus facilement les accès à un ensembles de document de même niveau de sécurité. Généralement, un même profil est partagé par les documents d'une même famille. |
Description de l'espace de développement type
Pour développer un module Dynacase, un répertoire contenant les différents fichiers de configuration est nécessaire. Ce répertoire sera nommé “répertoire source”.. II contient l'ensemble des éléments nécessaire à la publication du module afin de réaliser des tests unitaires et à la création de fichier d'exportation au format “webinst” nécessaire à une installation par dynacase-control.
hiérarchie des répertoires
Initialisation de la hiérarchie de répertoire pour la création d'un module mono application.
On récupère une archive et on lance le programme d'initialisation (demande de nom du module et de l'application).
| Fichier/répertoire | Description | Principaux liens vers la documentation |
|---|---|---|
 <APP>_app | Fichier de description de l'application ainsi que les définitions des différentes actions possibles | Fichier .app |
| <APP>_init.php.in | Fichier de description des paramètres de l'application. | Fichier _init.php |
 <APP>_fr.po | Catalogue des traductions pour le français | Fichiers po |
| <APP>_en.po | Catalogue des traductions pour l'anglais | |
 <APP>_post | Fichier de description des post-traitemement à effectuer lors de l'installation ou la mise à jour | |
 info.xml.in | Fichier de description du module | info.xml |
 configure.in | Fichier de configuration servant à générer le fichier configure qui servira à générer les fichiers résultats à partir des fichiers .in | |
| Makefile.in | Fichier Makefile décrivant l'ensemble des fichiers à publier et le traitement à réaliser pour la publication | |
| Pubrule | Fichier de règles générales sur lesquels les Makefiles s'appuient. | |
| VERSION | Fichier contenant la version du module sous la forme X.Y.Z. X,Y et Z sont des chiffres. X est le n° de version majeure, Y celui de version intermédiaire et Z celui version mineure. | |
| RELEASE | Fichier contenant le n° de release. contenant un nombre positif ou zéro. | |
 Families | Fichiers ods de définitions des structures Fichiers des méthodes du document. Fichiers des templates de vues de documents Fichiers ods de définitions des profils Fichiers d'aide à la saisie | Structure famille avec fichier .ods Méthodes de documents |
| Families/Views | Fichiers des templates de vues de documents (xml/odt) | Vues spécifiques |
| Families/Externals | Fichiers d'aide à la saisie Fichier de définition des recherches spécialisées | Aide à la saisie Recherche spécialisée |
| Actions | Fichiers décrivant les actions. Cela comprend les fichiers PHP pour les traitements, les fichiers templates pour les résultats des traitements | Construction d'une action |
| Actions/Zones | Fichiers décrivant les zones. Cela comprend les fichiers PHP pour les traitements, les fichiers templates pour les résultats des traitements | Définitions des zones |
| Scripts | Fichiers PHP pouvant être lancé par la commande wsh. Ces fichiers définissent des traitements qui peuvent être fait par ligne de commande. Ils servent généralement à effectuer des opérations d'exploitations comme un recalcul sur en ensemble de documents ou une opération d'importation cyclique par exemple. | Utilisation de wsh |
| Images | Différents fichiers images (PNG/JPEG) utilisé pour les vues, les templates et les icônes de familles. |
Gestion de configuration
Le répertoire source d'un module doit être géré en configuration afin de garder un historique de toutes les modifications et aussi afin de pouvoir le cas échéant gérer plusieurs versions en parallèle de votre module.
Si votre module ne nécessite pas un développement de plusieurs équipes de développeurs, la gestion de configuration peut être faite avec SVN. Dynacase utilise l'outil GIT qui permet plus facilement de se créer différentes branches de développement par développeur. Par contre sa maitrise reste plus complexe que SVN.
Cette gestion de configuration possède une branche par version intermédiaire (X.Y). Les versions Y impaires sont dites de développement (en test). Les versions Y paires sont dites stable. Les versions mineures servent à indiquer l'avancement des différentes corrections dans chacune des branches. Lors de chaque modification de la configuration, le fichier RELEASE ou le fichier VERSION doit aussi être mis à jour pour indiquer la modification. A chaque incrémentation du fichier VERSION, le fichier RELEASE doit être remis à zéro. La partie changelog du fichier info.xml.in doit aussi être modifiée afin d'avertir l'installateur des modifications apportées à la version.
Traduction
Les traductions des éléments d'interfaces et des messages se fait à l'aide de l'outil gettext. Cet outil fonctionne à l'aide de catalogue de traduction, un par langue. L'application Dynacase utilise un seul catalogue pour l'ensemble des traduction du noyau et de l'ensemble des modules. Ceci implique que les mots ou les phrases à traduire doivent être unique par module. Pour cela, il est fortement conseillé d'utiliser un préfix unique à ces mots ou phrase par module. Ainsi par exemple le clef du mot “yes” sera “app:yes” et qui sera traduit par “oui” en français et par “yes” en anglais. Les entêtes des fichiers po de votre module doivent indiquer l'utilisation de l'encodage UTF-8. Les programmes d'éditions des .po prennent en compte ces entêtes pour sauvegarder le fichier avec ce bon encodage.
Pour détecter les nouveaux mots à traduire, il faut lancer la commande “make po”. Cela va ajouter les nouveaux mots à traduire et supprimer les éventuels mots qui ne sont plus référencé dans aucun des fichiers. Une fois les catalogues mis à jour vous devez ensuite effectuer les traductions. Ces fichiers doivent être éditer par des logiciels spécifiques afin d'éviter des erreurs de syntaxe. Il existe gtranslator sous gnome et kbabel sous kde.
Les traductions sont remplacés littéralement dans les fichiers produit par le serveur. Il faut être particulièrement vigilant lorsque ceux-ci sont entre des double quotes ou des simple quote. En effet un texte javascript: qui sera traduit "l'automne" pourra donner lieu à une erreur de syntaxe. Il est alors préférable d'utiliser les double quote alert("[TEXT:my:the automn]")qui sont moins utilisés dans des traductions.
Paramétrage et développement Dynacase
Les familles
ODS
Les fichiers de définition des structures des familles sont définis dans des fichiers ods (openDocument spreadsheat). Ils sont enregistrés dans le répertoire Families. L'ensemble des familles utilisés conjointement dans un module doivent être rassemblé dans un même fichier ods. Chacune des familles occupant un onglet du fichier. Il est possible d'avoir plusieurs fichiers si vous avez des groupes de familles qui sont faiblement liés.
Ces fichiers de structures doivent être référencé dans le fichier de post-traitement info.xml.in dans la section update :
<post-upgrade> <process command="programs/pre_migration MYMODULE" /> <process command="./wsh.php --api=freedom_import --file=./MYMODULE/my_family.ods"> <label lang="en">Importing Testing Families</label> </process> <process command="programs/post_migration MYMODULE" /> <process command="programs/update_catalog" /> </post-upgrade>
Les fichiers ods étant publié à la racine de votre module, il faut alors indiquer le chemin d'accès aux fichiers ods du serveur (il n'y a pas de répertoire Families comme dans vos sources).
Les noms des familles (les noms internes pas les libellés) choisis doivent être préfixé par un trigramme unique lié à votre module. Exemple : 'MYM:ANIMAL' ou 'MYM:CAKE'.
Méthode
Les fichiers “méthodes” permettant de modifier le comportement des documents ou d'ajouter des fonctionnalités sont préfixés par Method. suivi par le nom de votre famille. Exemple : Method.mym:animal.php. Les fichiers Méthode étant publiés dans un répertoire unique il est primordial d'avoir un nom non utilisé dans d'autres modules. Les fichiers méthodes se trouvent dans le même répertoire que les fichiers ods de structure de famille.
Vues et template
Cycle de vie
ODS
Méthode
Sécurité
Groupe
Droits
Interface Utilisateur
utilisation des interfaces standards
développement à l'aide de freedom-extui
développement à l'aide de freedom-fdl
Initialisation / migration
Publication
Mise au point
Afin de valider votre module et faire de la mise au point, il est nécessaire d'avoir installé Dynacase localement sur votre machine de développement. Si vous ne pouvez pas installer Dynacase sur votre machine, vous pouvez aussi installer Dynacase sur une autre machine (virtuelle ou non). Dans le cas d'une installation sur une machine externe, vous devrez effectuer un point de montage nfs (en lecture/écriture) sur le répertoire d'installation de Dynacase. Supposons que la racine d'installation est '/var/www/test'.
Initialisation
à faire la première fois ou lorsque le répertoire de destination change
eric@tarfful(2.15):~/freedom/mymodule$ autoconf eric@tarfful(2.15):~/freedom/mymodule$ ./configure --prefix=/var/www/test checking for /home/eric/devtools/PubRule... yes checking for /home/eric/devtools//PubRule... yes configure: PubRule located at /home/eric/anakeen/devtools/ configure: creating ./config.status config.status: creating Makefile config.status: creating MYMODULE_init.php config.status: creating info.xml eric@tarfful(2.15):~/freedom/mymodule$
Publication
à faire à chaque modification de code
eric@tarfful(2.15):~/freedom/mymodule$ sudo -u www-data make publish cp -f MYMODULE_init.php /var/www/test//MYMODULE/MYMODULE_init.php cp -f MYMODULE.app /var/www/test//MYMODULE/MYMODULE.app cp -f info.xml /var/www/test//MYMODULE/info.xml msgfmt -v MYMODULE_en.po -o /var/tmp/en.gmo; 0 message traduit, 43 messages non traduits. cp -f /var/tmp/en.gmo /var/www/test/locale/en/LC_MESSAGES/MYMODULE.mo msgfmt -v MYMODULE_fr.po -o /var/tmp/fr.gmo; 41 messages traduits. cp -f /var/tmp/fr.gmo /var/www/test/locale/fr/LC_MESSAGES/MYMODULE.mo ... eric@tarfful(2.15):~/freedom/mymodule$
Mise à jour des catalogues de traduction
Lorsque vous avez mis à jour vos fichier .po. Vous devez publier les catalogues de vos module (make publish). Pour re-générer le catalogue général utilisé par Dynacase vous devez ensuite lancer la commande suivante.
eric@tarfful(2.15):~/reedom/mymodule$ sudo -u www-data /var/www/test/whattext
msgcat: AVERTISSEMENT : Les fichiers d'entrée contiennent des messages dans plusieurs encodages, dont l'UTF-8.
L'ensemble a été converti en UTF-8.
msgcat: AVERTISSEMENT : Les fichiers d'entrée contiennent des messages dans plusieurs encodages, dont l'UTF-8.
L'ensemble a été converti en UTF-8.
Les messages d'avertissement indiquent que des catalogues n'utilise pas l'encodage UTF-8. Cela n'a pas d'impact car lors de construction du catalogue principal ces catalogues de modules ont été retranscrit correctement
Mise à jour des familles
Lors que vous effectuez une modification de la structure d'une famille (fichier ods) ou d'un fichier méthode, il est nécessaire, après publication, de lancer une re-génération des classes documentaires de votre module. Pour cela vous devez lancer le script de mise à jour de votre module :
eric@tarfful(2.15):~/anakeen/eric$ sudo -u www-data /var/www/test/wsh --api=freedom_import --file=/var/www/test/MYMODULE/my_family.ods
Cette commande étant longue il est conseillé de se faire un alias afin de simplifier l'écriture. Il faut bien sûr, comme décrit dans les paragraphes précédents, avoir renseigné le fichier de famille à importer dans le fichier info.xml.in dans sa partie post-upgrade.
L'ensemble de ces commandes peut être réalisée de manière automatique à l'aide de dynacase-control en ligne de commande.
Empaquetage
Pour installer le module en production ou dans sur un autre serveur, il est nécessaire de produire un fichier de type “webinst” pour que dynacase-control le prennent en compte. Pour fabriquer un fichier webinst, il faut au préalable s'assurer que tous ces fichiers sont enregistrés en configuration. Il est important de modifier la partie “changelog” du fichier info.xml.in pour notifier à l'installateur la nature des modifications apportées.
Ensuite il faut “tagguer” la configuration avec la version. Ensuite vous pouvez effectuer la commande “make webinst” pour générer le fichier webinst. Ce fichier est créé avec le nom du module donné lors de l'initialisation.
Sur votre serveur, à l'aide de dynacase-control, vous pouvez maintenant installer ou mettre à jour votre module en téléchargeant votre fichier webinst..
Si votre serveur dynacase-control est local, vous pouvez utiliser dynacase-control en mode de commande shell pour réaliser votre mise à jour.
make webinst sudo /var/www/dynacase-control/wiff context Dév module upgrade mymodule-0.1.0.webinst
Tuning
Ressources
