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