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 :

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 :
  • 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 :

Paramètre de la famille référentiel

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éfaut ONEFAM 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.

Famille avec icônes

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é.
Famille avec titre

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 :

Valeur par défaut

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 :

Attribut en S

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 à :

Attribut obligatoire

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 : attributs cac_ref et cac_titre,
  • ./COGIP_AUDIT/COGIP_AUDIT_AUDIT__STRUCT.csv : attribut caa_titre,
  • ./COGIP_AUDIT/COGIP_AUDIT_FNC__STRUCT.csv : attributs caf_titre et caf_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 colonne E 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 à :

Attribut titre

Figure 46. Attribut titre

Ce qui donne après la création du document :

Document avec le calcul du titre

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 :

Document avec le calcul du titre

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 à :

Paramètre de famille

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 :

Titre : famille audit

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 à :

Définition contrainte : Structure

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 :

Définition contrainte : résultat

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 :

  1. vous créez l'audit le 12 juin pour un audit commençant le 15 juin et durant 5 jours,
  2. 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 fonction getAttributeValue est un array,
  • l'array retourné par la fonction getAttributeValue est converti en une chaîne de caractères,
  • la variable $searchDoc est une instance de la classe SearchDoc, 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 un array bi-dimensionnel. Chaque entrée de cet array est un array 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. Cet initid 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, le name 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.
Aide à la saisie : struct

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

Aide à la saisie : 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 :

Aide à la saisie : struct

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 en S 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.

5.3.12 Voir aussi

×