This documentation relates to Opera's now deprecated .oex Extension API framework for Opera versions <= 12.15 and also provided by our OEX2NEX shim library.
For the latest Opera Extensions API documentation for Opera versions > 12.15 please consult the latest Opera Extensions API documentation online.
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.
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.
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:
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;The title property sets the tooltip that is shown when the user hovers over the button.
theButton.title = "This is a tooltip";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";The function to execute when a user clicks on the button and a click event is fired.
theButton.onclick = function(){ /* do something */ };The function to execute when the button is removed from the ToolbarContext and a remove event is fired.
theButton.onremove = function(){ /* do something */ };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.
A button can be removed from the toolbar using the removeItem method:
opera.contexts.toolbar.removeItem(theButton);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.
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.
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
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:
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";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";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.