Opera extensions: buttons, badges and popups

By David Storey

From Opera 15 onward, Opera 11 & 12’s extension format is no longer supported, and instead, we’ve switched to Chromium’s extension model. Check out our new documentation for developing extensions for Opera 15 and higher and start building your own extensions.

This article explains the ins and outs of how to create and manage toolbar buttons, and their various components. All toolbar items have to be defined and manipulated as part of the background process. They cannot be defined or manipulated directly in the injected script or popup window. Buttons, badges and popups are controlled by opera.contexts.toolbar, the details of which can be found in the Button & Badge API Guide.

Contents

• Toolbar buttons
• Creating buttons
• Adding the button to the toolbar
• Removing the button from the toolbar
• Creating a popup
• Popup contents
• Popup dimensions
• Creating a badge
• Display a badge
• Examples
• API reference

Toolbar buttons

An extension is allowed to place one button on the Opera toolbar, to the right of the search field. This button can include an 18×18 pixel icon, a tooltip (displayed on hover), a status badge, and a popup overlay.

Creating buttons

The code for creating a button should be added to the script element of the index.html document. In this example we are running the code when the load event is fired.

The first step is to define the properties of the button. This is done in the ToolbarUIItemProperties object. Here is an example:

var ToolbarUIItemProperties = {
          disabled: false,
          title: "Button Example",
          icon: "icons/button.png"
 }

Once you have defined the button properties in ToolbarUIItemProperties, you need to create the actual button with the createItem method:

var theButton = opera.contexts.toolbar.createItem(ToolbarUIItemProperties);

There are five properties which we can pass to the ToolbarUIItemProperties. The five properties are as follows:

disabled

This specifies if the button is enabled. It is true (disabled) by default and accepts a boolean value. You can disable the button as follows:

theButton.disabled = true;

title

The title property sets the tooltip that is shown when the user hovers over the button.

theButton.title = "This is a tooltip";

icon

The icon property sets the icon used on the button. If you supply a size other than 18×18 pixels it will scale the image to fit that size.

theButton.icon = "icons/beautiful-toobar-icon.png";

onclick

The function to execute when a user clicks on the button and a click event is fired.

theButton.onclick = function(){ /* do something */ };

onremove

The function to execute when the button is removed from the ToolbarContext and a remove event is fired.

theButton.onremove = function(){ /* do something */ };

Adding the button to the toolbar

The newly created button then needs to be added to Opera’s toolbar. This is done with the addItem method:

opera.contexts.toolbar.addItem(theButton);

Try running the button example. It will not do much yet, as you’ve not defined any actions on the button.

Removing the button from the toolbar

A button can be removed from the toolbar using the removeItem method:

opera.contexts.toolbar.removeItem(theButton);

Creating a popup

Now you have a button, you want to do something with it. Popups can be displayed when the user clicks on the button. A popup is an overlay window with a specified width and height. You can point to a page on the web or a page packaged with your extension to display within the popup.

To create a popup you can define the properties of the Popup object within the ToolbarUIItemProperties object:

var ToolbarUIItemProperties = {
          disabled: false,
          title: "Button Example",
          icon: "icons/button.png",
	  popup: {
            	href: "popup.html",
            	width: 400,
            	height: 200
          }

 }

Keep in mind that by default, the width and height of a popup window would be 300 by 300 units. To change it, you will need to explicitly define the width and height of the popup like the above example.

Popup contents

You point to the contents of the popup using the href property. You can point to any page on the web using its absolute URL:

theButton.popup.href = http://www.opera.com/";

You can access a locally stored web page by specifying a relative address:

theButton.popup.href = "popup.html";

The web page can be a regular HTML page. Nothing special is required. Be aware that if you change the href property while the popup is open then the popup will close.

Popup dimensions

The dimensions of a popup are specified in pixels using the width and height properties:

Width:

theButton.popup.width = 300;

Height:

theButton.popup.height = 300;

The popup will be created along with the button when calling the createItem method.

Try the button with popup example. If you worked through the Opera extensions hello world example, you will notice this extension is very similar

Creating a badge

A badge is an overlay over the icon with some textual content. They are often used to display a count of items, such as unread mails or messages. To create a badge you can define the properties of the Badge object within the ToolbarUIItemProperties object:

var ToolbarUIItemProperties = {
          disabled: false,
          title: "Button Example",
          icon: "icons/button.png",
	  badge: {
            	display: "block",
            	textContent: "12",
            	color: "white",
                backgroundColor: "rgba(211, 0, 4, 1)"
          }
 }

A badge has four properties that can be customised:

Displaying a badge

The display property shows and hides the badge. Valid values are block and none. The default value is none. A badge can be set to be visible as follows:

theButton.badge.display = "block";

textContent

The badge's label can be set using the textContent property. Badges only have a limited space to display text, so try to be concise.

theButton.badge.textContent = "12";

color and backgroundColor

The color and backgroundColor properties set the foreground (text) and background colour of the badge. They accept hexadecimal, RGBA and named colors.

theButton.badge.color = "white";

theButton.badge.backgroundColor: = "rgba(211, 0, 4, 1)";

You can try the button with badge example and play with the various ways to create and manipulate the Opera extensions' UI items.

You can also refer to the Opera extensions API documentation for a complete overview of the various objects and methods.

David Storey

David Storey heads up the Open the Web initiative at Opera. This small global team is tasked with improving the compatibility of web sites across Opera's wide range of browsers, as well as promoting web standards, accessibility and best practices, so that the Web will work for all standards-aware browsers, platforms, devices and users. He is a member of the W3C Mobile Web Best Practices Working Group.

On his blog, Slightly Ajar, he discusses this work, as well as random topics, from travel to music.

David previously worked for CERN, home of the World Wide Web, before taking up his post at Opera Software.

This article is licensed under a Creative Commons Attribution 3.0 Unported license.