Book a Demo!
CoCalc Logo Icon
StoreFeaturesDocsShareSupportNewsAboutPoliciesSign UpSign In
seleniumhq
GitHub Repository: seleniumhq/selenium
Path: blob/trunk/third_party/closure/goog/dom/iframe.js
2868 views
1
// Copyright 2008 The Closure Library Authors. All Rights Reserved.
2
//
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
6
//
7
// http://www.apache.org/licenses/LICENSE-2.0
8
//
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS-IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
14
15
/**
16
* @fileoverview Utilities for creating and working with iframes
17
* cross-browser.
18
* @author [email protected] (Garry Boyer)
19
*/
20
21
22
goog.provide('goog.dom.iframe');
23
24
goog.require('goog.dom');
25
goog.require('goog.dom.TagName');
26
goog.require('goog.dom.safe');
27
goog.require('goog.html.SafeHtml');
28
goog.require('goog.html.SafeStyle');
29
goog.require('goog.html.TrustedResourceUrl');
30
goog.require('goog.string.Const');
31
goog.require('goog.userAgent');
32
33
34
/**
35
* Safe source for a blank iframe.
36
*
37
* Intentionally not about:blank for IE, which gives mixed content warnings in
38
* IE6 over HTTPS. Using 'about:blank' for all other browsers to support Content
39
* Security Policy (CSP). According to http://www.w3.org/TR/CSP/ CSP does not
40
* allow inline javascript by default.
41
*
42
* @const {!goog.html.TrustedResourceUrl}
43
*/
44
goog.dom.iframe.BLANK_SOURCE_URL = goog.userAgent.IE ?
45
goog.html.TrustedResourceUrl.fromConstant(
46
goog.string.Const.from('javascript:""')) :
47
goog.html.TrustedResourceUrl.fromConstant(
48
goog.string.Const.from('about:blank'));
49
50
51
/**
52
* Legacy version of goog.dom.iframe.BLANK_SOURCE_URL.
53
* @const {string}
54
*/
55
goog.dom.iframe.BLANK_SOURCE =
56
goog.html.TrustedResourceUrl.unwrap(goog.dom.iframe.BLANK_SOURCE_URL);
57
58
59
/**
60
* Safe source for a new blank iframe that may not cause a new load of the
61
* iframe. This is different from {@code goog.dom.iframe.BLANK_SOURCE} in that
62
* it will allow an iframe to be loaded synchronously in more browsers, notably
63
* Gecko, following the javascript protocol spec.
64
*
65
* NOTE: This should not be used to replace the source of an existing iframe.
66
* The new src value will be ignored, per the spec.
67
*
68
* Due to cross-browser differences, the load is not guaranteed to be
69
* synchronous. If code depends on the load of the iframe,
70
* then {@code goog.net.IframeLoadMonitor} or a similar technique should be
71
* used.
72
*
73
* According to
74
* http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#javascript-protocol
75
* the 'javascript:""' URL should trigger a new load of the iframe, which may be
76
* asynchronous. A void src, such as 'javascript:undefined', does not change
77
* the browsing context document's, and thus should not trigger another load.
78
*
79
* Intentionally not about:blank, which also triggers a load.
80
*
81
* NOTE: 'javascript:' URL handling spec compliance varies per browser. IE
82
* throws an error with 'javascript:undefined'. Webkit browsers will reload the
83
* iframe when setting this source on an existing iframe.
84
*
85
* @const {!goog.html.TrustedResourceUrl}
86
*/
87
goog.dom.iframe.BLANK_SOURCE_NEW_FRAME_URL = goog.userAgent.IE ?
88
goog.html.TrustedResourceUrl.fromConstant(
89
goog.string.Const.from('javascript:""')) :
90
goog.html.TrustedResourceUrl.fromConstant(
91
goog.string.Const.from('javascript:undefined'));
92
93
94
/**
95
* Legacy version of goog.dom.iframe.BLANK_SOURCE_NEW_FRAME_URL.
96
* @const {string}
97
*/
98
goog.dom.iframe.BLANK_SOURCE_NEW_FRAME = goog.html.TrustedResourceUrl.unwrap(
99
goog.dom.iframe.BLANK_SOURCE_NEW_FRAME_URL);
100
101
102
/**
103
* Styles to help ensure an undecorated iframe.
104
* @const {string}
105
* @private
106
*/
107
goog.dom.iframe.STYLES_ = 'border:0;vertical-align:bottom;';
108
109
110
/**
111
* Creates a completely blank iframe element.
112
*
113
* The iframe will not caused mixed-content warnings for IE6 under HTTPS.
114
* The iframe will also have no borders or padding, so that the styled width
115
* and height will be the actual width and height of the iframe.
116
*
117
* This function currently only attempts to create a blank iframe. There
118
* are no guarantees to the contents of the iframe or whether it is rendered
119
* in quirks mode.
120
*
121
* @param {goog.dom.DomHelper} domHelper The dom helper to use.
122
* @param {!goog.html.SafeStyle=} opt_styles CSS styles for the iframe.
123
* @return {!HTMLIFrameElement} A completely blank iframe.
124
*/
125
goog.dom.iframe.createBlank = function(domHelper, opt_styles) {
126
var styles;
127
if (opt_styles) {
128
// SafeStyle has to be converted back to a string for now, since there's
129
// no safe alternative to createDom().
130
styles = goog.html.SafeStyle.unwrap(opt_styles);
131
} else { // undefined.
132
styles = '';
133
}
134
return domHelper.createDom(goog.dom.TagName.IFRAME, {
135
'frameborder': 0,
136
// Since iframes are inline elements, we must align to bottom to
137
// compensate for the line descent.
138
'style': goog.dom.iframe.STYLES_ + styles,
139
'src': goog.dom.iframe.BLANK_SOURCE
140
});
141
};
142
143
144
/**
145
* Writes the contents of a blank iframe that has already been inserted
146
* into the document.
147
* @param {!HTMLIFrameElement} iframe An iframe with no contents, such as
148
* one created by {@link #createBlank}, but already appended to
149
* a parent document.
150
* @param {!goog.html.SafeHtml} content Content to write to the iframe,
151
* from doctype to the HTML close tag.
152
*/
153
goog.dom.iframe.writeSafeContent = function(iframe, content) {
154
var doc = goog.dom.getFrameContentDocument(iframe);
155
doc.open();
156
goog.dom.safe.documentWrite(doc, content);
157
doc.close();
158
};
159
160
161
// TODO(gboyer): Provide a higher-level API for the most common use case, so
162
// that you can just provide a list of stylesheets and some content HTML.
163
/**
164
* Creates a same-domain iframe containing preloaded content.
165
*
166
* This is primarily useful for DOM sandboxing. One use case is to embed
167
* a trusted Javascript app with potentially conflicting CSS styles. The
168
* second case is to reduce the cost of layout passes by the browser -- for
169
* example, you can perform sandbox sizing of characters in an iframe while
170
* manipulating a heavy DOM in the main window. The iframe and parent frame
171
* can access each others' properties and functions without restriction.
172
*
173
* @param {!Element} parentElement The parent element in which to append the
174
* iframe.
175
* @param {!goog.html.SafeHtml=} opt_headContents Contents to go into the
176
* iframe's head.
177
* @param {!goog.html.SafeHtml=} opt_bodyContents Contents to go into the
178
* iframe's body.
179
* @param {!goog.html.SafeStyle=} opt_styles CSS styles for the iframe itself,
180
* before adding to the parent element.
181
* @param {boolean=} opt_quirks Whether to use quirks mode (false by default).
182
* @return {!HTMLIFrameElement} An iframe that has the specified contents.
183
*/
184
goog.dom.iframe.createWithContent = function(
185
parentElement, opt_headContents, opt_bodyContents, opt_styles, opt_quirks) {
186
var domHelper = goog.dom.getDomHelper(parentElement);
187
188
var content = goog.html.SafeHtml.create(
189
'html', {}, goog.html.SafeHtml.concat(
190
goog.html.SafeHtml.create('head', {}, opt_headContents),
191
goog.html.SafeHtml.create('body', {}, opt_bodyContents)));
192
if (!opt_quirks) {
193
content =
194
goog.html.SafeHtml.concat(goog.html.SafeHtml.DOCTYPE_HTML, content);
195
}
196
197
var iframe = goog.dom.iframe.createBlank(domHelper, opt_styles);
198
199
// Cannot manipulate iframe content until it is in a document.
200
parentElement.appendChild(iframe);
201
goog.dom.iframe.writeSafeContent(iframe, content);
202
203
return iframe;
204
};
205
206