Modifying the Page Hosted by a Tab

To follow this tutorial you'll need to have installed the SDK and learned the basics of cfx.

This tutorial uses the action button API, which is only available from Firefox 29 onwards.

To modify the page hosted by a particular tab, load a script into it using the attach() method of the tab object. Because their job is to interact with web content, these scripts are called content scripts.

Here's a simple example:

var button = require("sdk/ui/button/action").ActionButton({
  id: "style-tab",
  label: "Style Tab",
  icon: "./icon-16.png",
  onClick: function() {
    require("sdk/tabs").activeTab.attach({
      contentScript: 'document.body.style.border = "5px solid red";'
    });
  }
});

To run this example you'll also have to have an icon file named "icon-16.png" saved in your add-on's "data" directory. You could download this icon: .

This add-on creates a button which contains the Mozilla favicon as an icon. It has a click handler which fetches the active tab and loads a script into the page hosted by the active tab. The script is specified using the contentScript option, and just draws a red border around the page.

Then open any web page in the browser window, and click the button . You should see a red border appear around the page, like this:

Keeping the Content Script in a Separate File

In the example above we've passed in the content script as a string. Unless the script is extremely simple, you should instead maintain the script as a separate file. This makes the code easier to maintain, debug, and review.

For example, if we save the script above under the add-on's data directory in a file called my-script.js:

var self = require("sdk/self");

var button = require("sdk/ui/button/action").ActionButton({
  id: "style-tab",
  label: "Style Tab",
  icon: "./icon-16.png",
  onClick: function() {
    require("sdk/tabs").activeTab.attach({
      contentScriptFile: self.data.url("my-script.js")
    });
  }
});

You can load more than one script, and the scripts can interact directly with each other. So you can load jQuery, and then your content script can use that.

Communicating With the Content Script

Your add-on script and the content script can't directly access each other's variables or call each other's functions, but they can send each other messages.

To send a message from one side to the other, the sender calls port.emit() and the receiver listens using port.on().

  • In the content script, port is a property of the global self object.
  • In the add-on script, tab.attach() returns a worker object containing the port property you use to send messages to the content script.

Let's rewrite the example above to pass a message from the add-on to the content script. The content script now needs to look like this:

// "self" is a global object in content scripts
// Listen for a "drawBorder"
self.port.on("drawBorder", function(color) {
  document.body.style.border = "5px solid " + color;
});

In the add-on script, we'll send the content script a "drawBorder" message using the object returned from attach():

var self = require("sdk/self");
var tabs = require("sdk/tabs");

var button = require("sdk/ui/button/action").ActionButton({
  id: "style-tab",
  label: "Style Tab",
  icon: "./icon-16.png",
  onClick: function() {
    worker = tabs.activeTab.attach({
      contentScriptFile: self.data.url("my-script.js")
    });
    worker.port.emit("drawBorder", "red");
  }
});

The drawBorder message isn't a built-in message, it's one that this add-on defines in the port.emit() call.

Injecting CSS

Unlike the page-mod API, tab.attach() doesn't enable you to inject CSS directly into a page.

To modify the style of a page you have to use JavaScript, as in the example above.

Learning More

To learn more about working with tabs in the SDK, see the Open a Web Page tutorial, the List Open Tabs tutorial, and the tabs API reference.

To learn more about content scripts, see the content scripts guide.

Attachments

File Size Date Attached by
tab-attach
19185 bytes 2013-12-06 13:19:38 Canuckistani
icon-16
1657 bytes 2014-04-09 19:53:18 wbamberg

Document Tags and Contributors

Contributors to this page: Canuckistani, wbamberg, bruno91
Last updated by: wbamberg,