= Unobtrusive Flash Object Plug-In = The `sfUFOPlugin` offers helpers that facilitate the insertion of Flash movies in an unobtrusive way. It relies on the [http://trac.symfony-project.com/trac/wiki/sfUJSPlugin sfUJSPlugin] and the [http://jquery.lukelutman.com/plugins/flash/ jQuery flash plug-in] ''Warning'': Due to the youth of its underlying components, and to its own youth, this plugin is in Alpha state. Syntax is subject to change. == Possible uses == * Embedding Flash objects in HTML content * Embedding YouTube videos, MP3 players, etc. * sIFR == Installation == * Install the plugin {{{ $ symfony plugin-install http://plugins.symfony-project.com/sfUFOPlugin }}} `sfUFOPlugin` has a dependency on `sfUJSPlugin`. If this last plugin is not installed, the `plugin-install` command will install it for you. You will also have to follow the supplementary installation steps described in the [http://trac.symfony-project.com/trac/wiki/sfUJSPlugin sfUJSPlugin helper installation page] * Alternatively, if you don't have PEAR installed, you can download the latest package attached to this plugin's wiki page and extract it under your project's `plugins/` directory == Basic syntax == === Declaring the helper in templates === The UFO plugin provides a set of helpers to be used within templates. As for other helpers, you must declare the related helper group to make the helper functions available in the template. {{{ <?php use_helper('UFO') ?> }}} === Adding Flash movies unobtrusively === The following template code: {{{ <div id="foobar"> I'm here ! </div> <?php UFO('#foobar', 'src=swf/example.swf')") ?> }}} Renders as follows: {{{ <head> <script type="text/javascript" src="/UJS/script/key/bc8b3812f3d7a20f7ed7c1ab25ec449a.php"></script> <link rel="stylesheet" type="text/css" media="screen" href="/sfUFOPlugin/css/UFO-screen.css" /> <link rel="stylesheet" type="text/css" media="print" href="/sfUFOPlugin/css/UFO-print.css" /> </head> <body> <div id="foobar"> I'm here ! </div> </body> }}} The attached script will contain: {{{ $().ready(function(){ $('#foobar').flash({ src: 'swf/example.swf'}); }) }}} The resulting DOM after execution is: {{{ <div id="foobar" class="flash-replaced"> <embed width="320" height="240" type="application/x-shockwave-flash" src="/./swf/example.swf" pluginspage="http://www.adobe.com/go/getflashplayer" flashvars=""/> <div class="alt"> I'm here ! </div> </div> }}} The attached style sheets will guarantee that the alternative text disappears in the screen but keeps in printed pages. === Flash Options === In addition to the `src` option, the second argument of the `UFO()` helper can contain other options. As with other symfony helpers, the options can be given as an associative array or as a HTML4 style. - `width`: Width of the flash movie in pixels - `height`: Height of the flash movie in pixels - `type`: Mime-type of the embedded object. Defaults `application/x-shockwave-flash` - `flashvars`: Hash of the parameters passed to the Flash. Ex: `{ foo: 'bar' }` - `bgcolor`: Background color of the embedded object. Ex: `#cccccc` - `version`: Minimal version of flash player required to play the movie. Ex: '6.0.65' - `update`: If true (default), users without a compatible flash player will be prompted to update it - `expressInstall`: If true, an update will use [http://www.adobe.com/cfusion/knowledgebase/index.cfm?id=6a253b75 Express Install] Any other usual tag attribute (such as `class`, `id`, etc.) is also accepted. So a complex example of Flash insertion could be: {{{ <div id="foobar"> I'm here ! </div> <?php UFO('#foobar', array( 'src' => 'swf/example.swf', 'width' => 150, 'height' => 250, 'flashvars' => "{ foo: 'bar' }", 'version' => '6.0.65', 'expressInstall' => true ) ) ?> }}} === Adding a Flash movie without DOM reference === The first example presented above uses an existing `<div>` tag to locate the place to put the Flash movie. If you don't have a placeholder to refer to, call the `UJS_write()` helper where you want the movie to appear, the helper will put a placeholder of its own and add the Flash movie unobtrusively. {{{ <?php UFO_write('swf/example.swf', 'width=10 height=10 update=false') ?> }}} Notice that users witout JavaScript and Flash support will not see anything. === Transforming a link to a Flash movie into an embedded Flash object === The correct, unobtrusive way of profiding Flash content is to propose a link to the Flash object to everybody, and to replace the link by an embedded Flash object to those who can support it. This is simply done by the `UFO_flashify()` helper: {{{ <a class="swf" href="/swf/example.swf">click me to see a flash movie</a> <?php UFO_flashify('.swf') ?> }}} The first argument of the helper is a jQuery selector, the second (optional) is the same options argument as for the `UFO()` helper. The resulting DOM after execution on the server and on the client side looks as follows: {{{ <span class="flash-replaced"> <embed width="320" height="240" type="application/x-shockwave-flash" src="/swf/example.swf" pluginspage="http://www.adobe.com/go/getflashplayer" flashvars=""/> <a class="swf alt" href="/swf/example.swf">click me to see a flash movie</a> </span> }}} This can be used to embed a YouTube video or a MP3 player. === Using Flash as a text replacement (sIFR) === Flash can be used to bypass the HTML protocol's limitations and render a text heading with a special font. See [http://www.mikeindustries.com/sifr/ Mike Davidson's website] for more information about this technique, called sIFR. To replace a text by some Flash text, you must use a special Flash font file (see Mike Davidson's site for details). You can also specify a few style elements of the text. Here is an example: {{{ <p class="sIFR">Hi <a href="toto.html">mates</a>!</p> <?php UFO_style('.sIFR', 'swf/itc_century.swf', "linkcolor: '#0000FF'") ?> }}} The second argument is a Flash font file, the third is a list of Flash font formatting, among: - `textcolor` - `linkcolor` - `hovercolor` The `UFO_style() helper accepts a fourth parameter, similar to the options parameter or the `UFO()` helper. Once again, complex escaping issues can be bypassed by using normal CSS syntax inside a special version of the `UFO_style()` helper, as follows: {{{ <p class="sIFR">Hi <a href="toto.html">mates</a>!</p> <?php UFO_style_block() ?> .sFIR { font: 'swf/tradegothic.swf'; textcolor: '#666666'; linkcolor: #0000FF; hovercolor: '#5500FF'; } <?php UFO_style_end_block() ?> }}} This is much more easy to use and code. The next step, as you could guess, is to store these pseudo-CSS rules in a reusable CSS file under your project's web root, and telling symfony to use it for UFO-styling. So, an alternatice to the solution presented above would be with two files. In `css/flash.css`: {{{ .sFIR { font: 'swf/tradegothic.swf'; textcolor: #666666; linkcolor: #0000FF; hovercolor: #5500FF; } }}} Then, in the template: {{{ <p class="sIFR">Hi <a href="toto.html">mates</a>!</p> <?php UFO_use_stylesheet('css/flash.css') ?> }}} Beware that this is not a real CSS file (for instance, there is no cascading), and only the four attributes shown above can be defined in it. == Testing the plugin == == Todo == * Unit tests * Better Flash object compatibility * More sIFR options * Add tests files in test/ directory == Changelog == === 2007-03-23 | 0.5.0 Alpha === * Emiliano.Gabrielli: Added real support to expressInstall (fixed jquery.flash.js too) === 2007-03-23 | 0.5.0 Alpha === * francois: Initial release