XUL Tutorial:Property Files

From MDC

In a script, entities cannot be used. Property files are used instead.

Contents 1 Properties 2 Stringbundles 2.1 Getting a String from the Bundle 2.2 Text Formatting 3 Escape non-ASCII Characters

[edit] Properties

DTD files are suitable when you have text in a XUL file. However, a script does not get parsed for entities. In addition, you may wish to display a message which is generated from a script, if, for example, you do not know the exact text to be displayed. For this purpose, property files can be used.

A property file contains a set of strings . You will find property files alongside the DTD files with a .properties extension. Properties in the file are declared with the syntax name=value. An example is shown below:

notFoundAlert=No files were found matching the criteria.
deleteAlert=Click OK to have all your files deleted.
resultMessage=%2$S files found in the %1$S directory.

Here, the property file contains three properties. These would be read by a script and displayed to the user.

[edit] Stringbundles

You could write the code to read properties yourself, however XUL provides the stringbundle element which does this for you. The element has a number of functions which can be used to get strings from the property file and get other locale information. This element reads in the contents of a property file and builds a list of properties for you. You can then look up a particular property by name.

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

Including this element will read the properties from the file 'strings.properties' in the same directory as the XUL file. Use a chrome URL to read a file from the locale. Like other non-displayed elements, you should declare all your stringbundles inside a stringbundleset element so that they are all kept together.

[edit] Getting a String from the Bundle

This stringbundle element has a number of properties. The first is getString which can be used in a script to read a string from the bundle.

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

alert(nofilesfound);

• This example first gets a reference to the bundle using its id
• Then, it looks up the string 'notFoundAlert' in the property file. The function getString() returns the value of the string or null if the string does not exist.
• Finally, the string is displayed in an alert box.

[edit] Text Formatting

The next method is getFormattedString(). This method also gets a string with the given key name from the bundle. In addition, each occurance of formatting code (e.g. %S) is replaced by each successive element in the supplied array.

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

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

alert(result);

This example will display following message in an alert box.

10 files found in the /usr/local/document directory.

You will notice the formatting codes %1$S and %2$S is used, and replaced different order in the array. Formatting code %n$S is specify the position of corresponding parameter directly. Although the word order is not the same in all the languages, by using getFormattedString() the specification of the order can be put out the property files.

[edit] Escape non-ASCII Characters

(This may no longer be true: on Localizing extension descriptions, it says to "make sure to use UTF-8 encoding (without BOM) to ensure foreign characters display correctly." While escape sequences will still work, using UTF-8 encoded text should also work. Some idea of when this was introduced would be helpful.)

Although many languages need non-ASCII characters, property files should be written using only ASCII characters. However, property files support other characters using escape sequences of the form: \uXXXX where XXXX is a character code. Therefore, if your property files contain non-ASCII characters, you should convert these to 'escaped-unicode' format. To do this, you can use native2ascii command line utility bundled with Sun's Java Development Kit (JDK).

In the next section, we will look at XBL, which can be used to define the behavior of an element.