1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
|
<!-- 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/. -->
<!-- contributed by Myk Melez [myk@mozilla.org] -->
The `hidden-frame` module creates host application frames (i.e. XUL `<iframe>`
elements) that are not displayed to the user. It is useful in the construction
of APIs that load web content not intended to be directly seen or accessed
by users, like `page-worker`. It is also useful in the construction of APIs
that load web content for intermittent display, such as `panel`.
This module is not intended to be used directly by programs. Rather, it is
intended to be used by other modules that provide APIs to programs.
Introduction
------------
The module exports a constructor function, `HiddenFrame`, and two other
functions, `add` and `remove`.
`HiddenFrame` constructs a new hidden frame. `add` registers a hidden frame,
preparing it to load content. `remove` unregisters a frame, unloading any
content that was loaded in it.
Examples
--------
The following code creates a hidden frame, loads a web page into it, and then
logs its title:
var hiddenFrames = require("hidden-frame");
let hiddenFrame = hiddenFrames.add(hiddenFrames.HiddenFrame({
onReady: function() {
this.element.contentWindow.location = "http://www.mozilla.org/";
let self = this;
this.element.addEventListener("DOMContentLoaded", function() {
console.log(self.element.contentDocument.title);
}, true, true);
}
}));
See the `panel` module for a real-world example of usage of this module.
Reference
---------
<api name="HiddenFrame">
@class
`HiddenFrame` objects represent hidden frames.
<api name="HiddenFrame">
@constructor
Creates a hidden frame.
@param options {object}
Options for the frame, with the following keys:
@prop onReady {function,array}
Functions to call when the frame is ready to load content. You must specify
an `onReady` callback and refrain from using the hidden frame until
the callback gets called, because hidden frames are not always ready to load
content the moment they are added.
</api>
<api name="add">
@function
Register a hidden frame, preparing it to load content.
@param hiddenFrame {HiddenFrame} the frame to add
</api>
<api name="remove">
@function
Unregister a hidden frame, unloading any content that was loaded in it.
@param hiddenFrame {HiddenFrame} the frame to remove
</api>
<api name="element">
@property {DOMElement}
The host application frame in which the page is loaded.
</api>
<api name="onReady">
@property {array}
Functions to call when the frame is ready to load content.
</api>
</api>
|
