5.6 Contraintes

5.6.1 Introduction

Ces méthodes permettent de programmer des contraintes clientes. Ces contraintes sont appliquées localement et ne permettent pas une vérification de la cohérence des données sécurisée, elles sont toutefois utiles pour améliorer l'ergonomie du document.

5.6.2 Fonctionnement

Les contraintes sont appliquées sur une instance du widget document. Elles restent donc valables durant toute la vie de cette instance de widget et sont appliquées quelque soit le document représenté par cette instance.

Les contraintes sont appelées à deux moments lors de la vie du document :

• lors de la modification d'un attribut,
• lors de la sauvegarde du document.

Les contraintes enregistrées possèdent toutes un nom logique qui permet de les identifier. Ce nom logique peut être composé avec un namespace, celui-ci est séparé du nom logique par un ..

Ce nom logique est unique : si deux événements sont enregistrés avec le même nom, le plus récent écrase le plus ancien. Toutes les contraintes ayant le même namespace peuvent être désinscrites via un appel à la méthode de désinscription avec le namespace. Soit par exemple, checkAge.animal, checkPoids.animal peuvent être supprimées en appelant removeConstraint avec .animal.

5.6.2.1 Cycle de vie des contraintes

Une contrainte possède deux pré-conditions :

documentCheck

cette pré-condition est exécutée à chaque rechargement du document. Si elle retourne true, la contrainte est exécutée par le document en cours, sinon elle est mise en attente ;

attributeCheck

cette pré-condition est exécutée à chaque modification d'attribut. Si elle retourne true, la contrainte est exécutée sur l'attribut en cours, sinon elle est mise en attente.

Les pré-conditions permettent de n'appliquer les contraintes que dans leur cas d'utilisation et de réduire la charge d'exécution sur le client.

5.6.3 Les méthodes associées

5.6.3.1 addConstraint

Cette méthode permet de charger une contrainte dans le widget de document. Une fois la contrainte chargée, elle est valide durant toute la vie du widget document.

Une contrainte n'est pas déchargée automatiquement lors du changement d'état du widget document ( changement de document, d'état, etc.).

5.6.3.1.1 Arguments

options (objet)

L'argument décrit la contrainte il contient les champs suivants :

documentCheck (function javascript, facultative)

cette function permet d'indiquer pour quel type de document s'applique la contrainte. Elle doit retourner true pour indiquer que la contrainte est applicable pour ce type de document. Par défaut, la contrainte s'applique pour tous les documents.

attributeCheck(function javascript, facultative)

Cette function permet d'indiquer pour quel attribut s'applique la contrainte. Elle doit retourner true pour indiquer que la contrainte est applicable pour cet attribut. Par défaut, la contrainte s'applique à tous les attributs.

name (string, facultative)

nom de la contrainte. Ce nom est utilisé pour identifier la contrainte et la supprimer. Le nom peut posséder un namespace. Par défaut un nom est calculé automatiquement.

once (booléen, facultatif)

si once est à true, la contrainte n'est appliquée qu'une seule fois et ensuite supprimée,

constraintCheck (function javascript)

cet argument est une fonction qui est appelée lors de la modification d'un attribut du document. Si une chaine de caractère est renvoyée alors la contrainte est déclenchée, dans ce cas la sauvegarde est annulée. Il est aussi possible de retourner un tableau d'objet avec une clef "message" et une clef "index" Elle reçoit les paramètres suivants :

document

un objet document,

attribute

un objet attribut,

values

objet décrivant la valeur de l'attribut en cours. Il contient trois valeurs :

current

valeur courante de l'attribut,

previous

valeur précédente de l'attribut,

initial

valeur de l'attribut au chargement du document.

5.6.3.1.2 Retour

Le nom de la contrainte est retourné.

5.6.3.1.3 Exception

Pas d'exception

5.6.3.1.4 Exemple

Ajout d'une contrainte s'appliquant uniquement

• sur les document de la famille ANIMAL,
• sur les attributs de nom logique animal_date.

window.dcp.document.documentController(
    "addConstraint",
    {
        "name": "checkAge.animal",
        "documentCheck": function(documentObject) {
            return documentObject.family.name === "ANIMAL"
        },
        "attributeCheck": function(attribute, documentObject) {
            return attribute.id === "animal_date";
        }
    },
    function(documentObject, attribute, value) {
        if (value.current.value < "1885-05-12") {
            return "La date doit être inférieure au 12/05/1885";
        }
    }
);

Cas d'un attribut inclus dans un tableau. Dans ce cas, la contrainte est indiquée pour une rangée particulière. Cet exemple vérifie si une des valeurs est vide ou non.

Si l'index n'est pas indiqué, alors la contrainte sera affichée pour toutes les rangées.

window.dcp.document.documentController(
    "addConstraint",
    {
        "name": "checkEmpty.child",
        "documentCheck": function(documentObject) {
            return documentObject.family.name === "ANIMAL"
        },
        "attributeCheck": function(attribute, documentObject) {
            return attribute.id === "my_childs";
        }
    },
    function(documentObject, attribute, value) {
        var currentDocids=value.current;
        // The value is an array for a multiple value
        _.each(currentDocids, function (aDocid, k) {
            if (!aDocid.value) {
                // k is the row number : first row is zero
                return [{
                    message : "Ne doit pas être vide",
                    index:k
                }];
            }
        });
    }
);

5.6.3.2 listConstraints

Cette méthode permet de lister les contraintes en cours sur le widget. La liste retournée affiche toutes les contraintes actives ou pas sur le document en cours.

5.6.3.2.1 Arguments

Pas d'argument

5.6.3.2.2 Retour

Tableau de contraintes

5.6.3.2.3 Exception

Pas d'exception

5.6.3.2.4 Exemple

Liste les contraintes associées au widget.

window.dcp.document.documentController("listConstraints");

Retourne

[{
    documentCheck: function (documentObject) { return documentObject.family.name === "ANIMAL"},
    attributeCheck: function (attribute, documentObject) { return attribute.id = "animal_date"},
    constraintCheck: function (documentObject, attribute) {…}
}]

5.6.3.3 removeConstraint

Cette méthode permet de supprimer une contrainte ou un ensemble de contraintes sur le widget en cours.

5.6.3.3.1 Arguments

nom (string)

nom de la contrainte ou namespace des contraintes à supprimer.

5.6.3.3.2 Retour

La ou les contraintes supprimées.

5.6.3.3.3 Exception

Pas d'exception.

5.6.3.3.4 Exemple

Suppression de la contrainte nommée animal ou des contraintes ayant le namespace animal.

window.dcp.document.documentController("removeConstraint", ".animal");

Retour :

[{
    documentCheck: function (document) { return document.family.name === "ANIMAL"},
    attributeCheck: function (attribute, documentObject) { return attribute.id = "animal_date"},
    constraintCheck: function (document, attribute) {…}
}]