Debian Codegraph @

closure-library/closure/goog/ui/media/flashobject.js

raw
1 // Copyright 2009 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 Wrapper on a Flash object embedded in the HTML page.
17 * This class contains routines for writing the HTML to create the Flash object
18 * using a goog.ui.Component approach. Tested on Firefox 1.5, 2 and 3, IE6, 7,
19 * Konqueror, Chrome and Safari.
20 *
21 * Based on http://go/flashobject.js
22 *
23 * Based on the following compatibility test suite:
24 * http://www.bobbyvandersluis.com/flashembed/testsuite/
25 *
26 * TODO(user): take a look at swfobject, and maybe use it instead of the current
27 * flash embedding method.
28 *
29 * Examples of usage:
30 *
31 * <pre>
32 * var url = goog.html.TrustedResourceUrl.fromConstant(
33 * goog.string.Const.from('https://hostname/flash.swf'))
34 * var flash = new goog.ui.media.FlashObject(url);
35 * flash.setFlashVar('myvar', 'foo');
36 * flash.render(goog.dom.getElement('parent'));
37 * </pre>
38 *
39 * TODO(user, jessan): create a goog.ui.media.BrowserInterfaceFlashObject that
40 * subclasses goog.ui.media.FlashObject to provide all the goodness of
41 * http://go/browserinterface.as
42 *
43 */
44
45 goog.provide('goog.ui.media.FlashObject');
46 goog.provide('goog.ui.media.FlashObject.ScriptAccessLevel');
47 goog.provide('goog.ui.media.FlashObject.Wmodes');
48
49 goog.require('goog.asserts');
50 goog.require('goog.dom.TagName');
51 goog.require('goog.dom.safe');
52 goog.require('goog.events.Event');
53 goog.require('goog.events.EventHandler');
54 goog.require('goog.events.EventType');
55 goog.require('goog.html.TrustedResourceUrl');
56 goog.require('goog.html.flash');
57 goog.require('goog.log');
58 goog.require('goog.object');
59 goog.require('goog.string');
60 goog.require('goog.structs.Map');
61 goog.require('goog.style');
62 goog.require('goog.ui.Component');
63 goog.require('goog.userAgent');
64 goog.require('goog.userAgent.flash');
65
66
67
68 /**
69 * A very simple flash wrapper, that allows you to create flash object
70 * programmatically, instead of embedding your own HTML. It extends
71 * {@link goog.ui.Component}, which makes it very easy to be embedded on the
72 * page.
73 *
74 * @param {!goog.html.TrustedResourceUrl} flashUrl The Flash SWF URL.
75 * @param {goog.dom.DomHelper=} opt_domHelper An optional DomHelper.
76 * @extends {goog.ui.Component}
77 * @constructor
78 */
79 goog.ui.media.FlashObject = function(flashUrl, opt_domHelper) {
80 goog.ui.Component.call(this, opt_domHelper);
81
82 /**
83 * The URL of the flash movie to be embedded.
84 *
85 * @type {!goog.html.TrustedResourceUrl}
86 * @private
87 */
88 this.flashUrl_ = flashUrl;
89
90 /**
91 * An event handler used to handle events consistently between browsers.
92 * @type {goog.events.EventHandler<!goog.ui.media.FlashObject>}
93 * @private
94 */
95 this.eventHandler_ = new goog.events.EventHandler(this);
96
97 /**
98 * A map of variables to be passed to the flash movie.
99 *
100 * @type {goog.structs.Map}
101 * @private
102 */
103 this.flashVars_ = new goog.structs.Map();
104 };
105 goog.inherits(goog.ui.media.FlashObject, goog.ui.Component);
106
107
108 /**
109 * Different states of loaded-ness in which the SWF itself can be
110 *
111 * Talked about at:
112 * http://kb.adobe.com/selfservice/viewContent.do?externalId=tn_12059&sliceId=1
113 *
114 * @enum {number}
115 * @private
116 */
117 goog.ui.media.FlashObject.SwfReadyStates_ = {
118 LOADING: 0,
119 UNINITIALIZED: 1,
120 LOADED: 2,
121 INTERACTIVE: 3,
122 COMPLETE: 4
123 };
124
125
126 /**
127 * IE specific ready states.
128 *
129 * @see https://msdn.microsoft.com/en-us/library/ms534359(v=vs.85).aspx
130 * @enum {string}
131 * @private
132 */
133 goog.ui.media.FlashObject.IeSwfReadyStates_ = {
134 LOADING: 'loading',
135 UNINITIALIZED: 'uninitialized',
136 LOADED: 'loaded',
137 INTERACTIVE: 'interactive',
138 COMPLETE: 'complete'
139 };
140
141
142 /**
143 * The different modes for displaying a SWF. Note that different wmodes
144 * can result in different bugs in different browsers and also that
145 * both OPAQUE and TRANSPARENT will result in a performance hit.
146 *
147 * @enum {string}
148 */
149 goog.ui.media.FlashObject.Wmodes = {
150 /**
151 * Allows for z-ordering of the SWF.
152 */
153 OPAQUE: 'opaque',
154
155 /**
156 * Allows for z-ordering of the SWF and plays the SWF with a transparent BG.
157 */
158 TRANSPARENT: 'transparent',
159
160 /**
161 * The default wmode. Does not allow for z-ordering of the SWF.
162 */
163 WINDOW: 'window'
164 };
165
166
167 /**
168 * The different levels of allowScriptAccess.
169 *
170 * Talked about at:
171 * http://kb2.adobe.com/cps/164/tn_16494.html
172 *
173 * @enum {string}
174 */
175 goog.ui.media.FlashObject.ScriptAccessLevel = {
176 /*
177 * The flash object can always communicate with its container page.
178 */
179 ALWAYS: 'always',
180
181 /*
182 * The flash object can only communicate with its container page if they are
183 * hosted in the same domain.
184 */
185 SAME_DOMAIN: 'sameDomain',
186
187 /*
188 * The flash can not communicate with its container page.
189 */
190 NEVER: 'never'
191 };
192
193
194 /**
195 * The component CSS namespace.
196 *
197 * @type {string}
198 */
199 goog.ui.media.FlashObject.CSS_CLASS = goog.getCssName('goog-ui-media-flash');
200
201
202 /**
203 * The flash object CSS class.
204 *
205 * @type {string}
206 */
207 goog.ui.media.FlashObject.FLASH_CSS_CLASS =
208 goog.getCssName('goog-ui-media-flash-object');
209
210
211 /**
212 * A logger used for debugging.
213 *
214 * @type {goog.log.Logger}
215 * @private
216 */
217 goog.ui.media.FlashObject.prototype.logger_ =
218 goog.log.getLogger('goog.ui.media.FlashObject');
219
220
221 /**
222 * The wmode for the SWF.
223 *
224 * @type {goog.ui.media.FlashObject.Wmodes}
225 * @private
226 */
227 goog.ui.media.FlashObject.prototype.wmode_ =
228 goog.ui.media.FlashObject.Wmodes.WINDOW;
229
230
231 /**
232 * The minimum required flash version.
233 *
234 * @type {?string}
235 * @private
236 */
237 goog.ui.media.FlashObject.prototype.requiredVersion_;
238
239
240 /**
241 * The flash movie width.
242 *
243 * @type {string}
244 * @private
245 */
246 goog.ui.media.FlashObject.prototype.width_;
247
248
249 /**
250 * The flash movie height.
251 *
252 * @type {string}
253 * @private
254 */
255 goog.ui.media.FlashObject.prototype.height_;
256
257
258 /**
259 * The flash movie background color.
260 *
261 * @type {string}
262 * @private
263 */
264 goog.ui.media.FlashObject.prototype.backgroundColor_ = '#000000';
265
266
267 /**
268 * The flash movie allowScriptAccess setting.
269 *
270 * @type {string}
271 * @private
272 */
273 goog.ui.media.FlashObject.prototype.allowScriptAccess_ =
274 goog.ui.media.FlashObject.ScriptAccessLevel.SAME_DOMAIN;
275
276
277 /**
278 * Sets the flash movie Wmode.
279 *
280 * @param {goog.ui.media.FlashObject.Wmodes} wmode the flash movie Wmode.
281 * @return {!goog.ui.media.FlashObject} The flash object instance for chaining.
282 */
283 goog.ui.media.FlashObject.prototype.setWmode = function(wmode) {
284 this.wmode_ = wmode;
285 return this;
286 };
287
288
289 /**
290 * @return {string} Returns the flash movie wmode.
291 */
292 goog.ui.media.FlashObject.prototype.getWmode = function() {
293 return this.wmode_;
294 };
295
296
297 /**
298 * Adds flash variables.
299 *
300 * @param {goog.structs.Map|Object} map A key-value map of variables.
301 * @return {!goog.ui.media.FlashObject} The flash object instance for chaining.
302 */
303 goog.ui.media.FlashObject.prototype.addFlashVars = function(map) {
304 this.flashVars_.addAll(map);
305 return this;
306 };
307
308
309 /**
310 * Sets a flash variable.
311 *
312 * @param {string} key The name of the flash variable.
313 * @param {string} value The value of the flash variable.
314 * @return {!goog.ui.media.FlashObject} The flash object instance for chaining.
315 */
316 goog.ui.media.FlashObject.prototype.setFlashVar = function(key, value) {
317 this.flashVars_.set(key, value);
318 return this;
319 };
320
321
322 /**
323 * Sets flash variables. You can either pass a Map of key->value pairs or you
324 * can pass a key, value pair to set a specific variable.
325 *
326 * TODO(user, martino): Get rid of this method.
327 *
328 * @deprecated Use {@link #addFlashVars} or {@link #setFlashVar} instead.
329 * @param {goog.structs.Map|Object|string} flashVar A map of variables (given
330 * as a goog.structs.Map or an Object literal) or a key to the optional
331 * {@code opt_value}.
332 * @param {string=} opt_value The optional value for the flashVar key.
333 * @return {!goog.ui.media.FlashObject} The flash object instance for chaining.
334 */
335 goog.ui.media.FlashObject.prototype.setFlashVars = function(
336 flashVar, opt_value) {
337 if (flashVar instanceof goog.structs.Map ||
338 goog.typeOf(flashVar) == 'object') {
339 this.addFlashVars(/**@type {!goog.structs.Map|!Object}*/ (flashVar));
340 } else {
341 goog.asserts.assert(
342 goog.isString(flashVar) && goog.isDef(opt_value),
343 'Invalid argument(s)');
344 this.setFlashVar(
345 /**@type {string}*/ (flashVar),
346 /**@type {string}*/ (opt_value));
347 }
348 return this;
349 };
350
351
352 /**
353 * @return {goog.structs.Map} The current flash variables.
354 */
355 goog.ui.media.FlashObject.prototype.getFlashVars = function() {
356 return this.flashVars_;
357 };
358
359
360 /**
361 * Sets the background color of the movie.
362 *
363 * @param {string} color The new color to be set.
364 * @return {!goog.ui.media.FlashObject} The flash object instance for chaining.
365 */
366 goog.ui.media.FlashObject.prototype.setBackgroundColor = function(color) {
367 this.backgroundColor_ = color;
368 return this;
369 };
370
371
372 /**
373 * @return {string} The background color of the movie.
374 */
375 goog.ui.media.FlashObject.prototype.getBackgroundColor = function() {
376 return this.backgroundColor_;
377 };
378
379
380 /**
381 * Sets the allowScriptAccess setting of the movie.
382 *
383 * @param {string} value The new value to be set.
384 * @return {!goog.ui.media.FlashObject} The flash object instance for chaining.
385 */
386 goog.ui.media.FlashObject.prototype.setAllowScriptAccess = function(value) {
387 this.allowScriptAccess_ = value;
388 return this;
389 };
390
391
392 /**
393 * @return {string} The allowScriptAccess setting color of the movie.
394 */
395 goog.ui.media.FlashObject.prototype.getAllowScriptAccess = function() {
396 return this.allowScriptAccess_;
397 };
398
399
400 /**
401 * Sets the width and height of the movie.
402 *
403 * @param {number|string} width The width of the movie.
404 * @param {number|string} height The height of the movie.
405 * @return {!goog.ui.media.FlashObject} The flash object instance for chaining.
406 */
407 goog.ui.media.FlashObject.prototype.setSize = function(width, height) {
408 this.width_ = goog.isString(width) ? width : Math.round(width) + 'px';
409 this.height_ = goog.isString(height) ? height : Math.round(height) + 'px';
410 if (this.getElement()) {
411 goog.style.setSize(this.getFlashElement(), this.width_, this.height_);
412 }
413 return this;
414 };
415
416
417 /**
418 * @return {?string} The flash required version.
419 */
420 goog.ui.media.FlashObject.prototype.getRequiredVersion = function() {
421 return this.requiredVersion_;
422 };
423
424
425 /**
426 * Sets the minimum flash required version.
427 *
428 * @param {?string} version The minimum required version for this movie to work,
429 * or null if you want to unset it.
430 * @return {!goog.ui.media.FlashObject} The flash object instance for chaining.
431 */
432 goog.ui.media.FlashObject.prototype.setRequiredVersion = function(version) {
433 this.requiredVersion_ = version;
434 return this;
435 };
436
437
438 /**
439 * Returns whether this SWF has a minimum required flash version.
440 *
441 * @return {boolean} Whether a required version was set or not.
442 */
443 goog.ui.media.FlashObject.prototype.hasRequiredVersion = function() {
444 return this.requiredVersion_ != null;
445 };
446
447
448 /**
449 * Writes the Flash embedding {@code HTMLObjectElement} to this components root
450 * element and adds listeners for all events to handle them consistently.
451 * @override
452 */
453 goog.ui.media.FlashObject.prototype.enterDocument = function() {
454 goog.ui.media.FlashObject.superClass_.enterDocument.call(this);
455
456 // The SWF tag must be written after this component's element is appended to
457 // the DOM. Otherwise Flash's ExternalInterface is broken in IE.
458 goog.dom.safe.setInnerHtml(
459 /** @type {!Element} */ (this.getElement()), this.createSwfTag_());
460 if (this.width_ && this.height_) {
461 this.setSize(this.width_, this.height_);
462 }
463
464 // Sinks all the events on the bubble phase.
465 //
466 // Flash plugins propagates events from/to the plugin to the browser
467 // inconsistently:
468 //
469 // 1) FF2 + linux: the flash plugin will stop the propagation of all events
470 // from the plugin to the browser.
471 // 2) FF3 + mac: the flash plugin will propagate events on the <embed> object
472 // but that will get propagated to its parents.
473 // 3) Safari 3.1.1 + mac: the flash plugin will propagate the event to the
474 // <object> tag that event will propagate to its parents.
475 // 4) IE7 + windows: the flash plugin will eat all events, not propagating
476 // anything to the javascript.
477 // 5) Chrome + windows: the flash plugin will eat all events, not propagating
478 // anything to the javascript.
479 //
480 // To overcome this inconsistency, all events from/to the plugin are sinked,
481 // since you can't assume that the events will be propagated.
482 //
483 // NOTE(user): we only sink events on the bubbling phase, since there are no
484 // inexpensive/scalable way to stop events on the capturing phase unless we
485 // added an event listener on the document for each flash object.
486 this.eventHandler_.listen(
487 this.getElement(), goog.object.getValues(goog.events.EventType),
488 goog.events.Event.stopPropagation);
489 };
490
491
492 /**
493 * Creates the DOM structure.
494 *
495 * @override
496 */
497 goog.ui.media.FlashObject.prototype.createDom = function() {
498 if (this.hasRequiredVersion() &&
499 !goog.userAgent.flash.isVersion(
500 /** @type {string} */ (this.getRequiredVersion()))) {
501 goog.log.warning(
502 this.logger_,
503 'Required flash version not found:' + this.getRequiredVersion());
504 throw new Error(goog.ui.Component.Error.NOT_SUPPORTED);
505 }
506
507 var element = this.getDomHelper().createElement(goog.dom.TagName.DIV);
508 element.className = goog.ui.media.FlashObject.CSS_CLASS;
509 this.setElementInternal(element);
510 };
511
512
513 /**
514 * Creates the HTML to embed the flash object.
515 *
516 * @return {!goog.html.SafeHtml} Browser appropriate HTML to add the SWF to the
517 * DOM.
518 * @private
519 */
520 goog.ui.media.FlashObject.prototype.createSwfTag_ = function() {
521 var keys = this.flashVars_.getKeys();
522 var values = this.flashVars_.getValues();
523 var flashVars = [];
524 for (var i = 0; i < keys.length; i++) {
525 var key = goog.string.urlEncode(keys[i]);
526 var value = goog.string.urlEncode(values[i]);
527 flashVars.push(key + '=' + value);
528 }
529 var flashVarsString = flashVars.join('&');
530 if (goog.userAgent.IE && !goog.userAgent.isDocumentModeOrHigher(11)) {
531 return this.createSwfTagOldIe_(flashVarsString);
532 } else {
533 return this.createSwfTagModern_(flashVarsString);
534 }
535 };
536
537
538 /**
539 * Creates the HTML to embed the flash object for IE>=11 and other browsers.
540 *
541 * @param {string} flashVars The value of the FlashVars attribute.
542 * @return {!goog.html.SafeHtml} Browser appropriate HTML to add the SWF to the
543 * DOM.
544 * @private
545 */
546 goog.ui.media.FlashObject.prototype.createSwfTagModern_ = function(flashVars) {
547 return goog.html.flash.createEmbed(this.flashUrl_, {
548 'AllowScriptAccess': this.allowScriptAccess_,
549 'allowFullScreen': 'true',
550 'allowNetworking': 'all',
551 'bgcolor': this.backgroundColor_,
552 'class': goog.ui.media.FlashObject.FLASH_CSS_CLASS,
553 'FlashVars': flashVars,
554 'id': this.getId(),
555 'name': this.getId(),
556 'quality': 'high',
557 'SeamlessTabbing': 'false',
558 'wmode': this.wmode_
559 });
560 };
561
562
563 /**
564 * Creates the HTML to embed the flash object for IE<11.
565 *
566 * @param {string} flashVars The value of the FlashVars attribute.
567 * @return {!goog.html.SafeHtml} Browser appropriate HTML to add the SWF to the
568 * DOM.
569 * @private
570 */
571 goog.ui.media.FlashObject.prototype.createSwfTagOldIe_ = function(flashVars) {
572 return goog.html.flash.createObjectForOldIe(
573 this.flashUrl_, {
574 'allowFullScreen': 'true',
575 'AllowScriptAccess': this.allowScriptAccess_,
576 'allowNetworking': 'all',
577 'bgcolor': this.backgroundColor_,
578 'FlashVars': flashVars,
579 'quality': 'high',
580 'SeamlessTabbing': 'false',
581 'wmode': this.wmode_
582 },
583 {
584 'class': goog.ui.media.FlashObject.FLASH_CSS_CLASS,
585 'id': this.getId(),
586 'name': this.getId()
587 });
588 };
589
590
591 /**
592 * @return {HTMLObjectElement} The flash element or null if the element can't
593 * be found.
594 */
595 goog.ui.media.FlashObject.prototype.getFlashElement = function() {
596 return /** @type {HTMLObjectElement} */ (
597 this.getElement() ? this.getElement().firstChild : null);
598 };
599
600
601 /** @override */
602 goog.ui.media.FlashObject.prototype.disposeInternal = function() {
603 goog.ui.media.FlashObject.superClass_.disposeInternal.call(this);
604 this.flashVars_ = null;
605
606 this.eventHandler_.dispose();
607 this.eventHandler_ = null;
608 };
609
610
611 /**
612 * @return {boolean} whether the SWF has finished loading or not.
613 */
614 goog.ui.media.FlashObject.prototype.isLoaded = function() {
615 if (!this.isInDocument() || !this.getElement()) {
616 return false;
617 }
618
619 // IE has different readyState values for elements.
620 if (goog.userAgent.EDGE_OR_IE && this.getFlashElement().readyState &&
621 this.getFlashElement().readyState ==
622 goog.ui.media.FlashObject.IeSwfReadyStates_.COMPLETE) {
623 return true;
624 }
625
626 if (this.getFlashElement().readyState &&
627 this.getFlashElement().readyState ==
628 goog.ui.media.FlashObject.SwfReadyStates_.COMPLETE) {
629 return true;
630 }
631
632 // Use "in" operator to check for PercentLoaded because IE8 throws when
633 // accessing directly. See:
634 // https://github.com/google/closure-library/pull/373.
635 if ('PercentLoaded' in this.getFlashElement() &&
636 this.getFlashElement().PercentLoaded() == 100) {
637 return true;
638 }
639
640 return false;
641 };