Les fichiers de propriétés

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 à des chaînes issues d'un fichier XUL. Néanmoins, dans un script, les entités ne sont pas analysées pour être remplacées. 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êmes, 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="strings" src="strings.properties"/>
</stringbundleset>

L'inclusion de cet élément permettra de lire les propriétés via le fichier 'strings.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("strings");
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.

À propos de l'obtention d'une chaîne d'une collection

Si vous souhaitez utiliser l'élément stringbundle au sein d'un <overlay>, merci de faire attention. Vous devrez placer votre stringbundle dans un élément <window>, d'identifiant 'main-window'. Sinon, vous ne serez pas à même de récupérer les chaînes depuis votre code JavaScript, sans comprendre pourquoi. Ainsi, le code que vous auriez écrit aurait pu être :

<overlay id="OverLayId">
    <stringbundleset id="strbundles">
        <stringbundle id="strings" src="strings.properties"/>
    </stringbundleset>
</overlay>

Il sera donc :

<overlay id="OverLayId">
    <window id="main-window">
        <stringbundleset id="strbundles">
            <stringbundle id="strings" src="strings.properties"/>
        </stringbundleset>
    </window>
</overlay>

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 occurrence 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

Avant Gecko 1.8

Bien que la plupart des langages nécessitent des caractères non-ASCII, les fichiers de propriétés doivent être écrits en n'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).

À partir de Gecko 1.8.x (et versions ultérieures)

Les fichiers .properties encodés en UTF-8 sont pris en charge. Vous pouvez donc utiliser des caractères non-ASCII sans avoir à les "échapper".

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

Interwiki