5.3 Paramétrage
Dans ce chapitre, vous allez paramétrer les familles que vous avez créées dans le chapitre précédent, "Mise en place des structures".
5.3.1 Objectifs
- Mise en place des propriétés des familles,
- Mise en place du code métier :
- Valeurs par défaut,
- Aides à la saisie,
- Attributs calculés,
- Contraintes.
5.3.2 Cadre
Lors de la phase de spécification, les éléments suivants ont été identifiés. Votre application nécessite les comportements suivants :
- Référentiel qualité :
- L'attribut référence est obligatoire,
- Le titre d'un référentiel est sa référence.
- Chapitre de référentiel :
- L'attribut titre du chapitre est obligatoire,
- Le titre est composé du titre du référentiel associé et du titre du chapitre.
- Audit :
- L'attribut titre est obligatoire,
- Le titre est composé du titre de l'audit et d'un préfixe,
- La date de début est postérieure à la date du jour,
- La date de fin de l'audit est calculée automatiquement en fonction de la date de début d'audit et de sa durée,
- La liste des fiches de non-conformité, calculée automatiquement, n'est pas modifiable.
- Fiche de non-conformité :
- Le titre est composé de l'attribut titre de la fiche et du titre de l'audit associé,
- Le rédacteur d'une fiche est la personne l'ayant créée,
- Les référentiels accessibles sont ceux sélectionnés dans l'audit associé,
- Les chapitres accessibles sont ceux du référentiel de la ligne en cours,
- L'attribut titre est obligatoire,
- L'attribut lien vers l'audit est obligatoire.
5.3.3 Théorie et fichiers mis en œuvre
Le paramétrage des familles de Dynacase comprend tout ce qui est lié à la personnalisation du fonctionnement des familles. Les différents éléments paramétrables sont :
- les propriétés des familles, qui permettent de spécifier :
- des éléments de présentation (titre, icône),
- la sécurité (profil de famille, profil de document),
- valeur par défaut,
- paramètre de famille,
- le cycle de vie associé,
- etc.
- l'ajout de code métier à la famille; plusieurs concepts sont mis en œuvre :
Il vous est rappelé qu'à chaque modification de votre paquet, vous devez reconstruire celui-ci et le déployer pour voir les modifications s'appliquer sur votre environnement d'exécution (VM). De plus :
- si vous avez modifié la structure (ajout, suppression d'attribut), il est conseillé de :
- rafraîchir les stubs,
- rafraîchir les traductions
- si vous avez ajouté/enlevé une clef de traduction dans le code associé aux familles (fonctions
_
,___
), il est conseillé de rafraîchir les traductions.
Les annexes contiennent un chapitre développement rapide qui résume quelques techniques permettant d'accélérer le développement en évitant de déployer à chaque modification.
5.3.4 Propriétés des familles
Commencez par les propriétés des familles.
Une famille peut contenir un certain nombre de propriétés, elles sont décrites dans la documentation.
Ouvrez le fichier ./COGIP_AUDIT/COGIP_AUDIT_REFERENTIEL__PARAM.csv
, celui-ci contient les lignes suivantes :

Figure 40. Paramètre de la famille référentiel
Deux paramètres ont été remplis par le developper tool :
-
ICON
: désigne une image qui est utilisée comme icône pour cette famille dans les interfaces standards, -
DFLDID
: cette propriété est utilisée par l'interface par défautONEFAM
pour identifier les familles à afficher.
5.3.4.1 Icône
L'image de l’icône doit être ajoutée dans le répertoire Images
à la racine du contexte.
Vous devez donc créer dans vos sources un répertoire Images
et ajouter une image.
Vous obtenez la structure de fichiers suivantes :
├ Images ├── cogip_audit_audit.png ├── cogip_audit_base.png ├── cogip_audit_chapitre.png ├── cogip_audit_fnc.png ├── COGIP_AUDIT.png └── cogip_audit_referentiel.png
Vous pouvez retrouver l'ensemble des images de l'application sur github.

Figure 41. Famille avec icônes
5.3.4.2 Titre de famille
Le titre de la famille se paramètre via les traductions.
Ouvrez le fichier locale/fr/LC_MESSAGES/src/COGIP_AUDIT_AUDIT.po
et modifiez le bloc suivant :
msgid "COGIP_AUDIT_AUDIT#title" msgstr ""
en
msgid "COGIP_AUDIT_AUDIT#title" msgstr "Audit"
Complétez les différents fichiers .po
avec les traductions suivantes :
-
COGIP_AUDIT_BASE#title
: Base, -
COGIP_AUDIT_CHAPITRE#title
: Chapitre, -
COGIP_AUDIT_FNC#title
: Fiche de non-conformité, -
COGIP_AUDIT_REFERENTIEL#title
: Référentiel qualité.

Figure 42. Famille avec titre
Attention si jamais votre bloc de traduction porte la mention fuzzy
,
cette mention doit être supprimée pour que la traduction soit prise en compte.
Vous pouvez retrouver les po complétés sur github.
5.3.4.3 Valeur par défaut
Dans les fiches de non-conformité, le rédacteur est le créateur de la fiche.
Pour obtenir ce comportement, vous allez utiliser la notion de valeur par défaut.
La valeur par défaut est donnée par une méthode de la classe associée à famille. Cette méthode est appelée lors de la création d'un document et retourne une valeur qui complète la valeur d'un attribut.
Pour indiquer la valeur par défaut, ouvrez le fichier ./COGIP_AUDIT/COGIP_AUDIT_FNC__PARAM.csv
et ajoutez une ligne juste avant le END
avec pour les colonnes les valeurs :
-
A
:DEFAULT
, -
B
: le nom de l'attribut,caf_redacteur
dans votre cas, -
C
: le nom de la fonction fournissant la valeur par défaut, ici::getUserId()
.
Ce qui donne :

Figure 43. Valeur par défaut
Vous pouvez retrouver le fichier complété dans les sources.
De plus, cette valeur n'étant pas modifiable par les utilisateurs, vous allez modifier la visibilité par défaut de l'attribut correspondant pour le rendre non modifiable.
Ouvrez le fichier ./COGIP_AUDIT/COGIP_AUDIT_FNC__STRUCT.csv
et modifiez la ligne correspondant à l'attribut caf_redacteur
pour mettre S
dans la colonne I
. Cela indique que l'attribut est statique et donc non modifiable :

Figure 44. Attribut en S
Vous pouvez retrouver le fichier complété dans les sources.
5.3.5 Attribut obligatoire
Votre spécification indique que certains attributs sont obligatoires.
Pour indiquer qu'un attribut est obligatoire, sa définition est modifiée dans le fichier __STRUCT.csv
.
Ouvrez le fichier ./COGIP_AUDIT/COGIP_AUDIT_REFERENTIEL__STRUCT.csv
et modifiez la colonne J
sur la ligne de l'attribut car_titre
en y ajoutant la lettre Y
. Le fichier doit être similaire à :

Figure 45. Attribut obligatoire
Une fois le fichier importé, le formulaire en édition indique que l'attribut est obligatoire (passage en gras du label). L'enregistrement n'est pas permis sans mettre une valeur dans cet attribut.
Complétez ensuite les autres familles :
-
./COGIP_AUDIT/COGIP_AUDIT_CHAPITRE__STRUCT.csv
: attributscac_ref
etcac_titre
, -
./COGIP_AUDIT/COGIP_AUDIT_AUDIT__STRUCT.csv
: attributcaa_titre
, -
./COGIP_AUDIT/COGIP_AUDIT_FNC__STRUCT.csv
: attributscaf_titre
etcaf_audit
.
Vous pouvez retrouver les familles complétées dans les sources.
5.3.6 Calcul des titres des documents
Il existe deux moyens de spécifier les règles de calcul de titre d'un document :
- soit en modifiant la colonne
E
d'un fichier__STRUCT.csv
, cette colonne indique les attributs utilisés dans la composition du titre. Ce moyen est simple mais a plusieurs limitations :- vous ne pouvez pas définir l'ordre de composition (les valeurs sont concaténées selon l'ordre des attributs),
- seuls les attributs textuels et numériques sont utilisables.
- soit en modifiant la méthode
getCustomTitle
dans ce cas vous composez directement le titre. La colonneE
n'est plus utilisée.
5.3.6.1 Composition du titre par paramétrage de la structure
Ouvrez le fichier ./COGIP_AUDIT/COGIP_AUDIT_REFERENTIEL__STRUCT.csv
et modifiez le pour qu'il soit similaire à :

Figure 46. Attribut titre
Ce qui donne après la création du document :

Figure 47. Document avec le calcul du titre
Vous pouvez retrouver le fichier complété dans les sources.
5.3.6.2 Composition du titre en utilisant getCustomTitle
Pour les autres familles, vous ne pouvez pas utiliser la même méthode car soit le titre contient un lien vers un attribut, soit il est composé avec des éléments qui ne sont pas directement dans le document.
Ouvrez le fichier ./COGIP_AUDIT/COGIP_AUDIT_CHAPITRE__CLASS.php
et surchargez la méthode getCustomTitle
:
/** * Compute the title of the chapter family * * @return string */ public function getCustomTitle() { //Get the attr cac_titre value $title = $this->getAttributeValue(MyAttributes::cac_titre); //Get the title of the referenced referentiel $chapterTitle = $this->getTitle($this->getAttributeValue(MyAttributes::cac_ref)); // Compose the title return sprintf("%s : %s", $chapterTitle, $title); }
Ce qui donne après la création du document :

Figure 48. Document avec le calcul du titre
Vous pouvez retrouver le fichier complété dans les sources.
Ouvrez le fichier ./COGIP_AUDIT/COGIP_AUDIT_FNC__CLASS.php
et surchargez la méthode getCustomTitle
:
/** * Compute the title of the FNC family * * @return string */ public function getCustomTitle() { //Get the attr caf_titre value $title = $this->getAttributeValue(MyAttributes::caf_titre); //Get the title of the referenced audit $chapterTitle = $this->getTitle($this->getAttributeValue(MyAttributes::caf_audit)); // Compose the title return sprintf("%s : %s", $chapterTitle, $title); }
Vous pouvez retrouver le fichier complété dans les sources.
5.3.6.3 Paramètre de famille
Vous allez maintenant construire le titre pour la famille audit. Ce titre est composé de deux parties :
- un préfixe que sera stocké dans un paramètre de famille,
- le contenu d'un attribut de la famille
caa_titre
.
Vous allez ajouter un paramètre à la famille audit.
Ouvrez le fichier ./COGIP_AUDIT/COGIP_AUDIT_AUDIT__PARAM.csv
et modifiez le pour qu'il soit similaire à :

Figure 49. Paramètre de famille
Les paramètres de familles se définissent de la même manière que les attributs (voir la documentation d'importation).
À la prochaine importation, le paramètre sera associé à cette famille. Sa valeur est modifiable dans les interfaces d'administration sans nouveau déploiement des sources.
Vous pouvez retrouver les sources complétées dans les sources.
5.3.6.4 Composition du titre avec un paramètre de famille
Ouvrez le fichier ./COGIP_AUDIT/COGIP_AUDIT_AUDIT__CLASS.php
et surchargez la méthode getCustomTitle
:
/** * Compute the title of the audit family * * @return string */ public function getCustomTitle() { //Get the attr cac_titre value $title = $this->getAttributeValue(MyAttributes::caa_titre); //Get the prefix $prefixe = $this->getFamilyParameterValue("caa_p_title_prefix"); // Compose the title return sprintf("%s_%s", $prefixe, $title); }
Ce qui donne, après déploiement :

Figure 50. Titre : famille audit
Bravo ! Vous avez mis en place le calcul des titres des documents.
5.3.7 Mise en place des contraintes
Vous allez maintenant paramétrer la contrainte nécessaire à votre projet.
Une contrainte permet de vérifier qu'une condition est valide lors de l'enregistrement d'un document.
Ouvrez le fichier ./COGIP_AUDIT/COGIP_AUDIT_AUDIT__CLASS.php
et veuillez ajouter la fonction suivante :
/** * Check if the date is inferior to today * * @param string $date iso date * @return string|null */ public function checkBeginningDate($date) { if (!empty($date) && $date <= date("c")) { return _("coa:The date must be after today"); } return null; }
Quelques remarques sur la fonction ci-dessus :
- les méthodes associées à des contraintes commencent, par convention, par
check
(bonne pratique), - la fonction
_
permet d'indiquer que la chaîne va être traduite.
Pensez à relancer l'extraction des traductions et à traduire la chaîne dans le fichier .po
de l'application (COGIP_AUDIT_fr.po
).
Vous pouvez retrouver la contrainte complétée dans les sources.
Ouvrez le fichier ./COGIP_AUDIT/COGIP_AUDIT_AUDIT__STRUCT.csv
et modifiez la colonne O
de la ligne de l'attribut caa_date_debut
pour y ajouter la référence à la fonction définie ci-dessus.
Vous devez obtenir une ligne similaire à :

Figure 51. Définition contrainte : Structure
La cellule contient :
- le nom de la fonction
::checkBeginningDate
, - le nom de l'attribut dont la valeur est passée en paramètre à la fonction
caa_date_debut
.
Une fois le module déployé, le formulaire possède une nouvelle fonctionnalité, qui s'affiche de cette manière :

Figure 52. Définition contrainte : résultat
Vous pouvez retrouver la contrainte complétée dans les sources.
Les contraintes permettent aussi de suggérer des valeurs. Si vous souhaitez implémenter ce comportement, veuillez consulter la documentation.
Pour l'instant cette contrainte est très limitante, en effet elle s’exécute à chaque sauvegarde du document. Donc :
- vous créez l'audit le 12 juin pour un audit commençant le 15 juin et durant 5 jours,
- vous le modifiez le 16 juin la contrainte vous indique que la date de début est dépassée et vous empêche de sauvegarder.
Vous verrez dans le chapitre sur les cycles de vie différents moyens d'améliorer cette contrainte.
5.3.8 Configuration des aides à la saisie
Vous allez maintenant configurer une aide à la saisie.
La spécification indique que dans une fiche de non-conformité les référentiels accessibles sont ceux référencés par l'audit associé à la fiche.
Une aide à la saisie est dans un fichier autonome car elle peut-être utilisée au sein de plusieurs famille différentes.
5.3.8.1 Fonction
Ajoutez un fichier helper_audit.php
dans le répertoire EXTERNALS
et ajoutez dans celui-ci la fonction selectReferentiel
comme ci-dessous :
<?php function selectReferentiel($caf_audit, $userInput = "") { $return = array(); // Get the audit doc with the id $audit = new_Doc("", $caf_audit, true); if (!$audit->isAlive()) { return _("coa:You need to select an audit before"); } // Get the referentiel doc $auditReferentiel = $audit->getAttributeValue(\Dcp\AttributeIdentifiers\COGIP_AUDIT_AUDIT::caa_ref); if (is_array($auditReferentiel)) { $auditReferentiel = implode(",", $auditReferentiel); } // Search the associated referentiel $searchDoc = new \SearchDoc("", "COGIP_AUDIT_REFERENTIEL"); $searchDoc->setObjectReturn(); /* @var $auditReferentiel \COGIP\COGIP_AUDIT_AUDIT */ //Add a filter to select only the referentiel in the audit $searchDoc->addFilter("id in (%s)", $auditReferentiel); //Add a filter on the title that take the userInput if (!empty($userInput)) { $searchDoc->addFilter("title ~* '%s'", preg_quote($userInput)); } $htmlUserInput = htmlentities($userInput); foreach($searchDoc->getDocumentList() as $currentRef) { /* @var $currentRef \COGIP\COGIP_AUDIT_AUDIT */ $enhancedTitle = $currentRef->getHTMLTitle(); if (!empty($userInput)) { //Enhance the title to emphasize the userInput $enhancedTitle = str_replace($userInput, "<strong>$htmlUserInput</strong>", $currentRef->getHTMLTitle()); } //Set the return value $return[] = array( $enhancedTitle, $currentRef->getPropertyValue("initid"), $currentRef->getTitle() ); } return $return; }
Cette fonction permet de sélectionner uniquement les référentiels cités dans l'audit associé à la fiche de non-conformité. Vous pouvez remarquer les points suivants :
- si jamais le document audit associé à la FNC n'est pas vivant (alive) (soit inexistant, soit supprimé) alors un message est envoyé à l'utilisateur lui indiquant qu'il doit sélectionner un audit,
- l'attribut
caa_ref
est multiple, donc le retour de la fonctiongetAttributeValue
est unarray
, - l'
array
retourné par la fonctiongetAttributeValue
est converti en une chaîne de caractères, - la variable
$searchDoc
est une instance de la classeSearchDoc
, cette classe permet de chercher des documents dans la base documentaire de Dynacase. Elle génère le SQL nécessaire à la recherche et retourne des instances de Document ou les valeurs contenues dans le document, - la fonction addFilter permet d'ajouter un critère de recherche pour préciser la recherche,
- la fonction getDocumentList permet d'avoir la liste des documents trouvés,
- la variable
$return
contient unarray
bi-dimensionnel. Chaque entrée de cetarray
est unarray
décrivant une proposition, constituée de :- le premier élément est le nom de l'élément affiché dans la liste de suggestion, ce nom est en HTML,
- les éléments suivants sont les valeurs pour les attributs spécifiés dans le fichier
__STRUCT
.
id
et initid
: dans l'aide à la saisie la propriété renvoyée est l'initid du document.
Tout document possède plusieurs moyens d'être identifié :
-
id
: identifiant unique qui permet de trouver le document au sein d'un contexte, -
initid
: identifiant d'une lignée documentaire. Une lignée documentaire est l'ensemble des révisions (passées et applicable) d'un document, et l'initid
est l'id
de la première révision du document. Cetinitid
doit être utilisé pour référencer le document dans les formulaires pour permettre la recherche. -
name
: identifiant fonctionnel d'un document. Alors que l'id
et l'initid
sont générés par la base de donnée, lename
est défini par le développeur. Ainsi, il est constant entre les différentes installations, alors que l'id
et l'initid
ne le sont pas.
Vous pouvez retrouver les aides à la saisie complétées dans les sources.
5.3.8.2 Paramétrage
Vous allez maintenant référencer cette aide à la saisie dans la famille.
Ouvrez le fichier ./COGIP_AUDIT/COGIP_AUDIT_FNC__STRUCT.csv
et ajoutez dans les colonnes L
et M
les valeurs suivantes :
-
L
:helper_audit.php
, cette colonne contient la référence vers le fichier contenant l'aide à la saisie, -
M
:selectReferentiel(caf_audit,CT):caf_ecart_ref,CT[caf_ecart_ref]
cette colonne contient le paramétrage de l'aide à la saisie, elle peut-être découpée en trois éléments :- le nom de la fonction
selectReferentiel
, - la liste des éléments entrants :
caf_audit,CT
, ces éléments sont passés à la fonction en valeur entrantes, vous trouverez la liste des éléments acceptés dans la documentation, - la liste des éléments cibles de l'aide à la saisie, cette liste décrit les éléments à valuer avec la suggestion sélectionnée par l'utilisateur.
- le nom de la fonction

Figure 53. Aide à la saisie : struct
Vous remarquez qu'il y a un décalage d'une valeur entre
le nombre de retour de la fonction d'aide à la saisie (3 éléments par valeur possible)
et la définition de l'aide à la saisie (2 éléments uniquement).
En effet, le premier élément du retour de l'aide à la saisie est utilisé
pour construire la liste de suggestion présentée à l'utilisateur.
Vous pouvez retrouver le paramétrage complété dans les sources.
5.3.8.3 Résultat

Figure 54. Aide à la saisie : résultat
5.3.8.4 Exemple
Ci-dessous, un autre exemple d'aide à la saisie. Il concerne toujours les Fiche de non-conformité, les chapitres présentés doivent être ceux du référentiels en cours.
La fonction suivante est à ajouter dans helper_audit.php
:
function selectChapter($caf_referentiel, $userInput = "") { if (empty($caf_referentiel)) { return _("coa:You need to select a referentiel"); } $return = array(); // Search the associated referentiel $searchDoc = new \SearchDoc("", "COGIP_AUDIT_CHAPITRE"); $searchDoc->setObjectReturn(); /* @var $auditReferentiel \COGIP\COGIP_AUDIT_CHAPITRE */ //Add a filter to select only the referentiel in the audit $searchDoc->addFilter("cac_ref = '%s'", $caf_referentiel); //Add a filter on the title that take the userInput if (!empty($userInput)) { $searchDoc->addFilter("title ~* '%s'", preg_quote($userInput)); } $htmlUserInput = htmlentities($userInput); foreach ($searchDoc->getDocumentList() as $currentRef) { /* @var $currentRef \COGIP\COGIP_AUDIT_CHAPITRE */ $enhancedTitle = $currentRef->getHTMLTitle(); if (!empty($userInput)) { //Enhance the title to emphasize the userInput $enhancedTitle = str_replace($userInput, "<strong>$htmlUserInput</strong>", $currentRef->getHTMLTitle()); } //Set the return value $return[] = array( $enhancedTitle, $currentRef->getPropertyValue("initid"), $currentRef->getTitle() ); } return $return; }
Vous pouvez retrouver les aides à la saisie complétées dans les sources.
Et complétez le fichier ./COGIP_AUDIT/COGIP_AUDIT_FNC__STRUCT.csv
:

Figure 55. Aide à la saisie : struct
Vous pouvez retrouver les sources complétées dans les sources.
5.3.9 Attributs calculés
Pour finir ce chapitre, vous allez mettre en place un attribut calculé. La date de fin de l'audit doit être calculée en fonction de sa date de début et de sa durée.
Ouvrez le fichier ./COGIP_AUDIT/COGIP_AUDIT_AUDIT__CLASS.php
et ajoutez la fonction ci-dessous :
/** * Compute end date * * @param string $dateDebut iso * @param int $duree nb days * @return string */ public function computeDateFin($dateDebut, $duree) { if (!empty($dateDebut) && !empty($duree)) { $date = new \DateTime($dateDebut); $interval = \DateInterval::createFromDateString(sprintf('%d day', $duree)); $date->add($interval); return $date->format("o-m-d"); } return " "; }
Le retour de l'attribut calculé doit être un espace pour indiquer que le contenu de l'attribut doit-être vidé. Si jamais la fonction retourne une chaîne vide ou rien alors le contenu de l'attribut est laissé tel quel.
Vous pouvez retrouver le fichier PHP complété dans les sources.
Ensuite, vous devez enregistrer la fonction dans le fichier __STRUCT.csv
,
ouvrez ./COGIP_AUDIT/COGIP_AUDIT_AUDIT__STRUCT.csv
et modifiez pour l'attribut caa_date_fin
les colonnes :
-
I
: pour rester cohérent il faut que la visibilité soit enS
car l'utilisateur ne doit pas pouvoir modifier la date de fin, -
M
:::computeDateFin(caa_date_debut,caa_duree)
. Cette cellule porte la référence vers la fonction et ces paramètres d'entrée. Le format de cet élément est explicité dans la documentation.
Vous pouvez retrouver le fichier CSV complété dans les sources.
Bravo ! Vous avez terminé la partie pratique de ce chapitre.
5.3.10 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 pouvez ensuite créer quelques formulaires pour voir les modifications que vous avez mises en place.
5.3.11 Conclusion
Ce chapitre de paramétrage vous a permis de rendre votre formulaire plus interactif et d'y intégrer plus de logique métier.
Dans les chapitres suivants, vous allez continuer à améliorer celui-ci notamment
- en ajoutant des règles métier grâce aux hooks
- et en améliorant l'interface générée.