src/flash/Component.js

   1 /*
   2
   3 This file is part of Ext JS 4
   4
   5 Copyright (c) 2011 Sencha Inc
   6
   7 Contact:  http://www.sencha.com/contact
   8
   9 GNU General Public License Usage
  10 This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file.  Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
  11
  12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
  13
  14 */
  15 /**
  16  * @class Ext.flash.Component
  17  * @extends Ext.Component
  18  *
  19  * A simple Component for displaying an Adobe Flash SWF movie. The movie will be sized and can participate
  20  * in layout like any other Component.
  21  *
  22  * This component requires the third-party SWFObject library version 2.2 or above. It is not included within
  23  * the ExtJS distribution, so you will have to include it into your page manually in order to use this component.
  24  * The SWFObject library can be downloaded from the [SWFObject project page](http://code.google.com/p/swfobject)
  25  * and then simply import it into the head of your HTML document:
  26  *
  27  *     <script type="text/javascript" src="path/to/local/swfobject.js"></script>
  28  *
  29  * ## Configuration
  30  *
  31  * This component allows several options for configuring how the target Flash movie is embedded. The most
  32  * important is the required {@link #url} which points to the location of the Flash movie to load. Other
  33  * configurations include:
  34  *
  35  * - {@link #backgroundColor}
  36  * - {@link #wmode}
  37  * - {@link #flashVars}
  38  * - {@link #flashParams}
  39  * - {@link #flashAttributes}
  40  *
  41  * ## Example usage:
  42  *
  43  *     var win = Ext.widget('window', {
  44  *         title: "It's a tiger!",
  45  *         layout: 'fit',
  46  *         width: 300,
  47  *         height: 300,
  48  *         x: 20,
  49  *         y: 20,
  50  *         resizable: true,
  51  *         items: {
  52  *             xtype: 'flash',
  53  *             url: 'tiger.swf'
  54  *         }
  55  *     });
  56  *     win.show();
  57  *
  58  * ## Express Install
  59  *
  60  * Adobe provides a tool called [Express Install](http://www.adobe.com/devnet/flashplayer/articles/express_install.html)
  61  * that offers users an easy way to upgrade their Flash player. If you wish to make use of this, you should set
  62  * the static EXPRESS\_INSTALL\_URL property to the location of your Express Install SWF file:
  63  *
  64  *     Ext.flash.Component.EXPRESS_INSTALL_URL = 'path/to/local/expressInstall.swf';
  65  *
  66  * @docauthor Jason Johnston <jason@sencha.com>
  67  */
  68 Ext.define('Ext.flash.Component', {
  69     extend: 'Ext.Component',
  70     alternateClassName: 'Ext.FlashComponent',
  71     alias: 'widget.flash',
  72
  73     /**
  74      * @cfg {String} flashVersion
  75      * Indicates the version the flash content was published for. Defaults to <tt>'9.0.115'</tt>.
  76      */
  77     flashVersion : '9.0.115',
  78
  79     /**
  80      * @cfg {String} backgroundColor
  81      * The background color of the SWF movie. Defaults to <tt>'#ffffff'</tt>.
  82      */
  83     backgroundColor: '#ffffff',
  84
  85     /**
  86      * @cfg {String} wmode
  87      * The wmode of the flash object. This can be used to control layering. Defaults to <tt>'opaque'</tt>.
  88      * Set to 'transparent' to ignore the {@link #backgroundColor} and make the background of the Flash
  89      * movie transparent.
  90      */
  91     wmode: 'opaque',
  92
  93     /**
  94      * @cfg {Object} flashVars
  95      * A set of key value pairs to be passed to the flash object as flash variables. Defaults to <tt>undefined</tt>.
  96      */
  97
  98     /**
  99      * @cfg {Object} flashParams
 100      * A set of key value pairs to be passed to the flash object as parameters. Possible parameters can be found here:
 101      * http://kb2.adobe.com/cps/127/tn_12701.html Defaults to <tt>undefined</tt>.
 102      */
 103
 104     /**
 105      * @cfg {Object} flashAttributes
 106      * A set of key value pairs to be passed to the flash object as attributes. Defaults to <tt>undefined</tt>.
 107      */
 108
 109     /**
 110      * @cfg {String} url
 111      * The URL of the SWF file to include. Required.
 112      */
 113
 114     /**
 115      * @cfg {String/Number} swfWidth The width of the embedded SWF movie inside the component. Defaults to "100%"
 116      * so that the movie matches the width of the component.
 117      */
 118     swfWidth: '100%',
 119
 120     /**
 121      * @cfg {String/Number} swfHeight The height of the embedded SWF movie inside the component. Defaults to "100%"
 122      * so that the movie matches the height of the component.
 123      */
 124     swfHeight: '100%',
 125
 126     /**
 127      * @cfg {Boolean} expressInstall
 128      * True to prompt the user to install flash if not installed. Note that this uses
 129      * Ext.FlashComponent.EXPRESS_INSTALL_URL, which should be set to the local resource. Defaults to <tt>false</tt>.
 130      */
 131     expressInstall: false,
 132
 133     /**
 134      * @property swf
 135      * @type {Ext.Element}
 136      * A reference to the object or embed element into which the SWF file is loaded. Only
 137      * populated after the component is rendered and the SWF has been successfully embedded.
 138      */
 139
 140     // Have to create a placeholder div with the swfId, which SWFObject will replace with the object/embed element.
 141     renderTpl: ['<div id="{swfId}"></div>'],
 142
 143     initComponent: function() {
 144         // <debug>
 145         if (!('swfobject' in window)) {
 146             Ext.Error.raise('The SWFObject library is not loaded. Ext.flash.Component requires SWFObject version 2.2 or later: http://code.google.com/p/swfobject/');
 147         }
 148         if (!this.url) {
 149             Ext.Error.raise('The "url" config is required for Ext.flash.Component');
 150         }
 151         // </debug>
 152
 153         this.callParent();
 154         this.addEvents(
 155             /**
 156              * @event success
 157              * Fired when the Flash movie has been successfully embedded
 158              * @param {Ext.flash.Component} this
 159              */
 160             'success',
 161
 162             /**
 163              * @event failure
 164              * Fired when the Flash movie embedding fails
 165              * @param {Ext.flash.Component} this
 166              */
 167             'failure'
 168         );
 169     },
 170
 171     onRender: function() {
 172         var me = this,
 173             params, vars, undef,
 174             swfId = me.getSwfId();
 175
 176         me.renderData.swfId = swfId;
 177
 178         me.callParent(arguments);
 179
 180         params = Ext.apply({
 181             allowScriptAccess: 'always',
 182             bgcolor: me.backgroundColor,
 183             wmode: me.wmode
 184         }, me.flashParams);
 185
 186         vars = Ext.apply({
 187             allowedDomain: document.location.hostname
 188         }, me.flashVars);
 189
 190         new swfobject.embedSWF(
 191             me.url,
 192             swfId,
 193             me.swfWidth,
 194             me.swfHeight,
 195             me.flashVersion,
 196             me.expressInstall ? me.statics.EXPRESS_INSTALL_URL : undef,
 197             vars,
 198             params,
 199             me.flashAttributes,
 200             Ext.bind(me.swfCallback, me)
 201         );
 202     },
 203
 204     /**
 205      * @private
 206      * The callback method for handling an embedding success or failure by SWFObject
 207      * @param {Object} e The event object passed by SWFObject - see http://code.google.com/p/swfobject/wiki/api
 208      */
 209     swfCallback: function(e) {
 210         var me = this;
 211         if (e.success) {
 212             me.swf = Ext.get(e.ref);
 213             me.onSuccess();
 214             me.fireEvent('success', me);
 215         } else {
 216             me.onFailure();
 217             me.fireEvent('failure', me);
 218         }
 219     },
 220
 221     /**
 222      * Retrieve the id of the SWF object/embed element
 223      */
 224     getSwfId: function() {
 225         return this.swfId || (this.swfId = "extswf" + this.getAutoId());
 226     },
 227
 228     onSuccess: function() {
 229         // swfobject forces visiblity:visible on the swf element, which prevents it
 230         // from getting hidden when an ancestor is given visibility:hidden.
 231         this.swf.setStyle('visibility', 'inherit');
 232     },
 233
 234     onFailure: Ext.emptyFn,
 235
 236     beforeDestroy: function() {
 237         var me = this,
 238             swf = me.swf;
 239         if (swf) {
 240             swfobject.removeSWF(me.getSwfId());
 241             Ext.destroy(swf);
 242             delete me.swf;
 243         }
 244         me.callParent();
 245     },
 246
 247     statics: {
 248         /**
 249          * Sets the url for installing flash if it doesn't exist. This should be set to a local resource.
 250          * See http://www.adobe.com/devnet/flashplayer/articles/express_install.html for details.
 251          * @static
 252          * @type String
 253          */
 254         EXPRESS_INSTALL_URL: 'http:/' + '/swfobject.googlecode.com/svn/trunk/swfobject/expressInstall.swf'
 255     }
 256 });
 257