Debian Codegraph @

closure-library/closure/goog/window/window.js

raw
1 // Copyright 2006 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 window manipulation.
17 */
18
19
20 goog.provide('goog.window');
21
22 goog.require('goog.dom.TagName');
23 goog.require('goog.dom.safe');
24 goog.require('goog.html.SafeUrl');
25 goog.require('goog.html.uncheckedconversions');
26 goog.require('goog.labs.userAgent.platform');
27 goog.require('goog.string');
28 goog.require('goog.string.Const');
29 goog.require('goog.userAgent');
30
31
32 /**
33 * Default height for popup windows
34 * @type {number}
35 */
36 goog.window.DEFAULT_POPUP_HEIGHT = 500;
37
38
39 /**
40 * Default width for popup windows
41 * @type {number}
42 */
43 goog.window.DEFAULT_POPUP_WIDTH = 690;
44
45
46 /**
47 * Default target for popup windows
48 * @type {string}
49 */
50 goog.window.DEFAULT_POPUP_TARGET = 'google_popup';
51
52
53 /**
54 * @return {!Window}
55 * @suppress {checkTypes}
56 * @private
57 */
58 goog.window.createFakeWindow_ = function() {
59 return /** @type {!Window} */ ({});
60 };
61
62 /**
63 * Opens a new window.
64 *
65 * @param {?goog.html.SafeUrl|string|?Object} linkRef If an Object with an 'href'
66 * attribute (such as HTMLAnchorElement) is passed then the value of 'href'
67 * is used, otherwise its toString method is called. Note that if a
68 * string|Object is used, it will be sanitized with SafeUrl.sanitize().
69 *
70 * @param {?Object=} opt_options supports the following options:
71 * 'target': (string) target (window name). If null, linkRef.target will
72 * be used.
73 * 'width': (number) window width.
74 * 'height': (number) window height.
75 * 'top': (number) distance from top of screen
76 * 'left': (number) distance from left of screen
77 * 'toolbar': (boolean) show toolbar
78 * 'scrollbars': (boolean) show scrollbars
79 * 'location': (boolean) show location
80 * 'statusbar': (boolean) show statusbar
81 * 'menubar': (boolean) show menubar
82 * 'resizable': (boolean) resizable
83 * 'noreferrer': (boolean) whether to attempt to remove the referrer header
84 * from the request headers. Does this by opening a blank window that
85 * then redirects to the target url, so users may see some flickering.
86 *
87 * @param {?Window=} opt_parentWin Parent window that should be used to open the
88 * new window.
89 *
90 * @return {?Window} Returns the window object that was opened. This returns
91 * null if a popup blocker prevented the window from being
92 * opened. In case when a new window is opened in a different
93 * browser sandbox (such as iOS standalone mode), the returned
94 * object is a emulated Window object that functions as if
95 * a cross-origin window has been opened.
96 */
97 goog.window.open = function(linkRef, opt_options, opt_parentWin) {
98 if (!opt_options) {
99 opt_options = {};
100 }
101 var parentWin = opt_parentWin || window;
102
103 /** @type {!goog.html.SafeUrl} */
104 var safeLinkRef;
105
106 if (linkRef instanceof goog.html.SafeUrl) {
107 safeLinkRef = linkRef;
108 } else {
109 // HTMLAnchorElement has a toString() method with the same behavior as
110 // goog.Uri in all browsers except for Safari, which returns
111 // '[object HTMLAnchorElement]'. We check for the href first, then
112 // assume that it's a goog.Uri or String otherwise.
113 var url =
114 typeof linkRef.href != 'undefined' ? linkRef.href : String(linkRef);
115 safeLinkRef = goog.html.SafeUrl.sanitize(url);
116 }
117
118
119 var target = opt_options.target || linkRef.target;
120
121 var sb = [];
122 for (var option in opt_options) {
123 switch (option) {
124 case 'width':
125 case 'height':
126 case 'top':
127 case 'left':
128 sb.push(option + '=' + opt_options[option]);
129 break;
130 case 'target':
131 case 'noopener':
132 case 'noreferrer':
133 break;
134 default:
135 sb.push(option + '=' + (opt_options[option] ? 1 : 0));
136 }
137 }
138 var optionString = sb.join(',');
139
140 var newWin;
141 if (goog.labs.userAgent.platform.isIos() && parentWin.navigator &&
142 parentWin.navigator['standalone'] && target && target != '_self') {
143 // iOS in standalone mode disregards "target" in window.open and always
144 // opens new URL in the same window. The workout around is to create an "A"
145 // element and send a click event to it.
146 // Notice that the "A" tag does NOT have to be added to the DOM.
147
148 var a = /** @type {!HTMLAnchorElement} */
149 (parentWin.document.createElement(String(goog.dom.TagName.A)));
150 goog.dom.safe.setAnchorHref(a, safeLinkRef);
151
152 a.setAttribute('target', target);
153 if (opt_options['noreferrer']) {
154 a.setAttribute('rel', 'noreferrer');
155 }
156 var click = document.createEvent('MouseEvent');
157 click.initMouseEvent(
158 'click',
159 true, // canBubble
160 true, // cancelable
161 parentWin,
162 1); // detail = mousebutton
163 a.dispatchEvent(click);
164 // New window is not available in this case. Instead, a fake Window object
165 // is returned. In particular, it will have window.document undefined. In
166 // general, it will appear to most of clients as a Window for a different
167 // origin. Since iOS standalone web apps are run in their own sandbox, this
168 // is the most appropriate return value.
169 newWin = goog.window.createFakeWindow_();
170 } else if (opt_options['noreferrer']) {
171 // Use a meta-refresh to stop the referrer from being included in the
172 // request headers. This seems to be the only cross-browser way to
173 // remove the referrer. It also allows for the opener to be set to null
174 // in the new window, thus disallowing the opened window from navigating
175 // its opener.
176 //
177 // Detecting user agent and then using a different strategy per browser
178 // would allow the referrer to leak in case of an incorrect/missing user
179 // agent.
180 //
181 // Also note that we can't use goog.dom.safe.openInWindow here, as it
182 // requires a goog.string.Const 'name' parameter, while we're using plain
183 // strings here for target.
184 newWin = parentWin.open('', target, optionString);
185
186 var sanitizedLinkRef = goog.html.SafeUrl.unwrap(safeLinkRef);
187 if (newWin) {
188 if (goog.userAgent.EDGE_OR_IE) {
189 // IE/EDGE can't parse the content attribute if the url contains
190 // a semicolon. We can fix this by adding quotes around the url, but
191 // then we can't parse quotes in the URL correctly. We take a
192 // best-effort approach.
193 //
194 // If the URL has semicolons, wrap it in single quotes to protect
195 // the semicolons.
196 // If the URL has semicolons and single quotes, url-encode the single
197 // quotes as well.
198 //
199 // This is imperfect. Notice that both ' and ; are reserved characters
200 // in URIs, so this could do the wrong thing, but at least it will
201 // do the wrong thing in only rare cases.
202 // ugh.
203 if (goog.string.contains(sanitizedLinkRef, ';')) {
204 sanitizedLinkRef = "'" + sanitizedLinkRef.replace(/'/g, '%27') + "'";
205 }
206 }
207 newWin.opener = null;
208
209 // TODO(rjamet): Building proper SafeHtml with SafeHtml.createMetaRefresh
210 // pulls in a lot of compiled code, which is composed of various unneeded
211 // goog.html parts such as SafeStyle.create among others. So, for now,
212 // keep the unchecked conversion until we figure out how to make the
213 // dependencies of createSafeHtmlTagSecurityPrivateDoNotAccessOrElse less
214 // heavy.
215 var safeHtml =
216 goog.html.uncheckedconversions
217 .safeHtmlFromStringKnownToSatisfyTypeContract(
218 goog.string.Const.from(
219 'b/12014412, meta tag with sanitized URL'),
220 // The referrer policy meta tag below works around a bug in
221 // Chrome where the meta-refresh alone fails to clear the
222 // the referrer under certain circumstances
223 // (crbug.com/791216).
224 '<meta name="referrer" content="no-referrer">' +
225 '<meta http-equiv="refresh" content="0; url=' +
226 goog.string.htmlEscape(sanitizedLinkRef) + '">');
227 goog.dom.safe.documentWrite(newWin.document, safeHtml);
228 newWin.document.close();
229 }
230 } else {
231 newWin = parentWin.open(
232 goog.html.SafeUrl.unwrap(safeLinkRef), target, optionString);
233 // Passing in 'noopener' into the 'windowFeatures' param of window.open(...)
234 // will yield a feature-deprived browser. This is an known issue, tracked
235 // here: https://github.com/whatwg/html/issues/1902
236 if (newWin && opt_options['noopener']) {
237 newWin.opener = null;
238 }
239 }
240 // newWin is null if a popup blocker prevented the window open.
241 return newWin;
242 };
243
244
245 /**
246 * Opens a new window without any real content in it.
247 *
248 * This can be used to get around popup blockers if you need to open a window
249 * in response to a user event, but need to do asynchronous work to determine
250 * the URL to open, and then set the URL later.
251 *
252 * Example usage:
253 *
254 * var newWin = goog.window.openBlank('Loading...');
255 * setTimeout(
256 * function() {
257 * newWin.location.href = 'http://www.google.com';
258 * }, 100);
259 *
260 * @param {string=} opt_message String to show in the new window. This string
261 * will be HTML-escaped to avoid XSS issues.
262 * @param {?Object=} opt_options Options to open window with.
263 * {@see goog.window.open for exact option semantics}.
264 * @param {?Window=} opt_parentWin Parent window that should be used to open the
265 * new window.
266 * @return {?Window} Returns the window object that was opened. This returns
267 * null if a popup blocker prevented the window from being
268 * opened.
269 */
270 goog.window.openBlank = function(opt_message, opt_options, opt_parentWin) {
271 // Open up a window with the loading message and nothing else.
272 // This will be interpreted as HTML content type with a missing doctype
273 // and html/body tags, but is otherwise acceptable.
274 //
275 // IMPORTANT: The order of escaping is crucial here in order to avoid XSS.
276 // First, HTML-escaping is needed because the result of the JS expression
277 // is evaluated as HTML. Second, JS-string escaping is needed; this avoids
278 // \u escaping from inserting HTML tags and \ from escaping the final ".
279 // Finally, URL percent-encoding is done with encodeURI(); this
280 // avoids percent-encoding from bypassing HTML and JS escaping.
281 //
282 // Note: There are other ways the same result could be achieved but the
283 // current behavior was preserved when this code was refactored to use
284 // SafeUrl, in order to avoid breakage.
285 var loadingMessage;
286 if (!opt_message) {
287 loadingMessage = '';
288 } else {
289 loadingMessage =
290 goog.string.escapeString(goog.string.htmlEscape(opt_message));
291 }
292 var url = goog.html.uncheckedconversions
293 .safeUrlFromStringKnownToSatisfyTypeContract(
294 goog.string.Const.from(
295 'b/12014412, encoded string in javascript: URL'),
296 'javascript:"' + encodeURI(loadingMessage) + '"');
297 return /** @type {?Window} */ (
298 goog.window.open(url, opt_options, opt_parentWin));
299 };
300
301
302 /**
303 * Raise a help popup window, defaulting to "Google standard" size and name.
304 *
305 * (If your project is using GXPs, consider using {@link PopUpLink.gxp}.)
306 *
307 * @param {?goog.html.SafeUrl|string|?Object} linkRef If an Object with an 'href'
308 * attribute (such as HTMLAnchorElement) is passed then the value of 'href'
309 * is used, otherwise otherwise its toString method is called. Note that
310 * if a string|Object is used, it will be sanitized with SafeUrl.sanitize().
311 *
312 * @param {?Object=} opt_options Options to open window with.
313 * {@see goog.window.open for exact option semantics}
314 * Additional wrinkles to the options:
315 * - if 'target' field is null, linkRef.target will be used. If *that's*
316 * null, the default is "google_popup".
317 * - if 'width' field is not specified, the default is 690.
318 * - if 'height' field is not specified, the default is 500.
319 *
320 * @return {boolean} true if the window was not popped up, false if it was.
321 */
322 goog.window.popup = function(linkRef, opt_options) {
323 if (!opt_options) {
324 opt_options = {};
325 }
326
327 // set default properties
328 opt_options['target'] = opt_options['target'] || linkRef['target'] ||
329 goog.window.DEFAULT_POPUP_TARGET;
330 opt_options['width'] =
331 opt_options['width'] || goog.window.DEFAULT_POPUP_WIDTH;
332 opt_options['height'] =
333 opt_options['height'] || goog.window.DEFAULT_POPUP_HEIGHT;
334
335 var newWin = goog.window.open(linkRef, opt_options);
336 if (!newWin) {
337 return true;
338 }
339 newWin.focus();
340
341 return false;
342 };