10.6 Les fichiers de propriétés

Écrit par Neil Deakin , mise à jour par les contributeurs à MDC .
Traduit par Sylvain Costard (21/07/2004), mise à jour par Alain B. (04/04/2007) .
Page originale : http://developer.mozilla.org/en/docs/XUL_Tutorial/Property_Files

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.

Dans un script, les entités ne peuvent être utilisées. On utilise alors plutôt les fichiers de propriétés.

Propriétés

Les fichiers DTD sont adaptés à du texte dans un fichier XUL. Néanmoins, dans un script, les entités ne sont pas analysées pour être remplacer. De plus, vous pourriez souhaiter afficher un message généré par un script, sans par exemple connaître à l'avance son contenu. Les fichiers de propriétés peuvent être utilisés dans ce but.

Un fichier de propriétés contient une suite de chaînes de caractères. Vous trouverez les fichiers de propriétés aux côtés des fichiers DTD avec l'extension .properties. Les propriétés dans un de ces fichiers sont déclarées selon une structure nom=valeur. Un exemple est décrit ci-dessous :

notFoundAlert=Aucun fichier trouvé correspondant aux critères.
deleteAlert=Cliquez sur OK pour effacer tous vos fichiers.
resultMessage=%2$S fichiers trouvés dans le répertoire %1$S.

Ici, le fichier de propriétés contient deux propriétés. Elles pourront être lues par un script et affichées.

Stringbundles

Vous pouvez écrire le code de lecture des propriétés vous même, néanmoins XUL fournit l'élément stringbundle qui le fait pour vous. Cet élément dispose de plusieurs fonctions pouvant être utilisées pour récupérer les chaînes de caractères des fichiers de propriétés et d'autres informations de localisation. Cet élément lit le contenu des fichiers de propriétés et construit une liste de ces propriétés pour vous. Vous pouvez donc ensuite y accéder par leur nom.

<stringbundleset id="strbundles">
<stringbundle id="chaines" src="chaines.properties"/>
</stringbundleset>

L'inclusion de cet élément permettra de lire les propriétés via le fichier chaines.properties dans le même répertoire que le fichier XUL. Utilisez une URL chrome pour lire un fichier de localisation. Comme pour d'autres éléments non affichables, vous devriez déclarer tous les stringbundles à l'intérieur d'un élément stringbundleset pour les regrouper.

Obtention d'une chaîne d'une collection

L'élément stringbundle a plusieurs propriétés. La première est getString pouvant être utilisée dans un script pour lire une chaîne de caractères de la collection.

var strbundle=document.getElementById("chaines");
var nofilesfound=strbundle.getString("notFoundAlert");

alert(nofilesfound);

Cet exemple récupère tout d'abord une référence sur la collection en utilisant son id.
Puis il recherche la chaîne de caractères notFoundAlert dans le fichier de propriétés. La fonction getString() retourne la valeur de la chaîne ou null si la chaîne n'existe pas.
Enfin, la chaîne de caractères est affichée dans une boîte d'alerte.

Formatage de texte

La méthode suivante est getFormattedString(). Elle permet également d'obtenir avec une clef donnée une chaîne de la collection. Mais en plus, chaque occurence de code de formatage (par ex. %S) est remplacée par chaque élément successif dans le tableau transmis.

var dir = "/usr/local/document";
var count = 10;

var strbundle = document.getElementById("strings");
var result = strbundle.getFormattedString("resultMessage", [ dir, count ]);

alert(result);

Cet exemple affichera le message suivant dans une boîte d'alerte.

10 fichiers trouvés dans le répertoire /usr/local/document.

Vous noterez que les codes de formatage %1$S et %2$S sont utilisés, et sont remplacés par les différents membres dans le tableau. Un code de formatage %n$S spécifie directement la position du paramètre correspondant. Bien que l'ordre des mots soit différent dans tous les langages, l'utilisation de getFormattedString() permet de préciser l'ordre dans les fichiers de propriétés.

Échappement de caractères non-ASCII

Bien que la plupart des langages nécessitent des caractères non-ASCII, les fichiers de propriétés doivent être écrits en utilisant que des caractères ASCII. Cependant, les fichiers de propriétés supportent d'autres caractères grâce à des séquences échappées de la forme : \uXXXX où XXXX est le code du caractère. Ainsi, si votre fichier de propriété contient des caractères non-ASCII, vous devrez le convertir au format 'échappement-unicode'. Pour faire cela, vous pouvez utiliser l'utilitaire en ligne de commande native2ascii fourni avec le kit de développement Java de Sun (JDK).

Dans la prochaine section, nous découvrirons XBL qui peut être utilisé pour définir le comportement d'un élément.