Mobile/Fennec/Extensions/Options
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 a few new 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 and it's limited to <setting> tags. The root <vbox> just acts as a container, it isn't merged into the main window. Here is how the options look in Fennec:
