PageActions.jsm

Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.

Starting from Firefox 53, no new legacy add-ons will be accepted on addons.mozilla.org (AMO) for desktop Firefox and Firefox for Android.

Starting from Firefox 57, WebExtensions will be the only supported extension type. Desktop Firefox and Firefox for Android will not load other extension types.

Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to WebExtensions if they can. See the "Compatibility Milestones" document for more information.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

The PageActions object is only available to privileged code running on Firefox for Android, and is intended for use by Firefox for Android add-ons.
NOTE: PageActions.jsm replaces NativeWindow.pageactions in Firefox 34. To maintain backward compatibility NativeWindow.pageaction will still return a reference to the PageActions object, but new code should use the new JSM.

Summary

Contains the PageActions object, which can be used to add items to the Firefox for Android url/title bar, and subsequently remove them. You can add an item using PageActions.add() and remove it using PageActions.remove(). Import the script by inserting:

Components.utils.import("resource://gre/modules/PageActions.jsm");

PageActions.add() returns a uuid which you can subsequently pass into PageActions.remove() to remove the item.

NOTE: A maximum of two page action items will be shown to users at a time. If users have three page actions showing, an overflow menu will appear to handle the extra ones. Your action has NO control over whether its shown in the urlbar or overflow. Don't depend on your page action always showing in the main urlbar.

Example

The following example adds a pageaction item which is displayed whenever the user is viewing a page from a mozilla.org domain. Selecting the page action shows an alert.

Components.utils.import("resource://gre/modules/PageActions.jsm");
var uuid = null;
function pageLoad(event) {
  var win = event.originalTarget.defaultView;
  if (win.location.host == "www.mozilla.org" && !uuid) {
    uuid = Pageactions.add({
      icon: "drawable://alert_app",
      title: "My page action",
      clickCallback: function() { win.alert("Clicked!"); }
    });
  } else if (uuid) {
    PageActions.remove(uuid);
  }
}

Methods

add()

id add(options)

Adds a page action to the urlbar.

Arguments

Options
The options object describes the page action. It may contain:
Attribute Description
title The name shown to the use when your pageaction is shown as a menuitem
icon The icon shown to the use when your pageaction is shown in the urlbar. This icon will also be shown on the menuitem if page actions are overflowing. This icon should be 24x24dip to match the default icons that are included with the browser.
clickCallback The function to call if your page action is clicked.
longClickCallback Optional: The function to call if your page action is long tapped. Only page actions that are shown in the urlbar can be long tapped. Ones shown in the overflow menu can NOT be long pressed. Since you have no control over whether your icon is shown in the urlbar or in overflow, don't depend on this behaviour being available to users.

Returns

Returns the id of the page action that was added. You should store this if you want to remove the page action in the future

remove()

void remove(id)

Removes the page action associated with an id.

Arguments

id
The id of the page action to remove

Document Tags and Contributors

 Contributors to this page: rebloor, andrewtruongmoz, wbamberg, alex_johnson, wesj
 Last updated by: rebloor,