nsIFrameScriptLoader

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:

  • loadFrameScript() will load the frame script independently into each applicable frame: every open frame in the given window for the window message manager, or every frame in every window for the global message manager
  • if aAllowDelayedLoad is true, then the script will also be loaded into any applicable new frames opened after the loadFrameScript() call. Otherwise it will only be loaded into frames that exist at the time of the call.

If this function is called on a ChromeMessageSender:

  • it will load the frame script only into this ChromeMessageSender's frame
  • aAllowDelayedLoad should always be true. It's possible that the frame for this ChromeMessageSender is not yet available at the time of the loadFrameScript() call, and if you pass false in this situation, your process script won't be loaded.

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>].

Document Tags and Contributors

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