remote/child

Enables an SDK module loaded into a child process to access web content in the child process and communicate with modules in the main process.

Usage

The sdk/remote/parent module enables SDK code to load modules into child processes. The sdk/remote/child module is for these "child process modules". It provides two main things:

• access to web content loaded into this child process
• port mechanisms to communicate with the main process

Interacting with web content

To interact with web content, the sdk/remote/child module provides a frames property that's a list of all content frames loaded into this child process.

Each frame then has a content property that's the top-level DOM window for the frame, and addEventListener/removeEventListener functions that enable you to listen to DOM events dispatched by the frame.

Communicating with the parent process

To communicate with the parent process, the process, frames, and frame objects in sdk/remote/child have a port object that you can use to receive messages from, and send messages to, code in the parent.

See the documentation for sdk/remote/parent for more details.

Globals

Properties

process

A Process object.

frames

A Frames object.

Process

A link to the main process.

Properties

port

An event emitter that sends and receives events from the main process.

isRemote

A boolean property indicating whether this process is remote from the main process or not.

Frames

A list of the content frames in this process. Each element in this list is a Frame. Listen to attach and detach events to hear as frames are created and destroyed.

Methods

forEvery

Calls the callback for every existing frame and any new frames created in the future. This is a shortcut for enumerating existing frames and then listening for attach events.

getFrameForWindow

Finds the frame for a top level DOM window.

addEventListener

Adds an event listener for DOM events dispatched to any existing and future frames.

removeEventListener

Removes an event listener that was previously registered.

Properties

port

An event emitter that sends and receives events from every frame in this process.

Events

attach

Triggered when a new content frame is opened (for example, the user opened a new tab).

The event listener gets a Frame object as an argument.

At this point you can't access frame's content yet, but you can add event listeners:

const { frames } = require("sdk/remote/child");

frames.on("attach", function(frame) {
  console.log("new frame");
  frame.addEventListener("DOMContentLoaded", function(e) {
    console.log(e.target.location.href);
  });
});

detach

Triggered when a frame is removed (for example, the user closed a tab).

Frame

A Frame represents a content frame in this process and provides a way to communicate frame specific events to the main process.

Methods

addEventListener(event, listener, isCapturing)

Adds an event listener for DOM events dispatched by this content frame. This can include load and unload events from any content that is loaded in the frame. Listeners are automatically removed when this frame is destroyed.

removeEventListener(event, listener, isCapturing)

Removes an event listener that was previously registered.

Properties

port

An event emitter that can be used to send and receive frame specific events to and from code in the main process.

content

The top level DOM window currently displaying in this frame.

isTab

A boolean property indicating whether this frame displays in one of the application's main browser tabs.

Events

detach

Event emitted when this frame disconnects from the application.