Path: blob/trunk/third_party/closure/goog/dom/iframe.js
2868 views
// Copyright 2008 The Closure Library Authors. All Rights Reserved.1//2// Licensed under the Apache License, Version 2.0 (the "License");3// you may not use this file except in compliance with the License.4// You may obtain a copy of the License at5//6// http://www.apache.org/licenses/LICENSE-2.07//8// Unless required by applicable law or agreed to in writing, software9// distributed under the License is distributed on an "AS-IS" BASIS,10// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.11// See the License for the specific language governing permissions and12// limitations under the License.1314/**15* @fileoverview Utilities for creating and working with iframes16* cross-browser.17* @author [email protected] (Garry Boyer)18*/192021goog.provide('goog.dom.iframe');2223goog.require('goog.dom');24goog.require('goog.dom.TagName');25goog.require('goog.dom.safe');26goog.require('goog.html.SafeHtml');27goog.require('goog.html.SafeStyle');28goog.require('goog.html.TrustedResourceUrl');29goog.require('goog.string.Const');30goog.require('goog.userAgent');313233/**34* Safe source for a blank iframe.35*36* Intentionally not about:blank for IE, which gives mixed content warnings in37* IE6 over HTTPS. Using 'about:blank' for all other browsers to support Content38* Security Policy (CSP). According to http://www.w3.org/TR/CSP/ CSP does not39* allow inline javascript by default.40*41* @const {!goog.html.TrustedResourceUrl}42*/43goog.dom.iframe.BLANK_SOURCE_URL = goog.userAgent.IE ?44goog.html.TrustedResourceUrl.fromConstant(45goog.string.Const.from('javascript:""')) :46goog.html.TrustedResourceUrl.fromConstant(47goog.string.Const.from('about:blank'));484950/**51* Legacy version of goog.dom.iframe.BLANK_SOURCE_URL.52* @const {string}53*/54goog.dom.iframe.BLANK_SOURCE =55goog.html.TrustedResourceUrl.unwrap(goog.dom.iframe.BLANK_SOURCE_URL);565758/**59* Safe source for a new blank iframe that may not cause a new load of the60* iframe. This is different from {@code goog.dom.iframe.BLANK_SOURCE} in that61* it will allow an iframe to be loaded synchronously in more browsers, notably62* Gecko, following the javascript protocol spec.63*64* NOTE: This should not be used to replace the source of an existing iframe.65* The new src value will be ignored, per the spec.66*67* Due to cross-browser differences, the load is not guaranteed to be68* synchronous. If code depends on the load of the iframe,69* then {@code goog.net.IframeLoadMonitor} or a similar technique should be70* used.71*72* According to73* http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#javascript-protocol74* the 'javascript:""' URL should trigger a new load of the iframe, which may be75* asynchronous. A void src, such as 'javascript:undefined', does not change76* the browsing context document's, and thus should not trigger another load.77*78* Intentionally not about:blank, which also triggers a load.79*80* NOTE: 'javascript:' URL handling spec compliance varies per browser. IE81* throws an error with 'javascript:undefined'. Webkit browsers will reload the82* iframe when setting this source on an existing iframe.83*84* @const {!goog.html.TrustedResourceUrl}85*/86goog.dom.iframe.BLANK_SOURCE_NEW_FRAME_URL = goog.userAgent.IE ?87goog.html.TrustedResourceUrl.fromConstant(88goog.string.Const.from('javascript:""')) :89goog.html.TrustedResourceUrl.fromConstant(90goog.string.Const.from('javascript:undefined'));919293/**94* Legacy version of goog.dom.iframe.BLANK_SOURCE_NEW_FRAME_URL.95* @const {string}96*/97goog.dom.iframe.BLANK_SOURCE_NEW_FRAME = goog.html.TrustedResourceUrl.unwrap(98goog.dom.iframe.BLANK_SOURCE_NEW_FRAME_URL);99100101/**102* Styles to help ensure an undecorated iframe.103* @const {string}104* @private105*/106goog.dom.iframe.STYLES_ = 'border:0;vertical-align:bottom;';107108109/**110* Creates a completely blank iframe element.111*112* The iframe will not caused mixed-content warnings for IE6 under HTTPS.113* The iframe will also have no borders or padding, so that the styled width114* and height will be the actual width and height of the iframe.115*116* This function currently only attempts to create a blank iframe. There117* are no guarantees to the contents of the iframe or whether it is rendered118* in quirks mode.119*120* @param {goog.dom.DomHelper} domHelper The dom helper to use.121* @param {!goog.html.SafeStyle=} opt_styles CSS styles for the iframe.122* @return {!HTMLIFrameElement} A completely blank iframe.123*/124goog.dom.iframe.createBlank = function(domHelper, opt_styles) {125var styles;126if (opt_styles) {127// SafeStyle has to be converted back to a string for now, since there's128// no safe alternative to createDom().129styles = goog.html.SafeStyle.unwrap(opt_styles);130} else { // undefined.131styles = '';132}133return domHelper.createDom(goog.dom.TagName.IFRAME, {134'frameborder': 0,135// Since iframes are inline elements, we must align to bottom to136// compensate for the line descent.137'style': goog.dom.iframe.STYLES_ + styles,138'src': goog.dom.iframe.BLANK_SOURCE139});140};141142143/**144* Writes the contents of a blank iframe that has already been inserted145* into the document.146* @param {!HTMLIFrameElement} iframe An iframe with no contents, such as147* one created by {@link #createBlank}, but already appended to148* a parent document.149* @param {!goog.html.SafeHtml} content Content to write to the iframe,150* from doctype to the HTML close tag.151*/152goog.dom.iframe.writeSafeContent = function(iframe, content) {153var doc = goog.dom.getFrameContentDocument(iframe);154doc.open();155goog.dom.safe.documentWrite(doc, content);156doc.close();157};158159160// TODO(gboyer): Provide a higher-level API for the most common use case, so161// that you can just provide a list of stylesheets and some content HTML.162/**163* Creates a same-domain iframe containing preloaded content.164*165* This is primarily useful for DOM sandboxing. One use case is to embed166* a trusted Javascript app with potentially conflicting CSS styles. The167* second case is to reduce the cost of layout passes by the browser -- for168* example, you can perform sandbox sizing of characters in an iframe while169* manipulating a heavy DOM in the main window. The iframe and parent frame170* can access each others' properties and functions without restriction.171*172* @param {!Element} parentElement The parent element in which to append the173* iframe.174* @param {!goog.html.SafeHtml=} opt_headContents Contents to go into the175* iframe's head.176* @param {!goog.html.SafeHtml=} opt_bodyContents Contents to go into the177* iframe's body.178* @param {!goog.html.SafeStyle=} opt_styles CSS styles for the iframe itself,179* before adding to the parent element.180* @param {boolean=} opt_quirks Whether to use quirks mode (false by default).181* @return {!HTMLIFrameElement} An iframe that has the specified contents.182*/183goog.dom.iframe.createWithContent = function(184parentElement, opt_headContents, opt_bodyContents, opt_styles, opt_quirks) {185var domHelper = goog.dom.getDomHelper(parentElement);186187var content = goog.html.SafeHtml.create(188'html', {}, goog.html.SafeHtml.concat(189goog.html.SafeHtml.create('head', {}, opt_headContents),190goog.html.SafeHtml.create('body', {}, opt_bodyContents)));191if (!opt_quirks) {192content =193goog.html.SafeHtml.concat(goog.html.SafeHtml.DOCTYPE_HTML, content);194}195196var iframe = goog.dom.iframe.createBlank(domHelper, opt_styles);197198// Cannot manipulate iframe content until it is in a document.199parentElement.appendChild(iframe);200goog.dom.iframe.writeSafeContent(iframe, content);201202return iframe;203};204205206