|
1 <!DOCTYPE html> |
|
2 <html lang="en"> |
|
3 <head> |
|
4 <meta charset="utf-8"> |
|
5 <title>SWF Utility</title> |
|
6 <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=PT+Sans:400,700,400italic,700italic"> |
|
7 <link rel="stylesheet" href="../../build/cssgrids/cssgrids-min.css"> |
|
8 <link rel="stylesheet" href="../assets/css/main.css"> |
|
9 <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css"> |
|
10 <link rel="shortcut icon" type="image/png" href="../assets/favicon.png"> |
|
11 <script src="../../build/yui/yui-min.js"></script> |
|
12 |
|
13 </head> |
|
14 <body> |
|
15 <!-- |
|
16 <a href="https://github.com/yui/yui3"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"></a> |
|
17 --> |
|
18 <div id="doc"> |
|
19 <div id="hd"> |
|
20 <h1><img src="http://yuilibrary.com/img/yui-logo.png"></h1> |
|
21 </div> |
|
22 |
|
23 <a href="#toc" class="jump">Jump to Table of Contents</a> |
|
24 |
|
25 |
|
26 <h1>SWF Utility</h1> |
|
27 <div class="yui3-g"> |
|
28 <div class="yui3-u-3-4"> |
|
29 <div id="main"> |
|
30 <div class="content"><div class="intro"> |
|
31 <p>The YUI SWF Utility provides a standardized method for embedding the Adobe Flash player in web pages. Specifically, the SWF Utility: |
|
32 <ol> |
|
33 <li> Creates browser-specific, standards-compliant markup for correctly embedding an instance of Flash player plugin (in browsers with Netscape Plugin Architecture), or an instance of Flash Player ActiveX control (in Internet Explorer).</li> |
|
34 <li> Allows developers to set a requirement for the minimum version of Flash player installed on the end user's computer. |
|
35 <li> Provides a convenient single method instantiation of the embedded player properties and variables.</li> |
|
36 <li> Wraps the ExternalInterface API of the Flash player to allow method calls on specific player instances.</li> |
|
37 <li> In conjunction with the YUIBridge ActionScript API, allows Flash applications to dispatch events that get converted to native YUI events.</li> |
|
38 </ol> |
|
39 |
|
40 <p><strong>Important usage notes:</strong></p><ul> |
|
41 |
|
42 <li>The SWF Utility is engineered to only work with A-grade browsers. Because it allows only standards-compliant markup, the utility will not function properly in older browser versions.</li> |
|
43 <li>The <code>swfReady</code> event provided by the SWF Utility is only available when the Flash application being embedded uses the YUIBridge ActionScript library (see below).</li> |
|
44 <li>The current recommended version of the Flash Player is 10.1, available at the <a href="http://www.adobe.com/go/getflashplayer">Adobe Flash Player Download Center</a>.</li> |
|
45 </ul> |
|
46 </div> |
|
47 |
|
48 <h2 id="getting-started">Getting Started</h2> |
|
49 |
|
50 <p> |
|
51 To include the source files for SWF Utility and its dependencies, first load |
|
52 the YUI seed file if you haven't already loaded it. |
|
53 </p> |
|
54 |
|
55 <pre class="code prettyprint"><script src="http://yui.yahooapis.com/3.10.3/build/yui/yui-min.js"></script></pre> |
|
56 |
|
57 |
|
58 <p> |
|
59 Next, create a new YUI instance for your application and populate it with the |
|
60 modules you need by specifying them as arguments to the <code>YUI().use()</code> method. |
|
61 YUI will automatically load any dependencies required by the modules you |
|
62 specify. |
|
63 </p> |
|
64 |
|
65 <pre class="code prettyprint"><script> |
|
66 // Create a new YUI instance and populate it with the required modules. |
|
67 YUI().use('swf', function (Y) { |
|
68 // SWF Utility is available and ready for use. Add implementation |
|
69 // code here. |
|
70 }); |
|
71 </script></pre> |
|
72 |
|
73 |
|
74 <p> |
|
75 For more information on creating YUI instances and on the |
|
76 <a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the |
|
77 documentation for the <a href="../yui/index.html">YUI Global Object</a>. |
|
78 </p> |
|
79 |
|
80 |
|
81 <h2 id="using-the-swf-utility">Using the SWF Utility</h2> |
|
82 |
|
83 <p>This section describes how to use the SWF Utility in further detail. |
|
84 |
|
85 |
|
86 <h3 id="anatomy-of-the-swf-utility">Anatomy of the SWF Utility</h3> |
|
87 |
|
88 <p>The SWF Utility uses the browser information from the <code>Y.ua</code> variable to generate the appropriate markup for embedding the Flash player. The markup that the SWF Utility generates is entirely based on the <code><object></code> tag, and therefore will not work in older browsers that use the non-standard <code><embed></code> tag. |
|
89 </p> |
|
90 <p>In addition, the SWF Utility also determines the version of the Flash player (using YUI's <code>swfdetect</code> library), and places that information in <code>Y.ua.flash</code> as a period-delimited string (MajorVersion.MinorVersion.Revision). This information is used by SWF utility to prevent Flash Player embedding if the version of user's installed Flash player does not match that required by the developer.</p> |
|
91 <p> |
|
92 While the SWF Utility provides a direct access to the instance of the Flash player it encapsulates, it is recommended that all communication to that instance occur via the methods provided by the SWF Utility (see below.) |
|
93 </p> |
|
94 |
|
95 <h3 id="configuring-and-instantiating-the-swf-utility">Configuring and Instantiating the SWF Utility</h3> |
|
96 <p>For simplicity, all configuration of the embedded Flash player instance happens in the SWF Utility at construction time, and therefore, all configuration parameters must be provided as arguments to the SWF constructor.</p> |
|
97 <p>By default, the SWF constructor requires only two arguments – the reference to the container in which the instance of the Flash player should be placed, and the URL of the swf application that the Flash player instance should load. Note that the Flash player instance created by the SWF Utility always adopts the size of the parent container it is placed into; therefore, setting the size of the Flash player is as simple as setting the size of its container.</p> |
|
98 <p>To put an instance of the Flash player on the page, simply create a new instance of <code>Y.SWF</code> and provide it with the reference to the container in which it should be placed, as well as the URL of the swf file that needs to be loaded:</p> |
|
99 <pre class="code prettyprint">YUI({...}).use('swf',function (Y) { |
|
100 |
|
101 // Default everything |
|
102 var myswf = new Y.SWF("#swfContainer", "http://example.com/example.swf"); |
|
103 |
|
104 });</pre> |
|
105 |
|
106 |
|
107 <p>If you would like to specify additional parameters or pass arbitrary variables to the SWF, you can provide the constructor with the third argument, a paramter Object:</p> |
|
108 <pre class="code prettyprint">var params = {version: "9.0.115", |
|
109 fixedAttributes: |
|
110 {allowScriptAccess:"always", allowNetworking:"all"}, |
|
111 flashVars: |
|
112 {foo: "bar", foo1: "bar1"} |
|
113 }; |
|
114 var myswf = new Y.SWF("#swfContainer", "http://example.com/example.swf", params);</pre> |
|
115 |
|
116 |
|
117 <p>The parameter object may contain the following possible properties:</p> |
|
118 |
|
119 |
|
120 <table> |
|
121 <thead> |
|
122 <tr> |
|
123 <th>Property</th> |
|
124 <th>Description</th> |
|
125 </tr> |
|
126 </thead> |
|
127 <tbody> |
|
128 <tr> |
|
129 <td><code>version</code></td> |
|
130 <td>A period-delimited string of three numbers specifying the minimum version of Flash player that must be installed on the user's machine.</td> |
|
131 </tr> |
|
132 <tr> |
|
133 <td><code>fixedAttributes</code></td> |
|
134 <td>An object with a set of configuration variables specific to the Flash player. The list of all possible configuration variables and their values, provided by Adobe, can be found <a href="http://help.adobe.com/en_US/flex/using/WS2db454920e96a9e51e63e3d11c0bf69084-7f18.html">here</a>.</td> |
|
135 </tr> |
|
136 <tr> |
|
137 <td><code>flashVars</code></td> |
|
138 <td>An object with a set of variables to pass to the Flash player. These variables are made available to the Flash application at initialization time, in the ActionScript's <code>Stage.loaderInfo.parameters</code> container.</td> |
|
139 </tr> |
|
140 </tbody> |
|
141 </table> |
|
142 <h3 id="calling-methods-on-the-instance-of-flash-player">Calling Methods on the instance of Flash player</h3> |
|
143 |
|
144 <p>The SWF Utility provides a wrapper for calling methods that have been exposed to JavaScript from within the Flash application. This allows the developer to call the methods without having to directly reference the private pointer to the instance of the Flash player contained in the SWF Utility. To call a method <code>foo(arg1, arg2)</code> on an instance of the Flash player, do the following: |
|
145 |
|
146 <pre class="code prettyprint">YUI({...}).use('swf',function (Y) { |
|
147 |
|
148 var myswf = new Y.SWF("#swfContainer", "http://example.com/example.swf"); |
|
149 myswf.callSWF("foo", [arg1, arg2]); |
|
150 |
|
151 });</pre> |
|
152 |
|
153 |
|
154 <p>Note that, since Flash player is run as a separate thread, the existence of its instance is not guaranteed when the method call on it is made. To make sure that Flash is ready to accept incoming method calls, it's best to have the Flash player make a call to JavaScript announcing that it has finished initializing. While there is a number of ways to do that, YUI hybrid components use the YUIBridge ActionScript library to automate this process. See the next section for notes on its usage.</p> |
|
155 |
|
156 <h3 id="working-with-the-yuibridge-actionscript-library">Working with the YUIBridge ActionScript Library</h3> |
|
157 |
|
158 <p>YUIBridge ActionScript library creates a standardized method for sending YUI events from a Flash application. In an ActionScript application, an instance of YUIBridge is created as follows:</p> |
|
159 |
|
160 <pre class="code prettyprint">import com.yahoo.util.YUIBridge |
|
161 |
|
162 ... |
|
163 |
|
164 // The scope for 'this' should be either the top-level application |
|
165 // or a Sprite that has been placed on the stage. |
|
166 |
|
167 var yuiBridge:YUIBridge = new YUIBridge(this.stage);</pre> |
|
168 |
|
169 |
|
170 <p>Instead of using <code>ExternalInterface.addCallback</code> on each method that needs to be exposed to JavaScript, you can instead call a collective <code>addCallbacks()</code> method available in YUIBridge:</p> |
|
171 |
|
172 <pre class="code prettyprint">import com.yahoo.util.YUIBridge |
|
173 |
|
174 ... |
|
175 |
|
176 // The scope for 'this' should be either the top-level application |
|
177 // or a Sprite that has been placed on the stage. |
|
178 |
|
179 var yuiBridge:YUIBridge = new YUIBridge(this.stage); |
|
180 yuiBridge.addCallbacks({externalMethodName:internalMethod, externalMethodName2:internalMethod2}); |
|
181 |
|
182 });</pre> |
|
183 |
|
184 |
|
185 <p>To dispatch YUI events (fired by the instance of the SWF Utility on the JavaScript end, you can call YUIBridge's <code>sendEvent</code> method:</p> |
|
186 |
|
187 <pre class="code prettyprint">import com.yahoo.util.YUIBridge |
|
188 |
|
189 ... |
|
190 |
|
191 // The scope for 'this' should be either the top-level application |
|
192 // or a Sprite that has been placed on the stage. |
|
193 |
|
194 var yuiBridge:YUIBridge = new YUIBridge(this.stage); |
|
195 yuiBridge.sendEvent({type:'someevent', payload:'some payload'}); |
|
196 });</pre> |
|
197 |
|
198 |
|
199 <p>In addition to any custom events you dispatch, YUIBridge also fires a <code>swfReady</code> event at initialization time, announcing that the Flash player is ready for communication with JavaScript:</p> |
|
200 <pre class="code prettyprint">YUI({...}).use('swf',function (Y) { |
|
201 |
|
202 var myswf = new Y.SWF("#swfContainer", "http://example.com/example.swf"); |
|
203 myswf.on('swfReady', init); |
|
204 |
|
205 function init() { |
|
206 // Start communicating with the Flash player instance here |
|
207 myswf.callSWF("foo", [arg1, arg2]); |
|
208 } |
|
209 |
|
210 });</pre> |
|
211 |
|
212 </div> |
|
213 </div> |
|
214 </div> |
|
215 |
|
216 <div class="yui3-u-1-4"> |
|
217 <div class="sidebar"> |
|
218 |
|
219 <div id="toc" class="sidebox"> |
|
220 <div class="hd"> |
|
221 <h2 class="no-toc">Table of Contents</h2> |
|
222 </div> |
|
223 |
|
224 <div class="bd"> |
|
225 <ul class="toc"> |
|
226 <li> |
|
227 <a href="#getting-started">Getting Started</a> |
|
228 </li> |
|
229 <li> |
|
230 <a href="#using-the-swf-utility">Using the SWF Utility</a> |
|
231 <ul class="toc"> |
|
232 <li> |
|
233 <a href="#anatomy-of-the-swf-utility">Anatomy of the SWF Utility</a> |
|
234 </li> |
|
235 <li> |
|
236 <a href="#configuring-and-instantiating-the-swf-utility">Configuring and Instantiating the SWF Utility</a> |
|
237 </li> |
|
238 <li> |
|
239 <a href="#calling-methods-on-the-instance-of-flash-player">Calling Methods on the instance of Flash player</a> |
|
240 </li> |
|
241 <li> |
|
242 <a href="#working-with-the-yuibridge-actionscript-library">Working with the YUIBridge ActionScript Library</a> |
|
243 </li> |
|
244 </ul> |
|
245 </li> |
|
246 </ul> |
|
247 </div> |
|
248 </div> |
|
249 |
|
250 |
|
251 |
|
252 |
|
253 |
|
254 </div> |
|
255 </div> |
|
256 </div> |
|
257 </div> |
|
258 |
|
259 <script src="../assets/vendor/prettify/prettify-min.js"></script> |
|
260 <script>prettyPrint();</script> |
|
261 |
|
262 <script> |
|
263 YUI.Env.Tests = { |
|
264 examples: [], |
|
265 project: '../assets', |
|
266 assets: '../assets/swf', |
|
267 name: 'swf', |
|
268 title: 'SWF Utility', |
|
269 newWindow: '', |
|
270 auto: false |
|
271 }; |
|
272 |
|
273 </script> |
|
274 <script src="../assets/yui/test-runner.js"></script> |
|
275 |
|
276 |
|
277 |
|
278 </body> |
|
279 </html> |