Opera Sidebar Action API

Contents

DescriptionAvailabilityManifestLearn More
Add actions in the browser sidebar. In addition to its icon, a sidebar action can also have a tooltip, a badge, and a panel.For Opera 30 and onwards."sidebar_action": { … }Creating extensions for the sidebar.

Terminology

There are some additional elements in the browser that we need to understand in the context of sidebar extensions. These are the sidebar, which consists of a buttons list on the left hand side (which contains the icons for sidebar extensions). Clicking on each icon will open up its corresponding panel on the right hand side of the sidebar.

Manifest

These would be the changes in the manifest:

{
	"manifest_version": 2,
	"name": "My extension",
	"version": "1",
	"sidebar_action": {
		// Required
		"default_icon": "images/default_icon.png",
		// Optional; shown in tooltip
		"default_title" : "My Extension Title",
		// Required
		"default_panel": "panel.html"
	}
}

You can also specify a series of sizes and icon paths as keys and values, instead of a single icon value described above. If you want to specify icons for a series of sizes, then instead of mentioning one default icon, you can specify an object listing out the paths to the icons and their corresponding sizes in the default_icon field like so:

"sidebar_action": {
	"default_icon": {
		"19": "images/19.png",
		"38": "images/38.png"
	}
}

Icon

You can set the icon in two ways: using a static image or using the HTML5 <canvas> element. Using static images is easier for simple applications, but you can create more dynamic UIs — such as smooth animation — using the canvas element. Static images can be in any format Blink can display, including BMP, GIF, ICO, JPEG, or PNG. For unpacked extensions, images must be in the PNG format.

To set the icon, use the default_icon field of sidebar_action in the manifest, or call the sidebarAction.setIcon method (especially, if you want to switch it and set alternative icon instead).

Tooltip

To set the tooltip, use the default_title field of sidebar_action in the manifest, or call the sidebarAction.setTitle method. You can specify locale-specific strings for the default_title field; see Internationalization for details.

Badge

Sidebar actions can optionally display a badge — a bit of text that is layered over the icon. Badges make it easy to update the sidebar action to display a small amount of information about the state of the extension. Because the badge has limited space, it should have 4 characters or less. Set the text and color of the badge using sidebarAction.setBadgeText and sidebarAction.setBadgeBackgroundColor, respectively.

Panel

If a sidebar action has a panel, it will appear when the user clicks the icon. The panel can contain any HTML content that you like, and it’s automatically sized to fit the available width and height. It is recommended that developers make their panel pages fluid and responsive in order to look good in various widths.

To add a panel to your sidebar action, create an HTML file with the panel’s contents. Specify the HTML file in the default_panel field of sidebar_action in the manifest, or call the sidebarAction.setPanel method.

Summary

Types

Methods

  • setTitle — opr.sidebarAction.setTitle( object details)
  • getTitle — opr.sidebarAction.getTitle(object details, function callback)
  • setIcon — opr.sidebarAction.setIcon(object details, function callback)
  • setPanel — opr.sidebarAction.setPanel(object details)
  • getPanel — opr.sidebarAction.getPanel(object details, function callback)
  • setBadgeText — opr.sidebarAction.setBadgeText(object details) *
  • getBadgeText — opr.sidebarAction.getBadgeText(object details, function callback) *
  • setBadgeBackgroundColor — opr.sidebarAction.setBadgeBackgroundColor(object details) *
  • getBadgeBackgroundColor — opr.sidebarAction.getBadgeBackgroundColor(object details, function callback) *
  • Not supported on Mac yet.

Events

Types

ColorArray

Array of integer.

ImageDataType

Pixel data for an image. Must be an ImageData object (for example, from a <canvas> element).

Methods

setTitle

opr.sidebarAction.setTitle(
	object details
)

Sets the title of the sidebar action. This shows up in the tooltip.

Parameters
objectdetailsstringtitleThe string the sidebar action should display when moused over.
integertabId (optional)Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.

getTitle

opr.sidebarAction.getTitle(
	object details,
	function callback
)

Gets the title of the sidebar action.

Parameters
objectdetailsintegertabId (optional)Specify the tab to get the title from. If no tab is specified, the non-tab-specific title is returned.
functioncallbackstringresultThe callback parameter should be a function that looks like this: function(string result) { … }

setIcon

opr.sidebarAction.setIcon(
	object details,
	function callback
)

Sets the icon for the sidebar action. The icon can be specified either as the path to an image file or as the pixel data from a canvas element, or as dictionary of either one of those. Either the path or the imageData property must be specified.

Parameters
objectdetailsImageDataType or objectimageData (optional)Either an ImageData object or a dictionary {size -> ImageData} representing icon to be set. If the icon is specified as a dictionary, the actual image to be used is chosen depending on screen’s pixel density. If the number of image pixels that fit into one screen space unit equals scale, then image with size scale × 19 will be selected. Initially only scales 1 and 2 will be supported. At least one image must be specified. Note that details.imageData = foo is equivalent to details.imageData = {'19': foo}.
string or objectpath (optional)
integertabId (optional)Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.
functioncallback (optional)If you specify the callback parameter, it should be a function that looks like this: function() { … }.

setPanel

opr.sidebarAction.setPanel(
	object details
)

Sets the HTML document to be opened as a panel when the user clicks on the sidebar action’s icon.

Parameters
objectdetailsintegertabId (optional)Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.
stringpanelThe HTML file to show in a panel. Cannot be an emptry string (entering a valid HTML file is mandatory).

getPanel

opr.sidebarAction.getPanel(
	object details,
	function callback
)

Gets the HTML document set as the panel for this sidebar action.

Parameters
objectdetailsintegertabId (optional)Specify the tab to get the panel from. If no tab is specified, the non-tab-specific panel is returned.
functioncallbackstringresultThe callback parameter should be a function that looks like this: function(string result) { … }.

setBadgeText

opr.sidebarAction.setBadgeText(
	object details
)

Sets the badge text for the sidebar action. The badge is displayed on top of the icon.

Parameters
objectdetailsstringtextAny number of characters can be passed, but only about four can fit in the space.
integertabId (optional)Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.

Not supported on Mac yet.

getBadgeText

opr.sidebarAction.getBadgeText(
	object details,
	function callback
)

Gets the badge text of the sidebar action. If no tab is specified, the non-tab-specific badge text is returned.

Parameters
objectdetailsintegertabId (optional)Specify the tab to get the badge text from. If no tab is specified, the non-tab-specific badge text is returned.
functioncallbackstringresultThe callback parameter should be a function that looks like this: function(string result) { … }.

Not supported on Mac yet.

setBadgeBackgroundColor

opr.sidebarAction.setBadgeBackgroundColor(
	object details
)

Sets the background color for the badge.

Parameters
objectdetailsstring or ColorArraycolorAn array of four integers in the range [0,255] that make up the RGBA color of the badge. For example, opaque red is [255, 0, 0, 255]. Can also be a string with a CSS value, with opaque red being #FF0000 or #F00.
integertabId (optional)Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.

Not supported on Mac yet.

getBadgeBackgroundColor

opr.sidebarAction.getBadgeBackgroundColor(
	object details,
	function callback
)

Gets the background color of the sidebar action.

Parameters
objectdetailsintegertabId (optional)Specify the tab to get the badge background color from. If no tab is specified, the non-tab-specific badge background color is returned.
functioncallbackColorArrayresultThe callback parameter should be a function that looks like this: function(ColorArray result) { … }.

Not supported on Mac yet.

Events

onFocus

opr.sidebarAction.onFocus.addListener(
	function callback
)

When the panel becomes in focus (user clicks inside the panel).

Parameters
functioncallbackwindows.WindowwindowThe callback parameter should be a function that looks like this: function(windows.Window window) { … }

Not supported on Mac yet.

onBlur

opr.sidebarAction.onBlur.addListener(
	function callback
)

When panel loses focus when the user clicks on the webpage (or any other area outside the panel), thereby the panel loses focus.

Parameters
functioncallbackwindows.WindowwindowThe callback parameter should be a function that looks like this: function(windows.Window window) { … }

Not supported on Mac yet.