JavaScript Preferences Wrapper for Mozilla extensions (prefutils.js)

Contents

  1. Overview
  2. Download
  3. Reference
  4. How to use it
  5. Resources
  6. Related libraries
  7. To do list
  8. Contact

Overview

prefutils.js is a wrapper around Mozilla's XPCOM preferences-related interfaces (nsIPrefBranch, etc.) for use in chrome Mozilla JavaScript code (extensions).

Features:

Download

Download prefutils.js v1.1 (4KB).

Reference

prefutils.js defines a single constructor function, named PrefsWrapper1, where 1 is wrapper's version which will change in future releases (if there are any). The function takes a single parameter aRoot, which is used as an initializer for underlying nsIPrefBranch.root. You usually want to pass something like "extensions.yourextensionname." (note the period):

var prefs = new PrefsWrapper1("extensions.yourextensionname.");

The object you have just instantiated has quite a few members. First of all, it "inherits" (via __proto__) all properties and methods of underlying nsIPrefBranch and nsIPrefBranchInternal (now the canonical name for this interface is nsIPrefBranch2). You should be able to use all of them (except nsISupports.QueryInterface(), which you probably don't need anyways).

In addition to those, it has the following members:

Member nameDescription
branch The underlying nsIPrefBranch instance, QIed to nsIPrefBranchInternal/nsIPrefBranch2.
prefSvc The reference to nsIPrefService service created for your convenience. QIed to nsIPrefBranch and nsIPrefBranchInternal.

Caveat: This is not a PrefsWrapper object for the root branch, just the plain XPCOM object.

getSubBranch(aSubpath) Returns a wrapper object for a sub-branch of current branch. For example, the following two statements are equivalent:
var prefs = new PrefsWrapper1(
	"extensions.yourextensionname.ftp.");
var prefs = new PrefsWrapper1(
	"extensions.yourextensionname.").getSubBranch("ftp.");
getUnicharPref(aPrefName)
setUnicharPref(aPrefName, aValue)
Gets/sets the unicode string stored in the preference aPrefName. Here's more information on the topic.
getLocalizedUnicharPref(aPrefName) Gets a preference, which has a localized default. Read details on MDC.
getFilePref(aPrefName)
setFilePref(aPrefName, aValue)
Gets/sets the nsILocalFile stored in the preference aPrefName. Read more about files in Mozilla.
getRelFilePref(aPrefName)
setRelFilePref(aPrefName, aValue, aRelTo)
Gets/sets the nsILocalFile relative to one of predefined directories, like the Profile folder, stored in the aPrefName preference. aRelTo parameter specifies the base directory, the list of available values is here.
clearUserPrefSafe(aPrefName) Same as nsIPrefBranch.clearUserPref, except this one doesn't throw an exception when the preference you want to clear does not exist or has no user value.

Finally, there are the following methods: getIntPrefDef, getCharPrefDef, getBoolPrefDef, getUnicharPrefDef, getFilePrefDef, getRelFilePrefDef. All of them take two parameters, the pref name and the default value, which is returned if an error (such as, the pref, that code tried to read, did not exist or had incorrect type) occurs. I don't recommend using these though, set default values for your preferences (see below) and use nsIPrefBranch methods instead.

How to use it

The suggested usage pattern is as follows.

Packaging

The prefutils.js file should be packaged in extension's content folder intact. If you make any changes to it, please change the function's name to something different from PrefsWrapper{number}, in order to avoid conflicts with other extensions.

Default preferences

Create a file containing default values for all of your prefs and package it in extension.xpi/defaults/preferences/extension.js. It should look like this:

pref("extensions.yourextension.pref1", "string value");
pref("extensions.yourextension.pref2", true);
pref("extensions.yourextension.subbranch.pref3", 0);

This will make the prefs appear in about:config even when they have no user value, and the values from that file will be returned when calling a get*Pref functions for a pref that hasn't been set. (The function would throw an exception if there was no default value specified.)

Note: the Mozilla Suite (as of version 1.7) doesn't support installing default prefs files in profile. Therefore either make your Mozilla Suite extension install in application directory or don't rely on default values.

Using

In your XUL files that have scripts that access preferences, add the following line to load prefutils.js:

<script src="chrome://yourextension/content/prefutils.js"/>

Then in your scripts create a PrefsWrapper instance as shown in example above and call whatever methods you need. If you access preferences often, it probably makes sense to have a global variable holding an instance of the wrapper — just be sure to give it a unique name in case it's in an overlay.

Example

(This assumes you defined default values for extensions.myextension.user.* preferences in defaults/preferences/myext.js)

// instantiate the wrapper
var gMyPrefs = new PrefsWrapper("extensions.myextension.");

// call nsIPrefBranch methods
var age = gMyPrefs.getIntPref("user.age"); // gets value of "extensions.myextension.user.age"
var loggedOn = gMyPrefs.getBoolPref("user.logged_on");

// you can also get sub-branches:
var branch = gMyPrefs.getSubBranch("user.");
var loggedOn2 = branch.getBoolPref("logged_on"); // == loggedOn

// call wrapper's helpers
// * for use with strings that may contain non-ASCII chars
var lastname = gMyPrefs.getUnicharPref("user.lastname");
// * nsPreferences-like variant (with built-in exception handling) -
//   in case when you don't provide a default value for the pref:
var middlename = gMyPrefs.getUnicharPrefDef("user.middlename", "default value");

Resources

Related libraries

prefarray.js is a tiny library that extends prefutils.js with support for reading and writing arrays. Thanks to David Vasilevsky for the idea and initial implementation.

To do

(help is welcome)

Contact

If you need to contact me, send an e-mail to asqueella@gmail.com. Please include “prefutils” word in subject line.

-- Nickolay Ponomarev, 24 January 2005 (last updated 03 January 2011, site only)