mozilla
Your Search Results

    Components.utils.cloneInto

    This function provides a safe way to take an object defined in a privileged scope and create a structured clone of it in a less-privileged scope. It returns a reference to the clone:

    var clonedObject = cloneInto(myObject, targetWindow);

    You can then assign the clone to an object in the target scope as an expando property, and scripts running in that scope can access it:

    targetWindow.foo = clonedObject;

    In this way privileged code, such as an add-on, can share an object with less-privileged code like a normal web page script.

    Syntax

    Components.utils.cloneInto(obj, targetScope[, options]);

    Parameters

    obj : object
    The object to clone.
    targetScope : object
    The object to attach the object to.
    options : object
    This optional parameter is an object with the following optional properties:

    Returns

    A reference to the cloned object.

    Example

    This add-on script creates an object, clones it into the content window and makes it a property of the content window global:

    // add-on script
    
    var addonScriptObject = {"greeting" : "hello from add-on"};
    contentWindow.addonScriptObject = cloneInto(addonScriptObject, contentWindow);

    Scripts running in the page can now access the object:

    // page script
    
    button.addEventListener("click", function() {
      console.log(window.addonScriptObject.greeting);     // "hello from add-on"
    }, false);

    Of course, you don't have to assign the clone to the window itself: you can assign it to some other object in the target scope:

    contentWindow.foo.addonScriptObject = cloneInto(addonScriptObject, contentWindow);

    You can also pass it into a function defined in the page script. Suppose the page script defines a function like this:

    // page script
    
    function foo(greeting) {
      console.log("they said: " + greeting.message);
    }
    

    The add-on script can define an object, clone it, and pass it into this function:

    // add-on script
    
    var addonScriptObject = {"message" : "hello from add-on"};
    contentWindow.foo(cloneInto(addonScriptObject, contentWindow));  // "they said: hello from add-on"

    Cloning objects that have functions

    If the object to be cloned contains functions, you must pass the {cloneFunctions:true} flag or you'll get an error. If you do pass this flag, then functions in the object are cloned using the same mechanism as that used in Components.utils.exportFunction:

    // add-on script
    
    var addonScriptObject = {
      greetme: function() {
        alert("hello from add-on");
      }
    };
    
    contentWindow.addonScriptObject = cloneInto(addonScriptObject,
                                               contentWindow,
                                               {cloneFunctions: true});
    
    // page script
    
    var test = document.getElementById("test");
    
    test.addEventListener("click", function() {
      window.addonScriptObject.greetme();
    }, false);

    Cloning objects that contain DOM elements

    By default, if the object you clone contains objects that are reflected from C++, such as DOM elements, the cloning operation will fail with an error. If you pass the {wrapReflectors:true} flag, then the object you clone is allowed to contain these objects:

    // add-on script
    
    var addonScriptObject = {
      body: contentWindow.document.body
    };
    
    contentWindow.addonScriptObject = cloneInto(addonScriptObject,
                                               contentWindow,
                                               {wrapReflectors: true});
    // page script
    
    var test = document.getElementById("test");
    
    test.addEventListener("click", function() {
      console.log(window.addonScriptObject.body.innerHTML);
    }, false);

    Access to these objects in the target scope is subject to the normal security checks.

     

    Document Tags and Contributors

    Contributors to this page: wbamberg, BlindWanderer
    Last updated by: wbamberg,