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, only extensions developed using WebExtensions APIs will be supported on Desktop Firefox and Firefox for Android.

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 use WebExtensions APIs 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 BrowserApp object is only available to privileged code running on Firefox for Android, and is intended for use by Firefox for Android add-ons.

Summary

Add-ons running on desktop Firefox can use the global gBrowser variable to interact with tabs and any HTML content they host. This object isn't available on Firefox for Android, and instead add-ons should use the BrowserApp object, which provides much of the same functionality.

BrowserApp is available as a property of the chrome window object. For example, if you use this template for initializing your add-on, you can access it from the window argument passed into loadIntoWindow():

function loadIntoWindow(window) {
  if (!window)
    return;
  window.BrowserApp.addTab("http://example.com/");
}

Obtain BrowserApp object with add-on SDK:

// Obtain component object : Chrome Authority
// https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials/Chrome_Authority
var { Cu } = require("chrome");

// Obtain commonly used services : Services.jsm
// https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules/Services.jsm
Cu.import("resource://gre/modules/Services.jsm");

function getBrowserApp() {

	let window = Services.wm.getMostRecentWindow("navigator:browser");
	return window.BrowserApp;

}

BrowserApp provides four main areas of functionality:

  • Enumerating and retrieving tabs.
  • Retrieving XUL browser objects.
  • Manipulating tabs: opening, closing, and selecting tabs.
  • Listening for tab events.

Enumerating and retrieving tabs

Tabs are represented as Tab objects, which include an API to access the content window they host.

// Log the titles of all open tabs
function logTabTitles(window) {
  var tabs = window.BrowserApp.tabs;
  tabs.forEach(function(tab) {
    window.console.log(tab.browser.contentTitle);
  });
}

// Get the selected tab
let tab = BrowserApp.selectedTab;

// Look up tab using an ID
let tab = BrowserApp.getTabForId(aID);

// Look up tab using a browser
let tab = BrowserApp.getTabForBrowser(aBrowser);

// Look up tab using a DOM window
let tab = BrowserApp.getTabForWindow(aWindow);

Retrieving XUL browser objects

// Get the selected browser
let selectedBrowser = BrowserApp.selectedTab.browser;

// Get the selected browser ( a shortcut)
let selectedBrowser = BrowserApp.selectedBrowser;

// Look up browser using a tab
let browser = tab.browser;

// Look up browser using a DOM window
let browser = BrowserApp.getBrowserForWindow(aWindow);

// Look up browser using a DOM document
let browser = BrowserApp.getBrowserForDocument(aDocument);

Manipulating browser tabs

// Add a tab
let tab = BrowserApp.addTab();

// Close a tab
BrowserApp.closeTab(tab);

// Select a tab
BrowserApp.selectTab(tab);

Listening for tab events

// Listening for tab events
function watchTab(aEvent) {
  // the target is a XUL browser element
  let browser = aEvent.target;
}

BrowserApp.deck.addEventListener("TabOpen", watchTab, false);
BrowserApp.deck.addEventListener("TabClose", watchTab, false);
BrowserApp.deck.addEventListener("TabSelect", watchTab, false);

Methods

getTabForId
Retrieve a tab, given its ID.
getTabForBrowser
Retrieve a tab, given its browser.
getTabForWindow
Retrieve a tab, given its DOM window.
getBrowserForWindow
Retrieve a browser, given its DOM window.
getBrowserForDocument
Retrieve a browser, given its DOM document.
addTab
Open a new tab.
closeTab
Close a tab.
selectTab
Set a tab as the selected tab.
loadURI
Load a URI into the specified browser.
getPreferences
Retrieve a set of preferences.
setPreferences
Set a single preference.
quit
Quit Firefox for Android.

Properties 

tabs
An Array of all currently open tabs, represented as Tab objects.
selectedTab
The currently selected tab, represented as a Tab object.
deck
A deck of browser objects. You can use this to listen for TabOpen, TabClose, and TabSelect events.
selectedBrowser
The browser for the currently selected tab. A shortcut for BrowserApp.selectedTab.browser.
 

Document Tags and Contributors

 Contributors to this page: rebloor, andrewtruongmoz, wbamberg, dkocho4, backy0175, MarkFinkle
 Last updated by: rebloor,