5.7.2 Les méthodes associées aux événements

5.7.2.1 addEventListener

Cette méthode permet de charger un écouteur dans le widget de document. Une fois l'événement chargé, il est valide durant toute la vie du widget document.

Un évènement n'est pas déchargé automatiquement lors du changement d'état du widget document (changement de document, d'étape, etc.).

5.7.2.1.1 Arguments

type

type de l'événement à suivre. Voir les types d'événements déclenchés par * le document, * les attributs, * les changements d'état, * les événements personnalisés

options (object)

il contient les champs suivants :

documentCheck(function javascript, facultatif)

Cette fonction permet d'indiquer pour quel type de document s'applique l'écouteur. Elle reçoit en entrée un objet document décrivant le document courant. Elle doit retourner true pour indiquer que l'écouteur' est applicable pour ce type de document. Par défaut l'écouteur s'applique pour tous les documents.

name (string, facultative)

nom de l'écouteur. Ce nom est utilisé pour identifier l'écouteur et le supprimer. Le nom peut posséder un namespace. Par défaut un nom est calculé automatiquement.

lorsque le nom correspond à un écouteur déjà enregistré sur ce widget, le nouvel écouteur remplace l'ancien, qui ne seron donc plus déclenché.

once (booléen, facultatif)

si once est à true, l'écouteur n'est appliqué qu'une seule fois et ensuite supprimé.

callback (function javascript)

cette fonction est appelée lorsque l'événement type est émis. Elle reçoit les paramètres suivants :

event

objet événement standard de jQuery,

documentObject

un objet document décrivant le document courant.

attribute (uniquement sur les événements concernant les attributs)

un objet attribut.

values (uniquement sur les événement concernant les attributs)

objet décrivant la valeur de l'attribut en cours, il contient trois propriétés :

current

valeur courante de l'attribut,

previous

valeur précédente de l'attribut,

initial

valeur de l'attribut au chargement du document

5.7.2.1.2 Retour

Le nom de l'événement est retourné.

5.7.2.1.3 Exception

Pas d'exception

5.7.2.1.4 Exemples

Ajout d'un écouteur s'appliquant uniquement sur le changement des attributs de la famille ANIMAL.

window.dcp.document.documentController("addEventListener",
    "change",
    {
        "name": "alertChange.animal",
        "documentCheck": function(documentObject) {
            return documentObject.family.name === "ANIMAL"
        }
    },
    function(event, documentObject, attribute, value) {
        alert(value.currentValue);
    }
);

Ajout d'un écouteur s'appliquant uniquement sur les messages de la famille ANIMAL et annulant les événements reçus.

window.dcp.document.documentController("addEventListener",
    "displayMessage",
    {
        "name": "preventMessages.animal",
        "documentCheck": function(documentObject) {
            return documentObject.family.name === "ANIMAL"
        }
    },
    function(event, documentObject, message) {
        event.preventDefault();
    }
);

5.7.2.2 listEventListeners

Cette méthode permet de lister les écouteurs attachés au widget. La liste retournée ne préjuge pas de si les événements sont actifs ou pas sur le document en cours.

5.7.2.2.1 Arguments

Pas d'argument

5.7.2.2.2 Retour

Tableau d'écouteurs

5.7.2.2.3 Exception

Pas d'exception

5.7.2.2.4 Exemples

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

retourne

[{
    "documentCheck" : function(document) {...},
    "eventCallback": function(event, document, data) {...},
    "eventType" : "change",
    "name" : "alertChange.animal"
},{
    "documentCheck" : function(document) {...},
    "eventCallback": function(event, document, data) {...},
    "eventType" : "displayMessage",
    "name" : "preventMessages.animal"
}]

5.7.2.3 removeEventListener

Cette méthode permet de supprimer un écouteur ou un ensemble d'écouteurs sur le widget en cours.

5.7.2.3.1 Arguments

nom (string)

nom de l'événement ou namespace des événements à supprimer.

5.7.2.3.2 Retour

Le ou les écouteur(s) supprimé(s).

5.7.2.3.3 Exception

Pas d'exception.

5.7.2.3.4 Exemple

Suppression des événements ayant le namespace animal.

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

Retourne

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