Opera extensions: options page

Introduction

This article details how to use a new feature of Opera extensions called the options page. This is a page in the extension containing preferences the user can set, defined in an options.html file in the root of the extension zip.

The way it works is quite simple — when you install an extension, if your Opera install finds an options.html file in the extension, it makes a "Preferences" option available for that extension in the extension manager (Tools > Extensions > Manage Extensions).

Exactly what is put on the options page is entirely up to you as the extension author, but in general you should include form elements that allow the end user to choose different options and then save the changes to localStorage, or preferably widget.preferences, so they can then be easily applied to the extension. In this article we will present a sample extension containing an options page template that you can feel free to use in your own extensions.

Presenting the template

Before you go any further, download our sample options page template. The template is contained inside a sample extension that doesn't really do anything, and simply serves to show off the extension options page functionality. Install the sample extension, then go to the extension manager and click the cog button. You'll see the "Preferences" option, as shown in Figure 1.

Figure 1: The new Opera extensions options page functionality, reachable through the extension manager.

When you select one of the "Preferences" option, you'll go to the extension's options page, which looks like Figure 2.

Figure 2: The options page for our sample extension, containing a set of form elements allowing the user to set preferences for the extension.

How does the options page work?

If you unzip the sample extension, you'll find an options.html file in the root. The existence of this file is what tells Opera to make the "Preferences" menu option available. Wiring it up correctly, and making the correct preference setting functionality available in the options.html file is entirely up to you.

Fortunately, you'll have a much easier time of it using our options.html template. It features a number of form elements allowing you to choose different options for the extension preferences, plus some clever JavaScript.

When the user opens the options page, the script goes through any <select> and <input> elements with a name attribute and sets their value to that of the corresponding item in the widget.preferences. You can therefore feel free to remove or add form elements from the markup of the options.html page, and it will continue to work just fine.

In addition, the script automatically populates the title of the page and the name and author of the extension — it picks these up from the widget object, window.widget, which gets them from the config.xml file.

By default, the preference values are hardcoded into the markup of the options.html file. When the user changes the value of any of the form elements, the preference values are stored immediately on the widget.preferences object. You don't even need to submit the form to change the preferences!

The widget.preferences interface is exactly the same as that of the localStorage object, except that it doesn't have the same size limitations as localStorage, and widget.preferences default values can be declared in the <preference> elements of your config.xml file, as seen in The preference Element and its Attributes section of the Widget Packaging and Configuration specification. Therefore, when the script in our options.html template sets a preference on the widget.preferences object, a storage event is fired on the active documents of the extension (especially the background process). By listening to the storage events, the background process of your extension can react immediately to any change in the widget.preferences.

So, when the options page is loaded and the document is ready, the script goes through the different form elements and populates them with the values from widget.preferences — if there is one — or falls back to the default hardcoded values.

To handle preferences with multiple values, eg checkbox groups and multiple selects, we join/split the multiple values using a variable called glue in the script of our options.html template: a simple \n. If your extension requires advanced preferences, you should probably write your own options.html page to better cater for your specific use cases.

Summary

This concludes our tour of the Opera extensions options page functionality. Feel free to grab our template and use it in your own projects.