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.

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

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

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.

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.


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

Add a note User Contributed Notes
July 23, 2004, 10:12 am gekacheka at yahoo dot com
Syntax:

Properties file syntax is similar to Java properties files
http://java.sun.com/j2se/1.4.2/docs/api/java/util/Properties.html#load(java.io.InputStream)

From reading code of parser nsPersistentProperties::Load:
http://lxr.mozilla.org/mozilla/source/xpcom/ds/nsPersistentProperties.cpp#146

o Properties: each property is defined by a line containing a key and value separated the first '=' or ':' on the line. Whitespace is trimmed from the start and end of both key and value.

keyname = valuetext
keyname: valuetext

o Long text values may be broken and continued on the next line by ending a line with a backslash. The whitespace at the beginning of each continuation line is ignored.

keyname: val\
uetext

o Values: Values may contain the following backslash escapes: \t for tab, \r for return, \n for newline, or may encode Unicode characters using the format \uXXXX where X is a hexadecimal digit (0-9,a-f,A-F).
o Encoding: Properties files may contain UTF-8 text (superset of US-ASCII).
o Comments: Lines that begin with '#' or '!' are ignored. Comments may have whitespace before the '#' or '!'. Blank lines are ignored.

Differences between XUL properties files and Java Properties files include:
o Default encoding: UTF-8 (XUL properties) vs. ISO8859-1 (Java Properties)
o Backslash quoting in Keys: No (XUL properties) vs. Yes (Java Properties) (so ':' and '=' cannot appear in XUL property keys)
o Backslash quoting whitespace: No (XUL properties) vs. Yes (Java Properties) (in Java properties, trailing space not trimmed from values, and can use \ before first leading space to prevent trim.)

Copyright © 1999 - 2005 XULPlanet.com