Introduction

We currently have a page actions API, but it is very weird because we were learning what we liked as we were building it. We also now have a BrowserActions API that we like a lot more, but it stinks that it is very different from the page actions API.

This proposal is for a new version of the page actions API that is more like the browser actions one. Because the two APIs are so similar, please see that document for more details.

There can be at most one browser or page action per-extension.

The difference between browser actions and page actions is that page actions only have the lifetime of a particular document. They are shown for a specific tab, but always go away when that tab navigates.

Manifest

{
  "name": "My extension that has a page action",
  "version": "1",
  "page_action": {
    "default_icon": "foo.png",  // optional
    "default_title": "Click here for foo",  // required
    "popup": "popup.html"  // optional
  }
}

Programmatic API

// Show the page action. The page action is shown whenever the tab is selected.
void chrome.pageAction.show(int tabId);

// Hide the page action.
void chrome.pageAction.hide(int tabId);

// Set the icon. Can be specified using either a path to a static icon inside
// the extension, or by using raw image data from an HTML5 canvas element
// (see: http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#imagedata)
// Either the imageData or path property must be set.
void chrome.pageAction.setIcon({optional ImageData imageData,
                                optional string path,
                                int tabId});

// Set the title of the page action. This is displayed in a tooltip over the
// page action.
void chrome.pageAction.setTitle({string title, int tabId});

// Set the badge background color. The |color| array is an array of four integers
// in the range [0-255] that specify the ARGB color for the badge background.
void chrome.pageAction.setBadgeBackgroundColor({int[] color, int tabId});

// Set the badge text color. The |color| array is an array of four integers
// in the range [0-255] that specify the ARGB color for the text background.
void chrome.pageAction.setBadgeTextColor({int[] color, int tabId});

// Set the badge text. This can be any string, but practically speaking, it is
// limited to about 4 characters.
void chrome.pageAction.setBadgeText({string text, int tabId});

// Fired when the page action is clicked.
event chrome.pageAction.onClicked(Tab tab);