Frame utilities

frame-utils.js

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

"use strict";

module.metadata = {
  "stability": "experimental"
};

const { Ci } = require("chrome");
const namespaceURI = "http://www.w3.org/1999/xhtml";

function getDocShell(frame) {
  let { frameLoader } = frame.QueryInterface(Ci.nsIFrameLoaderOwner);
  return frameLoader && frameLoader.docShell;
}

exports.getDocShell = getDocShell;

/**
 * Creates a XUL `browser` element in a privileged document.
 * @params {nsIDOMDocument} document
 * @params {String} options.type
 *    By default is 'content' for possible values see:
 *    https://developer.mozilla.org/en/XUL/iframe#a-browser.type
 * @params {String} options.uri
 *    URI of the document to be loaded into created frame.
 * @params {Boolean} options.remote
 *    If `true` separate process will be used for this frame, also in such
 *    case all the following options are ignored.
 * @params {Boolean} options.allowAuth
 *    Whether to allow auth dialogs. Defaults to `false`.
 * @params {Boolean} options.allowJavascript
 *    Whether to allow Javascript execution. Defaults to `false`.
 * @params {Boolean} options.allowPlugins
 *    Whether to allow plugin execution. Defaults to `false`.
 */
function create(document, options) {
  options = options || {};
  let remote = options.remote || false;

  let frame = document.createElementNS(namespaceURI, "iframe");
  // Type="content" is mandatory to enable stuff here:
  // http://mxr.mozilla.org/mozilla-central/source/content/base/src/nsFrameLoader.cpp#1776
  //frame.setAttribute("type", options.type || "content");

  // If specific `uri` is provided load it into frame.
  if (options.uri) frame.setAttribute("src", options.uri);

  // Indicate that the frame is to appear like a top-level browser window to
  // the embedded content. This means that `window.top`, `window.parent`,
  // `window.frameElement`, etc. will not reflect the frame hierarchy.
  frame.QueryInterface(Ci.nsIDOMMozBrowserFrame);
  frame.mozbrowser = true;

  // Inject frame into document otherwise it won't have a frame loader that
  // is required for the following steps.
  document.documentElement.appendChild(frame);

  // Load in separate process if `options.remote` is `true` frame is loaded
  // in the separate process.
  // http://mxr.mozilla.org/mozilla-central/source/content/base/src/nsFrameLoader.cpp#1347
  if (remote) {
    frame.QueryInterface(Ci.nsIMozBrowserFrame);
    frame.createRemoteFrameLoader(null);
    //frame.setAttribute('style', '-moz-binding: none;');
    //frame.setAttribute('remote', 'true');
  }
  // If frame is not remote than it has a `docShell` which can be used to
  // restrict it's capabilities.
  else {
    let docShell = getDocShell(frame);
    docShell.allowAuth = options.allowAuth || false;
    docShell.allowJavascript = options.allowJavascript || false;
    docShell.allowPlugins = options.allowPlugins || false;
  }

  return frame;
}
exports.create = create;