11.4 Ajout de propriétés

Attention : Ce tutoriel est ancien et n'est pas mis à jour. Bien que beaucoup d'informations soient encore valables pour les dernières versions de gecko, beaucoup sont aussi obsolètes. Il est préférable d'aller consulter cette page sur la version française de ce tutoriel sur developer.mozilla.org.

Nous allons voir comment ajouter des propriétés personnalisées aux éléments XBL.

L'interface XBL

Javascript et le DOM fournissent un moyen pour obtenir et définir les propriétés des éléments. Avec XBL, vous pouvez définir vos propres propriétés pour les éléments que vous créez. Vous pouvez aussi ajouter des méthodes qui peuvent être appelées. De cette façon, tout ce dont vous avez besoin est d'obtenir une référence à l'élément (en utilisant GetElementById ou une fonction similaire) et ainsi obtenir ou modifier ses propriétés additionnelles et appeler ses méthodes.

Il y a trois types d'items que vous pouvez ajouter.

• Les champs sont utilisés pour contenir une valeur simple.
• Les propriétés peuvent aussi être utilisées pour contenir une valeur mais elles peuvent aussi contenir du code pouvant être exécuté lorsqu'une tentative est faite pour récupérer ou modifier la valeur.
• Les méthodes sont des fonctions qui peuvent être exécutées.

Chacun des trois est défini dans un élément implementation, qui doit être un fils de l'élément de liaison binding. À l'intérieur de la balise implementation, vous définirez pour chacun d'eux un élément field, un élément property et un élément method selon ce que vous voulez. La syntaxe générale est celle-ci :

<binding id="nom-élément">
  <content>
    -- le contenu vient ici --
  </content>
  <implementation>
    <field name="nom-champ-1"/>
    <field name="nom-champ-2"/>
    <field name="nom-champ-3"/>

    <property name="nom-propriété-1"/>
    <property name="nom-propriété-2"/>
    <property name="nom-propriété-3"/>
    .
    .
    .
    <method name="nom-méthode-1/>
      -- le contenu vient ici --
    </method>
    .
    .
    .
  </implementation>
</binding>

Les champs

Chaque champ est défini en utilisant l'élément field. Souvent, les champs correspondent à un attribut placé sur l'élément comme label ou disabled, mais ils ne le devraient pas.

L'attribut name de field est utilisé pour indiquer le nom du champ. Vous pouvez utiliser le nom dans un script pour obtenir et déterminer une valeur. L'exemple ci-dessous crée un bouton qui génère et stocke un nombre aléatoire. Vous pouvez rechercher ce même nombre plusieurs fois en obtenant la propriété number du bouton. Le plus gros du travail ici est fait par les gestionnaires oncommand. Plus tard, nous verrons comment transformer cela en XBL.

XUL :

<box id="random-box" class="randomizer"/>

<button label="Générer"
           oncommand="document.getElementById('random-box').number=Math.random();"/>
<button label="Voir"
           oncommand="alert(document.getElementById('random-box').number)"/>

XBL :

<binding id="randomizer">
  <implementation>
    <field name="number"/>
  </implementation>
</binding>

Un champ number mémorisant le nombre aléatoire a été défini dans la liaison. Les deux boutons spéciaux définissent et obtiennent la valeur de ce champ. La syntaxe est très similaire pour obtenir et définir les propriétés des éléments HTML. Dans cet exemple, aucun contenu n'a été placé à l'intérieur que ce soit la boîte XUL ou sa définition dans XBL, ce qui est parfaitement valide.

Cet exemple n'est pas tout à fait correct car il n'y a pas de valeur par défaut assignée dans le champ. Pour en mettre une, ajoutez la valeur par défaut dans le contenu de la balise field. Par exemple :

<field name="number">
  25
</field>

Ici, la valeur 25 sera affectée comme valeur par défaut du champ "number". En fait, vous pourriez aussi insérer un script au sein de la balise field pour calculer la valeur par défaut. Cela pourrait être nécessaire si la valeur a besoin d'être calculée. Par exemple, le champ suivant donne une valeur par défaut égale à l'heure courante :

<field name="currentTime">
  new Date().getTime();
</field>

Les propriétés

Parfois vous voulez valider la donnée qui est assignée à une propriété. Ou bien, vous souhaitez que la valeur soit calculée dynamiquement lorsqu'on le lui demande. Par exemple, si vous souhaitez une propriété qui prenne en compte l'heure courante, vous voudrez que sa valeur soit générée au besoin. Dans ces cas là, vous avez besoin d'utiliser une balise property à la place de la balise field. Sa syntaxe est similaire mais comporte des particularités supplémentaires.

Attributs onget et onset

Vous pouvez utiliser les attributs onget et onset pour que le code soit exécuté lorsque la propriété est lue ou modifiée. Ajoutez les à l'élément property et définissez leur valeur dans un script qui, au choix, obtient ou déclare la valeur de la propriété.

Par exemple, vous pouvez assigner un script à la valeur de onget pour calculer le temps courant. Chaque fois qu'un script tente d'accéder à la valeur de la propriété, le script onget sera appelé pour fournir la valeur. Le script devra retourner la valeur qui devrait être traitée comme étant la valeur de la propriété.

Le gestionnaire onset est similaire mais est appelé chaque fois qu'un script tente d'assigner une nouvelle valeur à la propriété. Ce script devrait stocker la valeur quelque part, ou la valider. Par exemple, certaines propriétés pourraient juste être capables de stocker des nombres. Les tentatives pour assigner des caractères alphabétiques à ce genre de propriétés ne devraient pas fonctionner.

<property name="size"
          onget="return 77;"
          onset="alert('Modifié en :'+val); return val;"/>

Cette propriété retournera toujours 77 lorsqu'elle sera récupérée. Lorsqu'elle sera affectée, un message d'alerte s'affichera et indiquera la valeur à assigner à la propriété. La variable spéciale val contient cette valeur. Utilisez-la pour la valider ou la stocker. La propriété onset devrait aussi retourner la nouvelle valeur.

Ce qui suit décrit le comportement d'un cas typique :

Il y a deux éléments, l'un appelé "banana" et l'autre "orange". Chacun d'eux a une propriété spécifique appelée 'size'. Lorsque la ligne de script suivante est exécutée :

banana.size = orange.size;

1. Le script onget est appelé pour la propriété "size" de "orange". Il calcule la valeur et la retourne.
2. Le gestionnaire onset de la propriété "size" de "banana" est appelé. Ce script utilise la valeur passée dans la variable val et l'assigne à la propriété "size" de "banana" de façon quelconque.

Notez que contrairement à un champ, une propriété ne contient pas de valeur. Tenter de définir une propriété qui n'a pas de gestionnaire onset provoquera une erreur. Vous utiliserez souvent un champ séparé pour mémoriser la valeur actuelle de la propriété. Il est aussi commun que les propriétés correspondent à un attribut dans l'élément défini XBL. L'exemple suivant fait correspondre une propriété à un attribut sur un élément.

<property name="size"
          onget="return this.getAttribute('size');"
          onset="return this.setAttribute('size',val);"
/>

Chaque fois qu'un script tente d'obtenir la valeur de la propriété, elle est récupérée d'un attribut de même nom de l'élément XUL. Chaque fois qu'un script tente de définir la valeur de la propriété, elle est affectée à l'attribut 'size' de l'élément. C'est pratique parce qu'ainsi vous pouvez modifier la propriété ou l'attribut et tous les deux auront la même valeur.

Éléments getter et setter

Vous pouvez utiliser une syntaxe alternative pour les attributs onget et onset pouvant être utile pour des scripts plus longs. Vous pouvez remplacer l'attribut onget par l'élément fils nommé getter. De même, vous pouvez remplacer l'attribut onset par l'élément setter. L'exemple ci-dessous le montre :

<property name="number">
  <getter>
    return this.getAttribute('number');
  </getter>
  <setter>
    var v = parseInt(val);
    if (!isNaN(v)) return this.setAttribute('number',''+v);
    else return this.getAttribute('number');"
  </setter>
</property>

La propriété dans cet exemple ne pourra contenir que des valeurs d'entiers. Si d'autres caractères sont entrés, ils sont supprimés. S'il n'y a aucun chiffre, la valeur n'est pas modifiée. Ces opérations sont effectuées dans le code au sein de l'élément setter. La valeur réelle de la propriété est stockée dans l'attribut number.

Vous pouvez utilisez l'une ou l'autre syntaxe pour créer des gestionnaires de lecture et d'affectation.

Attribut readonly

Vous pouvez rendre un champ ou une propriété en lecture seule en ajoutant un attribut readonly à la balise field ou à la balise property, et en le déclarant à true. Toute tentative d'affecter une valeur à une propriété en lecture seule échouera.

---

La prochaine section montre comment ajouter des méthodes aux éléments définis en XBL.