The Tor Browser / file revision

 /* 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";

 this.EXPORTED_SYMBOLS = [ "SharedFrame" ];

 const Ci = Components.interfaces;

 const Cu = Components.utils;

 /**

  * The purpose of this module is to create and group various iframe

  * elements that are meant to all display the same content and only

  * one at a time. This makes it possible to have the content loaded

  * only once, while the other iframes can be kept as placeholders to

  * quickly move the content to them through the swapFrameLoaders function

  * when another one of the placeholder is meant to be displayed.

  * */

 let Frames = new Map();

 /**

  * The Frames map is the main data structure that holds information

  * about the groups being tracked. Each entry's key is the group name,

  * and the object holds information about what is the URL being displayed

  * on that group, and what is the active element on the group (the frame that

  * holds the loaded content).

  * The reference to the activeFrame is a weak reference, which allows the

  * frame to go away at any time, and when that happens the module considers that

  * there are no active elements in that group. The group can be reactivated

  * by changing the URL, calling preload again or adding a new element.

  *

  *

  *  Frames = {

  *    "messages-panel": {

  *      url: string,

  *      activeFrame: weakref

  *    }

  *  }

  *

  * Each object on the map is called a _SharedFrameGroup, which is an internal

  * class of this module which does not automatically keep track of its state. This

  * object should not be used externally, and all control should be handled by the

  * module's functions.

  */

 function UNLOADED_URL(aStr) "data:text/html;charset=utf-8,<!-- Unloaded frame " + aStr + " -->";

 this.SharedFrame = {

   /**

    * Creates an iframe element and track it as part of the specified group

    * The module must create the iframe itself because it needs to do some special

    * handling for the element's src attribute.

    *

    * @param aGroupName        the name of the group to which this frame belongs

    * @param aParent           the parent element to which the frame will be appended to

    * @param aFrameAttributes  an object with a list of attributes to set in the iframe

    *                          before appending it to the DOM. The "src" attribute has

    *                          special meaning here and if it's not blank it specifies

    *                          the URL that will be initially assigned to this group

    * @param aPreload          optional, tells if the URL specified in the src attribute

    *                          should be preloaded in the frame being created, in case

    *                          it's not yet preloaded in any other frame of the group.

    *                          This parameter has no meaning if src is blank.

    */

   createFrame: function (aGroupName, aParent, aFrameAttributes, aPreload = true) {

     let frame = aParent.ownerDocument.createElement("iframe");

     for (let [key, val] of Iterator(aFrameAttributes)) {

       frame.setAttribute(key, val);

     }

     let src = aFrameAttributes.src;

     if (!src) {

       aPreload = false;

     }

     let group = Frames.get(aGroupName);

     if (group) {

       // If this group has already been created

       if (aPreload && !group.isAlive) {

         // If aPreload is set and the group is not already loaded, load it.

         // This can happen if:

         // - aPreload was not used while creating the previous frames of this group, or

         // - the previously active frame went dead in the meantime

         group.url = src;

         this.preload(aGroupName, frame);

       } else {

         // If aPreload is not set, or the group is already loaded in a different frame,

         // there's not much that we need to do here: just create this frame as an

         // inactivate placeholder

         frame.setAttribute("src", UNLOADED_URL(aGroupName));

       }

     } else {

       // This is the first time we hear about this group, so let's start tracking it,

       // and also preload it if the src attribute was set and aPreload = true

       group = new _SharedFrameGroup(src);

       Frames.set(aGroupName, group);

       if (aPreload) {

         this.preload(aGroupName, frame);

       } else {

         frame.setAttribute("src", UNLOADED_URL(aGroupName));

       }

     }

     aParent.appendChild(frame);

     return frame;

   },

   /**

    * Function that moves the loaded content from one active frame to

    * another one that is currently a placeholder. If there's no active

    * frame in the group, the content is loaded/reloaded.

    *

    * @param aGroupName   the name of the group

    * @param aTargetFrame the frame element to which the content should

    *                     be moved to.

    */

   setOwner: function (aGroupName, aTargetFrame) {

     let group = Frames.get(aGroupName);

     let frame = group.activeFrame;

     if (frame == aTargetFrame) {

       // nothing to do here

       return;

     }

     if (group.isAlive) {

       // Move document ownership to the desired frame, and make it the active one

       frame.QueryInterface(Ci.nsIFrameLoaderOwner).swapFrameLoaders(aTargetFrame);

       group.activeFrame = aTargetFrame;

     } else {

       // Previous owner was dead, reload the document at the new owner and make it the active one

       aTargetFrame.setAttribute("src", group.url);

       group.activeFrame = aTargetFrame;

     }

   },

   /**

    * Updates the current URL in use by this group, and loads it into the active frame.

    *

    * @param aGroupName  the name of the group

    * @param aURL        the new url

    */

   updateURL: function (aGroupName, aURL) {

     let group = Frames.get(aGroupName);

     group.url = aURL;

     if (group.isAlive) {

       group.activeFrame.setAttribute("src", aURL);

     }

   },

   /**

    * Loads the group's url into a target frame, if the group doesn't have a currently

    * active frame.

    *

    * @param aGroupName    the name of the group

    * @param aTargetFrame  the frame element which should be made active and

    *                      have the group's content loaded to

    */

   preload: function (aGroupName, aTargetFrame) {

     let group = Frames.get(aGroupName);

     if (!group.isAlive) {

       aTargetFrame.setAttribute("src", group.url);

       group.activeFrame = aTargetFrame;

     }

   },

   /**

    * Tells if a group currently have an active element.

    *

    * @param aGroupName  the name of the group

    */

   isGroupAlive: function (aGroupName) {

     return Frames.get(aGroupName).isAlive;

   },

   /**

    * Forgets about this group. This function doesn't need to be used

    * unless the group's name needs to be reused.

    *

    * @param aGroupName  the name of the group

    */

   forgetGroup: function (aGroupName) {

     Frames.delete(aGroupName);

   }

 }

 function _SharedFrameGroup(aURL) {

   this.url = aURL;

   this._activeFrame = null;

 }

 _SharedFrameGroup.prototype = {

   get isAlive() {

     let frame = this.activeFrame;

     return !!(frame &&

               frame.contentDocument &&

               frame.contentDocument.location);

   },

   get activeFrame() {

     return this._activeFrame &&

            this._activeFrame.get();

   },

   set activeFrame(aActiveFrame) {

     this._activeFrame = aActiveFrame

                         ? Cu.getWeakReference(aActiveFrame)

                         : null;

   }

 }