IDL file: mozilla-central/source/dom/base/nsIMessageManager.idl

Inherits from: nsISupports

This interface is used to load frame scripts.

Methods

void loadFrameScript(in AString aURL,
                     in boolean aAllowDelayedLoad,
                    [optional] in boolean aRunInGlobalScope)

void removeDelayedFrameScript(in AString aURL);
jsval getDelayedFrameScripts();

loadFrameScript()

Load a script in the remote frame. Frame scripts are loaded as soon as loadFrameScript() is called.

If this function is called on a ChromeMessageBroadcaster (for example, a global frame message manager or a window message manager) then:

If this function is called on a ChromeMessageSender:

For example:

let windowMM = window.messageManager;
windowMM.loadFrameScript('data:,dump("foo\n");', true);

This will load a separate instance of the frame script into every tab open in the window associated with this window message manager. As the user opens new tabs in this window, copies of the script will be loaded into these new tabs, as well.

Frame scripts are essentially per-tab, so they don't get reloaded when the user navigates. If you want a frame script to do something whenever a new document is loaded, you can listen for the document-element-inserted notification.

Parameters

Name Type Description
aURL String URL for the script to load. aURL must be the absolute URL. data: URLs are also supported. For example data:,dump("foo\n");
aAllowDelayedLoad Boolean If true, this flag means that the frame script will be loaded into any new frames opened after the loadFrameScript() call, until removeDelayedFrameScript() is called for that script.
aRunInGlobalScope Boolean

Optional, defaults to false.

By default, frame scripts each have their own scope, so they can declare global variables without causing conflicts with any other frame scripts. If present and set to true, this flag switches off that behavior, meaning that the script's scope is shared with any other frame scripts in the same frame that have also set the flag.

removeDelayedFrameScript()

Removes aURL from the list of scripts which support delayed load.

This cancels the effect of the aAllowDelayedLoad flag, meaning that the loader will no longer load the script into new frames. If you used aAllowDelayedLoad, you should call this as part of your cleanup (for example, when your add-on is disabled or uninstalled).

Parameters

Name Type Description
aURL String URL for the script to remove.

getDelayedFrameScripts()

Returns all delayed scripts that will be loaded once a (remote) frame becomes available. The return value is a list of pairs [<URL>, <WasLoadedInGlobalScope>].

Returns

List of the delayed scripts. Each script is returned as a pair: [<URL>, <WasLoadedInGlobalScope>].