Inline options

Firefox 7 supports a new syntax for defining extensions' preferences for both bootstrapped and traditional extensions. The user interface for the preferences defined with this new syntax appears in the extension's detail view in the Add-on Manager. This functionality originally appeared in Firefox mobile and is now available in Firefox on the desktop as well.

Options file

The XUL allowed for the inline options is limited to a few new tags. Here is an example of an options.xul file:

<?xml version="1.0"?>
<!DOCTYPE mydialog SYSTEM "chrome://myaddon/locale/mydialog.dtd">
<vbox xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
  <setting type="bool" pref="extensions.myaddon.bool" title="Boolean" desc="Stored as a boolean preference" />
</vbox>

Note that it's limited to <setting> tags. The root <vbox> just acts as a container, it isn't merged into the main window. If you need script support, see the display notifications section.

Setting types

There are several types of <setting>s, each with a different type attribute:

The pref attribute should have the full name of the preference to be stored. The title attribute is used as a label for the controls. To set a description, either use the desc attribute, or a text node as a child of the <setting> tag.

Settings are tied to actual preferences, except the button setting, which is designed more for actions.

Some examples:

<!-- Boolean examples -->
<setting pref="extensions.myaddon.bool1" type="bool" title="Boolean 1"/>
<setting pref="extensions.myaddon.bool2" type="bool" title="Boolean 2">
  Description of Boolean 2
</setting>
<!-- Boolean stored as an integer -->
<setting pref="extensions.myaddon.boolInt" type="boolint" title="Boolean 3" on="1" off="2"/>
<!-- Integer example -->
<setting pref="extensions.myaddon.int" type="integer" title="Integer"/>
<!-- String examples -->
<setting pref="extensions.myaddon.text" type="string" title="Text"/>
<setting pref="extensions.myaddon.password" type="string" title="Password" inputtype="password"/>
<!-- Color example -->
<setting pref="extensions.myaddon.color" type="color" title="Color"/>
<!-- File and directory examples -->
<setting pref="extensions.myaddon.file" type="file" title="File"/>
<setting pref="extensions.myaddon.directory" type="directory" title="Directory"/>
<!-- List example (this example would be stored as an integer) -->
<setting pref="extensions.myaddon.options1" type="menulist" title="Options 1">
  <menulist>
    <menupopup>
      <menuitem value="500" label="small"/>
      <menuitem value="800" label="medium"/>
      <menuitem value="1200" label="large"/>
    </menupopup>
  </menulist>
</setting>
<!-- Radio Button example (this example would be stored as a boolean) -->
<setting pref="extensions.myaddon.options2" type="radio" title="Options 2">
  <radiogroup>
    <radio value="false" label="disabled"/>
    <radio value="true" label="enabled"/>
  </radiogroup>
</setting>
 
<!-- Button example - not tied to a preference, but attached to a command -->
<setting title="Do Something" type="control">
  <button id="myaddon-button" label="Click Me" oncommand="alert('Thank you!');"/>
</setting>

Setting element changed notifications

Most of the setting elements (it might be all I havent really looked), support oninputchanged attribute. So like for the type="file", once a user browses and picks a file, when it updates the label it will trigger the oninputchanged attribute. So if you would like to do some changes to the XUL on the inline options page you can do so. The this value is the setting XUL element. See MXR for what all this holds: http://mxr.mozilla.org/mozilla-release/source/toolkit/mozapps/extensions/content/setting.xml for example you can fire this.inputChanged() etc etc.

    <setting pref="extensions.ThrobberRestored.showTxtOnToolbar" title="Show Text on Toolbar Button" type="bool" oninputchanged="alert('New value is = ' + this.value); this.style.backgroundColor='red';">
        If labels on other toolbar buttons are visible (like by using add-on "Classic Theme Restorer") then show label on throbber toolbar button
    </setting>

Some discussion on the subject at StackOverflow: How to use addEventListener on inputChanged of inline options

Display notifications

If you want to use the settings UI for anything more than storing 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 Add-on Manager window, so you should listen for the addon-options-displayed notification to initialize your settings. For example:

var observer = {
  observe: function(aSubject, aTopic, aData) {
    if (aTopic == "addon-options-displayed" && aData == "MY_ADDON@MY_DOMAIN") {
      var doc = aSubject;
      var control = doc.getElementById("myaddon-pref-control");
      control.value = "test";
    }
  }
};
Services.obs.addObserver(observer, "addon-options-displayed", false);
// Don't forget to remove your observer when your add-on is shut down.

This code should be in bootstrap.js (within the startup() function) for restartless extensions or in an XPCOM component or a JavaScript code module (not an overlay!) for traditional extensions.

Locating the options file

There are two ways to let the Add-on Manager find your options file:

• Method 1 Name the file options.xul and put it in the extension's root folder (alongside install.rdf). This method does not require you to create a chrome.manifest and set it's path. This method does not require you to specify optionsType in install.rdf.
• Method 2 Use install.rdf to identify the XUL file used for displaying the options. This requires that you register a content path in the chrome.manifest. You must also specify the optionsType as 2:

  <em:optionsURL>chrome://myaddon/content/name_of_my_file_to_use_for_inline_opts.xul</em:optionsURL>
  <em:optionsType>2</em:optionsType>
  

  Your chrome.manifest file should contain the following, otherwise the path chrome://myaddon/content/name_of_my_file_to_use_for_inline_opts.xul will not exist

  content myaddon ./

  This method allows you to maintain compatibility with previous versions of Firefox by adding an override to your chrome.manifest:

  override chrome://myaddon/content/name_of_my_file_to_use_for_inline_opts.xul chrome://myaddon/content/oldOptions.xul application={ec8030f7-c20a-464f-9b0e-13a3a9e97384} appversion<=6.*
  

Opening Inline Options in Add-on Manager

If you would like to programatcially open up the add-on manager with your options displayed you can do so by using BrowserOpenAddonsMgr function which is available on "navigator:browser" type windows. For example:

Components.utils.import('resource://gre/modules/Services.jsm');
Services.wm.getMostRecentWindow('navigator:browser').BrowserOpenAddonsMgr();

To open up the add-on manager with your inline options shown do so by passing the URL to your add-ons preferences page which is "addons://detail/" followed by your add-on id followed by "/preferences". Seen in snippet here:

Components.utils.import('resource://gre/modules/Services.jsm');
Services.wm.getMostRecentWindow('navigator:browser').BrowserOpenAddonsMgr('addons://detail/YOUR_ADDON_ID_HERE/preferences');

Read more about it at this topic here on Mozilla Add-ons Forum :: How to open an add-on's preference panel?. Shown on this page are tricks, like you can pass the link to any page in the add-on manager to load that page such as the services page like: BrowserOpenAddonsMgr('addons://list/service').

Examples

• None

See also

• https://wiki.mozilla.org/Mobile/Fennec/Extensions/Options
• Add-ons > Code snippets > Preferences
• XUL School > Adding preferences to an extension