A new feature of the Mozilla 7 platform (soon to be on the Aurora channels) is the ability for extensions to have settings user-interface directly inside the Addon Manager. This will enable restartless extensions to easily have settings, and will also work for traditional extensions.
Here's how to use the new tools:
Create an options file
In most cases this will be a file called options.xul, and located inside the top-level directory of the extension (alongside install.rdf etc.). Alternatively, you can put this file elsewhere, and change install.rdf - em:optionsURL pointing to the file, and em:optionsType as 2.
Start with this:
<?xml version="1.0" ?>
<vbox xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
<!-- settings go here -->
</vbox>
The settings are represented as a list of <setting> elements of various types, for example:
<setting type="bool"
title="Boolean Setting"
desc="This is a description of the setting"
pref="extensions.settings.bool"/>
This node is represented with a checkbox. Clicking on the checkbox changes the value of the preference specified.
A description can be set with a desc attribute, or with text between the opening and closing <setting> tags. Other attributes can be use to alter the UI displayed. See the XUL documentation on MDC for control attributes.
Here's what this example looks like:
Settings Types
| type attribute | displayed as | preference stored as |
|---|---|---|
bool |
checkbox | boolean |
boolint |
checkbox | integer (use the attributes on and off to specify what values to store) |
integer |
textbox with type="number" |
integer |
string |
textbox |
string |
color |
colorpicker with type="button" |
string (in the #123456 format) |
file |
browse button and label | string |
directory |
browse button and label |
string |
(NB: color, file and directory types haven't landed just yet, see this bug.)
There's also the control type, which allows you to have a button or menulist control:
<setting type="control" title="Button">
<button label="click me!" oncommand="alert('thanks!');"/>
</setting>
<setting type="control" title="Menulist">
<menulist sizetopopup="always" onchange="alert(this.value);">
<menupopup>
<menuitem label="alpha" value="1"/>
<menuitem label="beta" value="2"/>
<menuitem label="charlie" value="3"/>
<menuitem label="delta" value="4"/>
</menupopup>
</menulist>
</setting>
Note that neither of these controls have pref attributes, you'll have to control them yourself. See below for details.
Here's what all these controls look like:
Need script?
Each time the UI is loaded, the notification addon-options-displayed is sent. Here's how to use it:
var observer = {
observe: function(aSubject, aTopic, aData) {
if (aTopic == "addon-options-displayed" && aData == "my@addon.id") {
// your code here
// aSubject is the Addon Manager document, so you can use aSubject.getElementById etc.
}
}
};
Services.obs.addObserver(observer, "addon-options-displayed", false);
Do NOT forget to remove your observer when your extension is shut down.
Adding your own settings types
If you're mad enough you can create your own setting type. Create your own XBL binding, using chrome://mozapps/content/extensions/setting.xml for example code, and bind your setting with it like this:
<setting type="mytype"
style="display:-moz-grid-line; -moz-binding:url('chrome://mynamespace/content/mybindings.xml#binding-id');"/>
If you think your setting type will be useful to others and should become a built-in type, file a bug and CC me (geoff@darktrojan.net).