Mobile/Fennec/Extensions/Options

Note: This actually still works with native Fennec!

Fennec uses special <setting> XUL tags to create it's list of options (preferences). Add-ons must use the same tags. The options are merged into the Fennec Add-on Manager, not displayed as a popup dialog. Of course, add-ons can support more than one application, so we need to make sure that the options XUL for Fennec can coexist with the options XUL for other applications. Let's take a look at how this all works:

Install Manifest

Add-ons use install.rdf to identify the XUL used for displaying the options. This is optional.

<em:optionsURL>chrome://myaddon/content/options.xul</em:optionsURL>

This is needed for any add-on that wants to use an options dialog.

Chrome Manifest

Add-ons use the chrome manifest to selectively override XUL, and other resources, between different applications using the application flags

override chrome://myaddon/content/options.xul chrome://myaddon/content/fennec-options.xul application={a23983c0-fd0e-11dc-95ff-0800200c9a66}

This will tell Mozilla to use fennec-options.xul anytime the options.xul resource is requested.

Setting Types

The are several types of <setting> types: Boolean (true/false), Boolean (mapped to numbers), String (plain/password/numeric), Buttons and Lists. The boolean and string settings are tied to actual preferences, while the button and list settings are designed more for actions. The button and list settings can tied to preferences via JavaScript.

Some examples:

// Simple Boolean examples

<setting pref="signon.rememberSignons" title="Remember Passwords" type="bool"/>

<setting pref="javascript.enabled" type="bool" title="Enable JavaScript">
  JavaScript is the glue of the Web
</setting>

// Boolean examples - mapped to integer values

<setting pref="permissions.default.image" title="Show Images" type="boolint" on="1" off="2"/>

<setting pref="network.cookie.cookieBehavior" title="Allow Cookies" type="boolint" on="0" off="2">
  Cookies are delicious
</setting>

// Button example - not tied to a preference, but attached to a command

<setting title="Clear Private Data" type="control">
  Clears history and other stuff
  <button id="prefs-clear-data" label="Clear" command="cmd_sanitize"/>
</setting>

// String examples

<setting pref="extensions.myaddon.username" type="string" title="Username"/>

<setting pref="extensions.myaddon.password" type="string" title="Password" inputtype="password"/>

// List examples = not tied to a preference, but attached to an event handler

<setting title="Favorite Color" type="control">
  <menulist oncommand="MyAddon.SetColor(this.value);">
    <menupopup>
      <menuitem value="red" label="Red"/>
      <menuitem value="blue" label="Blue"/>
      <menuitem value="green" label="Green"/>
    </menupopup>
  </menulist>
</setting>

Options XUL

The XUL allowed for the Fennec options system is limited to <setting> tags. Here is an example of a Fennec options dialog:

<?xml version="1.0"?>

<!DOCTYPE mydialog SYSTEM "chrome://myextension/locale/mydialog.dtd">

<vbox xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
  <setting pref="extensions.myaddon.debugging" type="boolint" on="1" off="2" title="Enable debugging"/>
  <setting pref="extensions.myaddon.profiling" type="bool" title="Enable profiling">
    Profiling can affect the performance of the application
  </setting>
  <setting pref="extensions.myaddon.logging" type="bool" title="Save logs"/>
  <setting pref="extensions.myaddon.logging.path" type="string" title="Log folder"/>
  <setting type="button" title="Clear logs">
    <button label="Clear" oncommand="MyAddon.clearLogs();"/>
  </setting>
</vbox>

Note that there isn't any <script> support. The root <vbox> just acts as a container, it isn't merged into the main window.

If you use type="control" settings that aren't tied to preferences, then you will probably need to initialize them when they first appear. You can't do this until your options XUL has been loaded into the browser window, so you should observe the AddonManager.OPTIONS_NOTIFICATION_DISPLAYED notification to initialize your settings. For example:

 Cu.import("resource://gre/modules/AddonManager.jsm");
 
 Services.obs.addObserver(observe, AddonManager.OPTIONS_NOTIFICATION_DISPLAYED, false);
 
 function observe(document, topic, id) {
   if (id != MY_ADDON_ID) {
     return;
   }
   
   let control = document.getElementById("myaddon-pref-control");
   control.value = "test";
   
   Services.obs.removeObserver(observe, AddonManager.OPTIONS_NOTIFICATION_DISPLAYED);
 }

See Also

• Adding Preferences To An Extension has more information about add-on options in both Firefox and Fennec, including how to set defaults for preferences.
• The Bigger Text source code is a complete example add-on that uses options.