Property Files

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

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.

A property file can also include comments. A line that begins with a hash sign ('#') is treated as a comment:

# This is a comment
welcomeMessage=Hello, world!
# This is another comment
goodbyeMessage=Come back soon!

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="stringbundleset">
<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:

<stringbundleset id="stringbundleset">
<stringbundle id="strings" src="chrome://myplugin/locale/strings.properties"/>
</stringbundleset>

Like other non-displayed elements, you should declare all your stringbundles inside a stringbundleset element so that they are all kept together.

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.

Text Formatting

The next method is getFormattedString(). This method also gets a string with the given key name from the bundle. In addition, each occurrence 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.

In case you need to format a string that already contains the percentage character in it (to get something like "50% Off" returned), escape the percentage character with another percentage character, like this:

my.percentage.string = %S%% Off

Not escaping the percentage character will generate an incorrect string that strips the space character between the percentage character and the next word of the string ("50%Off").

Non-ASCII Characters, UTF-8 and escaping

Gecko 1.8.x (or later) supports property files encoded in UTF-8. You can and should write non-ASCII characters directly without escape sequences, and save the file as UTF-8 without BOM. Double-check the save options of your text editor, because many don't do this by default. See Localizing extension descriptions for more details.

In some cases, it may be useful or needed to use escape sequences to express some characters. Property files support escape sequences of the form: \uXXXX , where XXXX is a Unicode character code. For example, to put a space at the beginning or end of a string (which would normally be stripped by the properties file parser), use \u0020 .

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

« Previous Next »