Debian Codegraph @

closure-library/closure/goog/dom/iframe.js

raw
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 };