worker

This module exports the Worker trait, which may be used to construct objects implementing the Worker interface defined by the W3C, with minor differences.

Content workers are message-passing facilities for communication between content scripts and the main add-on code.

It is important to note that unlike "web workers," these workers run in the same process as web content and browser chrome, so code within workers can block the UI.

API Reference

Classes

Worker

Worker is composed from the EventEmitter trait, therefore instances of Worker and their descendants expose all the public properties exposed by EventEmitter along with additional public properties that are listed below.

Example

var workers = require("content/worker");
let worker =  workers.Worker({
  window: require("window-utils").activeWindow,
  contentScript:
    "self.port.on('hello', function(name) { " +
    "  self.port.emit('response', window.location); " +
    "});"
});
worker.port.emit("hello", { name: "worker"});
worker.port.on("response", function (location) {
  console.log(location);
});
Constructors
Worker(options)

Creates a content worker.

options : object

Options for the constructor, with the following keys:

window : object

The content window to create JavaScript sandbox for communication with.

[ contentScriptFile : string,array ]

The local file URLs of content scripts to load. Content scripts specified by this option are loaded before those specified by the contentScript option. Optional.

[ contentScript : string,array ]

The texts of content scripts to load. Content scripts specified by this option are loaded after those specified by the contentScriptFile option. Optional.

[ onMessage : function ]

Functions that will registered as a listener to a 'message' events.

[ onError : function ]

Functions that will registered as a listener to an 'error' events.

Methods
postMessage(data)

Asynchronously emits "message" events in the enclosed worker, where content script was loaded.

data : number,string,JSON

The data to send. Must be stringifiable to JSON.

destroy()

Destroy the worker by removing the content script from the page and removing all registered listeners. A detach event is fired just before removal.

Properties
port : EventEmitter

EventEmitter object that allows you to:

  • send customized messages to the worker using the port.emit function
  • receive events from the worker using the port.on function
url : string

The URL of the content.

tab : object

If this worker is attached to a content document, returns the related tab.

Events
message

This event allows the content worker to receive messages from its associated content scripts. Calling the self.postMessage() function from a content script will asynchronously emit the message event on the corresponding worker.

value

The event listener is passed the message, which must be a JSON-serializable value.

error

This event allows the content worker to react to an uncaught runtime script error that occurs in one of the content scripts.

Error

The event listener is passed a single argument which is an Error object.

detach

This event is emitted when the document associated with this worker is unloaded or the worker's destroy() method is called.