XUL Tutorial - 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. For example, you may 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.

Here, the property file contains two properties. These would be read by a script and displayed to the user. You could write the code to read properties yourself, however Mozilla provides a script which contains some functions which handle this for you. This script 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. The set of properties is often called a string bundle.

To use this script, you just include the file 'chrome://global/content/strres.js' from with-in your XUL file. This is shown below.

<script src="chrome://global/content/strres.js"/>

This script provides a number of functions, one of which is srGetStrBundle. This function is used to load a properties file and build a string bundle from it. This string bundle can then be used to look up the values of various properties. Other functions can be used to get other locale information. Look at the file strres.js for more information.

The srGetStrBundle function takes one parameter, the URL of the properties file. It returns a bundle object. The bundle object has a function GetStringFromName which can be used to look up individual properties. The following is an example:

var bundle = srGetStrBundle("chrome://findfile/content/findfile.properties");
var nofilesfound = bundle.GetStringFromName("notFoundAlert");

alert(nofilesfound);

The properties file is first loaded and a string bundle created and stored in the bundle variable. The property 'notFoundAlert' is looked up and returned by the GetStringFromName function. This result can be used by the script to display an alert box.

(Next) Next, we'll see how to use overlays to handle common content.