5.2 Mise en place des structures
Ce chapitre va vous permettre d'initialiser vos premières familles.
5.2.1 Objectifs
- Créer une famille de base,
- Créer les familles en utilisant l'héritage,
- Initialiser les attributs,
- Initialiser les stubs,
- Faire une première traduction,
- Déployer votre module.
5.2.2 Cadre
L'analyse des besoins a montré que votre application nécessite les familles suivantes :
- Référentiel qualité
-
elle représente un référentiel qualité et contient :
- la désignation d'un référentiel qualité.
- Chapitre de référentiel
-
elle représente un chapitre et contient :
- un lien à un référentiel,
- un titre.
- Audit
-
elle représente un audit et contient :
- le titre de l'audit,
- sa date de début,
- sa durée en jours,
- sa date de fin,
- le site audité,
- un champ descriptif,
- le responsable de l'audit,
- la liste des auditeurs,
- une liste de référentiels,
- une liste de points forts, avec pour chacun :
- un encart de texte,
- une liste de points faibles, avec pour chacun :
- un encart de texte,
- une liste de fiches de non-conformité,
- une liste de fichiers associés.
- Fiche de non-conformité
-
elle représente une non-conformité et contient :
- le titre de la non-conformité,
- un lien vers la fiche d'audit,
- un rédacteur,
- une liste de liens vers des chapitres de référentiel, avec pour chacun :
- un lien vers le référentiel,
- un lien vers le chapitre,
- un texte explicitant le manquement,
- une liste d'actions, avec pour chacune :
- un descriptif,
- un responsable,
- une date de prise en compte.
5.2.3 Partie théorique
5.2.3.1 Structure de famille
La structure d'une famille est définie par deux éléments :
- le fichier de structure
- il contient la liste des attributs (type de données) que les documents de la famille contiennent,
- l'héritage
- si une famille hérite d'une autre, elle hérite de manière dynamique de tous les éléments de ses familles parentes.
La structure de la famille est utilisée en interne par Dynacase pour :
- créer la table de la base de données permettant de stocker les données,
- générer les formulaires de saisie des données,
- générer les formulaires de recherche de documents,
- générer les matrices de gestion de droits,
- générer les stubs,
- etc.
5.2.4 Création de votre première famille : Famille de base
À la liste des familles identifiées de manière fonctionnelle, nous allons ajouter une famille dite de base, dont toutes les familles de l'application hériteront. Cette méthode est une bonne pratique pour débuter un projet Dynacase. Ceci permet de propager plus facilement des comportements spécifiques entre toutes les familles d'un projet.
Par exemple, si vous souhaitez empêcher la duplication de tous les documents au sein de votre projet,
vous pouvez le spécifier au niveau de la famille mère et le comportement est transmis à toutes les familles filles.
De même, comme nous le verrons plus tard, cela permet de mettre en place une vue commune à toutes ces familles.
Ouvrez une console et rendez vous dans le répertoire de votre application et lancez la commande suivante :
<devtool> createFamily -s . -n COGIP_AUDIT_BASE -m COGIP -a COGIP_AUDIT
La commande createFamily permet de créer des familles Dynacase. La liste de ses options est accessibles avec l'option --help.
Les options utilisées ci dessus sont :
-
-s
: emplacement des sources (dans notre exemple le répertoire courant), -
-n
: nom logique de la famille, -
-m
: namespace de la famille, -
-a
: application contenant la famille.
Les fichiers suivants sont générés :
├ COGIP_AUDIT ├─ COGIP_AUDIT_BASE__CLASS.php ├─ COGIP_AUDIT_BASE__PARAM.csv └─ COGIP_AUDIT_BASE__STRUCT.csv
Les fichiers ci-dessus sont pré-remplis et prêts à être utilisés. Leur nomenclature est explicitée dans l'annexe.
Vous devez maintenant indiquer dans le fichier info.xml
que cette famille doit être importée lors de l'initialisation
et la mise à jour. Vous allez ajouter les lignes suivantes :
<process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COPGIP_AUDIT_BASE__STRUCT.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COPGIP_AUDIT_BASE__PARAM.csv --csv-separator=';' '/>
Ces deux lignes vous sont retournées par la commande de création des fichiers.
à 2 endroits :
- dans la partie d'initialisation, après l'import des utilisateurs
- dans la partie d'upgrade, après le
record_application
.
Vous devez avoir un fichier info.xml
semblable à :
<post-install> <process command="programs/record_application COGIP_AUDIT" /> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/ROLE__INIT_DATA.csv --csv-separator=';''/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/IGROUP__INIT_DATA.csv --csv-separator=';''/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/IUSER__INIT_DATA.csv --csv-separator=';''/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COPGIP_AUDIT_BASE__STRUCT.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COPGIP_AUDIT_BASE__PARAM.csv --csv-separator=';''/> <process command="programs/update_catalog" /> </post-install> <post-upgrade> <process command="programs/pre_migration COGIP_AUDIT" /> <process command="programs/record_application COGIP_AUDIT" /> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COPGIP_AUDIT_BASE__STRUCT.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COPGIP_AUDIT_BASE__PARAM.csv --csv-separator=';''/> <process command="programs/post_migration COGIP_AUDIT" /> <process command="programs/update_catalog" /> </post-upgrade>
5.2.5 Création des fichiers de familles
Vous allez maintenant créer les autres familles, reprenez la ligne de commande ci-dessus pour chacune des familles présentées ci-dessous.
-
Référentiel qualité
:<devtool> createFamily -s . -n COGIP_AUDIT_REFERENTIEL -p COGIP_AUDIT_BASE -m COGIP -a COGIP_AUDIT
-
Chapitre
:<devtool> createFamily -s . -n COGIP_AUDIT_CHAPITRE -p COGIP_AUDIT_BASE -m COGIP -a COGIP_AUDIT
-
Audit
:<devtool> createFamily -s . -n COGIP_AUDIT_AUDIT -p COGIP_AUDIT_BASE -m COGIP -a COGIP_AUDIT
-
Fiche de non-conformité
:<devtool> createFamily -s . -n COGIP_AUDIT_FNC -p COGIP_AUDIT_BASE -m COGIP -a COGIP_AUDIT
Vous avez créé l'ensemble des fichiers qui vont définir vos familles.
Il faut maintenant les référencer dans le fichier info.xml
. Pour ce faire, vous devez respecter l'ordre de l'héritage
et importer les familles mères puis les familles filles.
Si vous ne suivez pas un ordre adéquat, l'installeur refusera d'installer le paquet et vous indiquera le problème.
Votre info.xml
contient les lignes suivantes :
<post-install> <process command="programs/record_application COGIP_AUDIT"/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/ROLE__INIT_DATA.csv --csv-separator=';''/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/IGROUP__INIT_DATA.csv --csv-separator=';''/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/IUSER__INIT_DATA.csv --csv-separator=';''/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_BASE__STRUCT.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_BASE__PARAM.csv --csv-separator=';''/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_REFERENTIEL__STRUCT.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_REFERENTIEL__PARAM.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_CHAPITRE__STRUCT.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_CHAPITRE__PARAM.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_AUDIT__STRUCT.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_AUDIT__PARAM.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_FNC__STRUCT.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_FNC__PARAM.csv --csv-separator=';' '/> <process command="programs/update_catalog"/> </post-install> <post-upgrade> <process command="programs/pre_migration COGIP_AUDIT"/> <process command="programs/record_application COGIP_AUDIT"/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_BASE__STRUCT.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_BASE__PARAM.csv --csv-separator=';''/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_REFERENTIEL__STRUCT.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_REFERENTIEL__PARAM.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_CHAPITRE__STRUCT.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_CHAPITRE__PARAM.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_AUDIT__STRUCT.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_AUDIT__PARAM.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_FNC__STRUCT.csv --csv-separator=';' '/> <process command='./wsh.php --api=importDocuments --file=./COGIP_AUDIT/COGIP_AUDIT_FNC__PARAM.csv --csv-separator=';' '/> <process command="programs/post_migration COGIP_AUDIT"/> <process command="programs/update_catalog"/> </post-upgrade>
Vous pouvez retrouver l'ensemble de ces fichiers initialisés dans les sources du chapitre complété.
5.2.6 Ajout des attributs
Vous allez maintenant définir les attributs contenus dans vos familles.
5.2.6.1 Référentiel qualité
Vous allez commencer par la famille Référentiel qualité
. Ouvrez le fichier ./COGIP_AUDIT/COGIP_AUDIT_REFERENTIEL__STRUCT.csv
.
Le fichier se présente sous cette forme :

Figure 27. Contenu structure site
Dans cette capture d'écran, vous remarquez que le fichier est coloré. Vous pouvez obtenir ce comportement (ainsi que d'autres aides) en suivant l'annexe. Dans la suite du tutoriel, ces scripts sont considérés comme installés.
Attention : un attribut non-structurant (texte, relation, numérique, …) doit obligatoirement être contenu dans un attribut structurant frame ou array.
Pour définir un attribut, vous devez saisir :
- dans la colonne
A
: le mot clefATTR
; - dans la colonne
B
: l'identifiant unique de l'attribut, celui-ci est alphanumérique et écrit de préférence en minuscules ; - dans la colonne
C
: l'attribut encadrant de l'attribut en cours (cet élément est nécessaire pour les attributs non-structurants, c'est à dire les attributs qui contiennent des données, text, int, etc.) ; - dans la colonne
D
: la valeur de traduction par défaut du label de l'attribut, - dans la colonne
E
:Y
ouN
selon que l'attribut est utilisé pour composer le titre ou non - dans la colonne
G
: le type de l'attribut, - dans la colonne
H
: l'ordre d'affichage des attributs. Cet élément est utile dans le cas d'héritage entre famille, il permet de dire dans quel ordre doivent être affichés les attributs ; - dans la colonne
I
: la visibilité par défaut de l'attribut.
Dans le cas des Référentiel qualité
, vous devez obtenir une structure similaire à :

Figure 28. Contenu structure référentiel
Quelques astuces pour faciliter l'écriture des familles :
-
il est préférable de composer les noms d'attributs de la manière suivante :
- un préfixe pour indiquer leur famille de provenance (utile dans le cas d'un héritage),
- une lettre pour indiquer le type d'encadrant lorsque l'attribut est en encadrant (
f
pour frame,a
pour array,t
pour tab), - un nom explicitant l'information portée par l'attribut.
Ce qui donne, par exemple :
fam_f_general
-
dans le cas particulier des tableaux, la composition suivante est conseillée :
- le nom du tableau (sans le
a
), - un nom explicitant l'information portée par l'attribut.
Ce qui donne, par exemple :
fam_a_fichiers
, puisfam_fichiers_file
etfam_fichiers_commentaire
- le nom du tableau (sans le
vous pouvez commencer en complétant uniquement les colonnes
A
,B
,D
,G
puis au moyen des scripts décrits en annexe.
Vous pouvez voir ci-dessous un exemple de construction sur la famille chapitre.

Figure 29. Exemple de construction
Vous pouvez retrouver le fichier complété dans les sources.
5.2.6.2 Chapitre
Vous allez maintenant compléter la famille chapitre
.
Cette famille contient un lien vers son référentiel, de manière a pouvoir retrouver facilement tous les chapitres d'un référentiel.
Ouvrez le fichier ./COGIP_AUDIT/COGIP_AUDIT_CHAPITRE__STRUCT.csv
, et complétez-le pour obtenir une structure similaire à :

Figure 30. Contenu structure Chapitre
Vous pouvez remarquer la présence d'un nouveau type d'attribut docid. Ce type d'attribut référence un document et permet de créer des liens entre les fiches. Il est présenté :
- en édition : sous la forme d'une liste déroulante qui vous permet de choisir le document à lier,
- en consultation : sous la forme d'un lien hypertext pointant vers le document lié.
Dans la définition du docid
, la référence à la famille Référentiel
indique la nature du lien,
et permet de n'afficher en édition que les documents issus de cette famille.
Vous pouvez retrouver le fichier complété dans les sources.
5.2.6.3 Fiche de non-conformité
Vous allez maintenant compléter la Fiche de non-conformité
.
Ouvrez le fichier ./COGIP_AUDIT/COGIP_AUDIT_FNC__STRUCT.csv
, et complétez le pour obtenir une structure similaire à :

Figure 31. Contenu structure FNC
Vous pouvez remarquer la présence de deux nouveaux éléments structurants :
-
array : un
array
permet de gérer la multiplicité d'une liste d'attributs (un n-uplet) : chaque attribut est matérialisé par une colonne, et chaque ligne porte une valeur du n-uplet (liste des valeurs unitaires des attributs), -
tab : un
tab
est représenté sous la forme d'un onglet dans le formulaire. Il permet d'organiser les informations à présenter, d'avoir une présentation plus lisible et éviter des formulaires trop long.
Vous pouvez retrouver le fichier complété dans les sources.
5.2.6.4 Audit
Vous allez maintenant compléter votre dernière famille, la Fiche d'audit
.
Ouvrez le fichier ./COGIP_AUDIT/COGIP_AUDIT_AUDIT__STRUCT.csv
, et complétez le pour obtenir une structure similaire à :

Figure 32. Contenu structure Audit
Attention : Dans la spécification, il est indiqué que l'audit porte plusieurs référentiels. Vous devez donc ajouter
dans la colonnes options
(P
), l'option multiple=yes
.
Vous pouvez retrouver le fichier complété dans les sources.
Bravo ! Vous avez initialisé l'ensemble des familles.
5.2.7 Génération des stubs
Vous allez maintenant produire les stubs. Ce sont des fichiers PHP qui sont générés pour aider au développement de l'application.
Si vous ouvrez le fichier ./COGIP_AUDIT/COGIP_AUDIT_AUDIT__CLASS.php
, vous avez le contenu suivant :
namespace Cogip; use \Dcp\AttributeIdentifiers\COGIP_AUDIT_AUDIT as MyAttributes; Class COGIP_AUDIT_AUDIT extends \Dcp\Family\COGIP_AUDIT_BASE { }
Les deux classes référencées dans ce fichier n'existent pas encore : elles sont générées automatiquement sur le serveur lors de l'importation des familles.
Vous pouvez générer des classes de référence, les stubs, qui permettent d'utiliser la complétion sur votre IDE. Ces classes ne contiennent que les éléments qui vous seront utiles lors du développement et ne sont pas tout à fait semblables à celles générées sur le serveur.
Ouvrez une console et rendez vous dans le répertoire de votre application et lancez la commande suivante :
<devtool> generateStub -s . -o ./stubs/
L'outil a généré les stubs dans le nouveau sous-répertoire stubs
dans le répertoire de vos sources :
├ stubs ├─ cogip_audit_audit__STUB.php ├─ cogip_audit_base__STUB.php ├─ cogip_audit_chapitre__STUB.php ├─ cogip_audit_fnc__STUB.php └─ cogip_audit_referentiel__STUB.php
Les fichiers stubs contiennent :
- les classes intermédiaires générées sur le serveur (une classe par famille, sous le namespace
\Dcp\Family
) qui permettent d'avoir la chaîne d'héritage complète et la complétion via les IDE, - les classes d'attributs (une classe par famille, sous le namespace
\Dcp\AttributeIdentifiers
) qui contiennent la liste des attributs définis dans les fichiers__STRUCT.csv
et permettent de référencer les attributs en utilisant la complétion.
Vous pouvez retrouver les stubs sur github.
Exemple de complétion d'attribut à l'aide des stubs :

Figure 33. Complétion d'attribut
5.2.8 Internationalisation
Vous allez maintenant extraire les clefs permettant de traduire vos familles.
Ouvrez une console et rendez vous dans le répertoire de votre application et lancez la commande suivante :
<devtool> extractPo -s .
Des nouveaux fichiers de po sont ajoutés, il en existe un par famille et par langue.
./locale ├── en │ └── LC_MESSAGES │ └── src │ ├── COGIP_AUDIT_AUDIT_en.po │ ├── COGIP_AUDIT_BASE_en.po │ ├── COGIP_AUDIT_CHAPITRE_en.po │ ├── COGIP_AUDIT_en.po │ ├── COGIP_AUDIT_FNC_en.po │ └── COGIP_AUDIT_REFERENTIEL_en.po └── fr └── LC_MESSAGES └── src ├── COGIP_AUDIT_AUDIT_fr.po ├── COGIP_AUDIT_BASE_fr.po ├── COGIP_AUDIT_CHAPITRE_fr.po ├── COGIP_AUDIT_FNC_fr.po ├── COGIP_AUDIT_fr.po └── COGIP_AUDIT_REFERENTIEL_fr.po
Chacun de ces fichiers contient l'ensemble des clefs permettant de traduire les labels des attributs et des énumérés de la famille qu'il référence.
Pour chaque attribut est généré le bloc suivant :
#: COGIP_AUDIT/COGIP_AUDIT_AUDIT__STRUCT.csv #, fuzzy msgid "COGIP_AUDIT_AUDIT#caa_titre" msgstr "Titre"
La traduction présente est celle que vous avez notée dans le fichier CSV.
La notation fuzzy
indique que la traduction est une proposition pour aider le traducteur.
#: COGIP_AUDIT/COGIP_AUDIT_AUDIT__STRUCT.csv msgid "COGIP_AUDIT_AUDIT#caa_titre" msgstr "Titre"
Pour le fichier fr
, vous pouvez enlever les fuzzy car les propositions sont correctes, par contre il vous faudra traduire fichier en
.
5.2.9 Mise en place des modifications
Vous allez maintenant déployer vos modifications :
<devtool> deploy -s . --url http://admin:anakeen@<nomDeDomaine>/dynacase-control/ --port <port> --context dynacase
vous n'avez plus besoin de préciser les paramètres de déploiement car ils
ont été automatiquement mémorisés pour la target quickstart
lors du déploiement du chapitre précédent.
N'hésitez pas à consulter les instruction de déploiement pour plus d'explications.
Le script de déploiement choisit automatiquement le scénario upgrade car vous avez fait l'initialisation dans le chapitre précédent. L'initialisation apporte l'import des comptes (utilisateurs, groupes, rôles), or ceux-ci sont déjà importés, il est donc inutile (et coûteux en temps) de le faire à nouveau.
Vos familles sont installées sur le contexte, vous allez pouvoir consulter vos premiers formulaires.
5.2.10 Consultation des familles
Vous pouvez consulter les familles en utilisant l'interface open source de consultation par défaut OneFam
.
Cette interface est un exemple d'interface possible de consultation/création de documents.
Elle est simple à configurer et permet d'accéder à la création de rapport et de recherche.
Pour accéder à cette interface, connectez vous sur le contexte.
Vous arrivez sur l'interface suivante :

Figure 34. AppSwitcher
Utilisez le menu en haut à gauche et sélectionnez l'application Une famille
. Vous arrivez sur l'interface suivante :

Figure 35. Onefam
Les deux boutons +
vous permettent de choisir les familles présentées :
- le premier permet de choisir les familles présentées à tous les utilisateurs,
- le deuxième permet de choisir les familles qui vous sont présentées.
Cliquez sur le deuxième bouton et vous obtenez l'interface suivante :

Figure 36. Choisissez vos familles
Veuillez sélectionner la famille COGIP_AUDIT
.

Figure 37. Choisissez vos familles
Cliquez sur valider et confirmez.
Vous obtenez l'interface suivante :

Figure 38. Onefam
Pour l'instant toutes les familles sont semblables car vous n'avez pas configuré les icônes, vous pouvez les identifier en survolant l'icône.
Vous pouvez créer quelques formulaires en utilisant l'interface.
- Cliquez sur une des icônes,
- Cliquez sur
création > ...nom de la famille...
.

Figure 39. Onefam
5.2.11 Conclusion
Vous savez maintenant créer des familles, paramétrer la structure et les traduire.
Dans les autres tutoriaux de ce chapitre vous allez apprendre à les paramétrer, en paramétrer la sécurité, en modifier les interfaces.