michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: "use strict";
michael@0: 
michael@0: this.EXPORTED_SYMBOLS = [ "SharedFrame" ];
michael@0: 
michael@0: const Ci = Components.interfaces;
michael@0: const Cu = Components.utils;
michael@0: 
michael@0: /**
michael@0:  * The purpose of this module is to create and group various iframe
michael@0:  * elements that are meant to all display the same content and only
michael@0:  * one at a time. This makes it possible to have the content loaded
michael@0:  * only once, while the other iframes can be kept as placeholders to
michael@0:  * quickly move the content to them through the swapFrameLoaders function
michael@0:  * when another one of the placeholder is meant to be displayed.
michael@0:  * */
michael@0: 
michael@0: let Frames = new Map();
michael@0: 
michael@0: /**
michael@0:  * The Frames map is the main data structure that holds information
michael@0:  * about the groups being tracked. Each entry's key is the group name,
michael@0:  * and the object holds information about what is the URL being displayed
michael@0:  * on that group, and what is the active element on the group (the frame that
michael@0:  * holds the loaded content).
michael@0:  * The reference to the activeFrame is a weak reference, which allows the
michael@0:  * frame to go away at any time, and when that happens the module considers that
michael@0:  * there are no active elements in that group. The group can be reactivated
michael@0:  * by changing the URL, calling preload again or adding a new element.
michael@0:  *
michael@0:  *
michael@0:  *  Frames = {
michael@0:  *    "messages-panel": {
michael@0:  *      url: string,
michael@0:  *      activeFrame: weakref
michael@0:  *    }
michael@0:  *  }
michael@0:  *
michael@0:  * Each object on the map is called a _SharedFrameGroup, which is an internal
michael@0:  * class of this module which does not automatically keep track of its state. This
michael@0:  * object should not be used externally, and all control should be handled by the
michael@0:  * module's functions.
michael@0:  */
michael@0: 
michael@0: function UNLOADED_URL(aStr) "data:text/html;charset=utf-8,<!-- Unloaded frame " + aStr + " -->";
michael@0: 
michael@0: 
michael@0: this.SharedFrame = {
michael@0:   /**
michael@0:    * Creates an iframe element and track it as part of the specified group
michael@0:    * The module must create the iframe itself because it needs to do some special
michael@0:    * handling for the element's src attribute.
michael@0:    *
michael@0:    * @param aGroupName        the name of the group to which this frame belongs
michael@0:    * @param aParent           the parent element to which the frame will be appended to
michael@0:    * @param aFrameAttributes  an object with a list of attributes to set in the iframe
michael@0:    *                          before appending it to the DOM. The "src" attribute has
michael@0:    *                          special meaning here and if it's not blank it specifies
michael@0:    *                          the URL that will be initially assigned to this group
michael@0:    * @param aPreload          optional, tells if the URL specified in the src attribute
michael@0:    *                          should be preloaded in the frame being created, in case
michael@0:    *                          it's not yet preloaded in any other frame of the group.
michael@0:    *                          This parameter has no meaning if src is blank.
michael@0:    */
michael@0:   createFrame: function (aGroupName, aParent, aFrameAttributes, aPreload = true) {
michael@0:     let frame = aParent.ownerDocument.createElement("iframe");
michael@0: 
michael@0:     for (let [key, val] of Iterator(aFrameAttributes)) {
michael@0:       frame.setAttribute(key, val);
michael@0:     }
michael@0: 
michael@0:     let src = aFrameAttributes.src;
michael@0:     if (!src) {
michael@0:       aPreload = false;
michael@0:     }
michael@0: 
michael@0:     let group = Frames.get(aGroupName);
michael@0: 
michael@0:     if (group) {
michael@0:       // If this group has already been created
michael@0: 
michael@0:       if (aPreload && !group.isAlive) {
michael@0:         // If aPreload is set and the group is not already loaded, load it.
michael@0:         // This can happen if:
michael@0:         // - aPreload was not used while creating the previous frames of this group, or
michael@0:         // - the previously active frame went dead in the meantime
michael@0:         group.url = src;
michael@0:         this.preload(aGroupName, frame);
michael@0:       } else {
michael@0:         // If aPreload is not set, or the group is already loaded in a different frame,
michael@0:         // there's not much that we need to do here: just create this frame as an
michael@0:         // inactivate placeholder
michael@0:         frame.setAttribute("src", UNLOADED_URL(aGroupName));
michael@0:       }
michael@0: 
michael@0:     } else {
michael@0:       // This is the first time we hear about this group, so let's start tracking it,
michael@0:       // and also preload it if the src attribute was set and aPreload = true
michael@0:       group = new _SharedFrameGroup(src);
michael@0:       Frames.set(aGroupName, group);
michael@0: 
michael@0:       if (aPreload) {
michael@0:         this.preload(aGroupName, frame);
michael@0:       } else {
michael@0:         frame.setAttribute("src", UNLOADED_URL(aGroupName));
michael@0:       }
michael@0:     }
michael@0: 
michael@0:     aParent.appendChild(frame);
michael@0:     return frame;
michael@0: 
michael@0:   },
michael@0: 
michael@0:   /**
michael@0:    * Function that moves the loaded content from one active frame to
michael@0:    * another one that is currently a placeholder. If there's no active
michael@0:    * frame in the group, the content is loaded/reloaded.
michael@0:    *
michael@0:    * @param aGroupName   the name of the group
michael@0:    * @param aTargetFrame the frame element to which the content should
michael@0:    *                     be moved to.
michael@0:    */
michael@0:   setOwner: function (aGroupName, aTargetFrame) {
michael@0:     let group = Frames.get(aGroupName);
michael@0:     let frame = group.activeFrame;
michael@0: 
michael@0:     if (frame == aTargetFrame) {
michael@0:       // nothing to do here
michael@0:       return;
michael@0:     }
michael@0: 
michael@0:     if (group.isAlive) {
michael@0:       // Move document ownership to the desired frame, and make it the active one
michael@0:       frame.QueryInterface(Ci.nsIFrameLoaderOwner).swapFrameLoaders(aTargetFrame);
michael@0:       group.activeFrame = aTargetFrame;
michael@0:     } else {
michael@0:       // Previous owner was dead, reload the document at the new owner and make it the active one
michael@0:       aTargetFrame.setAttribute("src", group.url);
michael@0:       group.activeFrame = aTargetFrame;
michael@0:     }
michael@0:   },
michael@0: 
michael@0:   /**
michael@0:    * Updates the current URL in use by this group, and loads it into the active frame.
michael@0:    *
michael@0:    * @param aGroupName  the name of the group
michael@0:    * @param aURL        the new url
michael@0:    */
michael@0:   updateURL: function (aGroupName, aURL) {
michael@0:     let group = Frames.get(aGroupName);
michael@0:     group.url = aURL;
michael@0: 
michael@0:     if (group.isAlive) {
michael@0:       group.activeFrame.setAttribute("src", aURL);
michael@0:     }
michael@0:   },
michael@0: 
michael@0:   /**
michael@0:    * Loads the group's url into a target frame, if the group doesn't have a currently
michael@0:    * active frame.
michael@0:    *
michael@0:    * @param aGroupName    the name of the group
michael@0:    * @param aTargetFrame  the frame element which should be made active and
michael@0:    *                      have the group's content loaded to
michael@0:    */
michael@0:   preload: function (aGroupName, aTargetFrame) {
michael@0:     let group = Frames.get(aGroupName);
michael@0:     if (!group.isAlive) {
michael@0:       aTargetFrame.setAttribute("src", group.url);
michael@0:       group.activeFrame = aTargetFrame;
michael@0:     }
michael@0:   },
michael@0: 
michael@0:   /**
michael@0:    * Tells if a group currently have an active element.
michael@0:    *
michael@0:    * @param aGroupName  the name of the group
michael@0:    */
michael@0:   isGroupAlive: function (aGroupName) {
michael@0:     return Frames.get(aGroupName).isAlive;
michael@0:   },
michael@0: 
michael@0:   /**
michael@0:    * Forgets about this group. This function doesn't need to be used
michael@0:    * unless the group's name needs to be reused.
michael@0:    *
michael@0:    * @param aGroupName  the name of the group
michael@0:    */
michael@0:   forgetGroup: function (aGroupName) {
michael@0:     Frames.delete(aGroupName);
michael@0:   }
michael@0: }
michael@0: 
michael@0: 
michael@0: function _SharedFrameGroup(aURL) {
michael@0:   this.url = aURL;
michael@0:   this._activeFrame = null;
michael@0: }
michael@0: 
michael@0: _SharedFrameGroup.prototype = {
michael@0:   get isAlive() {
michael@0:     let frame = this.activeFrame;
michael@0:     return !!(frame &&
michael@0:               frame.contentDocument &&
michael@0:               frame.contentDocument.location);
michael@0:   },
michael@0: 
michael@0:   get activeFrame() {
michael@0:     return this._activeFrame &&
michael@0:            this._activeFrame.get();
michael@0:   },
michael@0: 
michael@0:   set activeFrame(aActiveFrame) {
michael@0:     this._activeFrame = aActiveFrame
michael@0:                         ? Cu.getWeakReference(aActiveFrame)
michael@0:                         : null;
michael@0:   }
michael@0: }