# Unobtrusive Flash Object Plug-In

The `sfUFOPlugin` offers helpers that facilitate the insertion of Flash movies in an unobtrusive way.

It relies on the [sfUJSPlugin] and the [http://jquery.lukelutman.com/plugins/flash/ jQuery flash plug-in](http://trac.symfony-project.com/trac/wiki/sfUJSPlugin)

  *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 [sfUJSPlugin helper installation page](http://trac.symfony-project.com/trac/wiki/sfUJSPlugin)
  
  * Alternatively, if you don&#039;t have PEAR installed, you can download the latest package attached to this plugin&#039;s wiki page and extract it under your project&#039;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. 
    
    &lt;?php use_helper(&#039;UFO&#039;) ?&gt;
    

### Adding Flash movies unobtrusively

The following template code:
    
    &lt;div id=&quot;foobar&quot;&gt;
      I&#039;m here !
    &lt;/div&gt;
    &lt;?php UFO(&#039;#foobar&#039;, &#039;src=swf/example.swf&#039;)&quot;) ?&gt;
    

Renders as follows:
    
    &lt;head&gt;
      &lt;script type=&quot;text/javascript&quot; src=&quot;/UJS/script/key/bc8b3812f3d7a20f7ed7c1ab25ec449a.php&quot;&gt;&lt;/script&gt;
      &lt;link rel=&quot;stylesheet&quot; type=&quot;text/css&quot; media=&quot;screen&quot; href=&quot;/sfUFOPlugin/css/UFO-screen.css&quot; /&gt;
      &lt;link rel=&quot;stylesheet&quot; type=&quot;text/css&quot; media=&quot;print&quot; href=&quot;/sfUFOPlugin/css/UFO-print.css&quot; /&gt;
    &lt;/head&gt;
    &lt;body&gt;
      &lt;div id=&quot;foobar&quot;&gt;
        I&#039;m here !
      &lt;/div&gt;
    &lt;/body&gt;
    

The attached script will contain:
    
    $().ready(function(){
        $(&#039;#foobar&#039;).flash({ src: &#039;swf/example.swf&#039;});
     })
    

The resulting DOM after execution is:
    
    &lt;div id=&quot;foobar&quot; class=&quot;flash-replaced&quot;&gt;
      &lt;embed width=&quot;320&quot; height=&quot;240&quot; type=&quot;application/x-shockwave-flash&quot; src=&quot;/./swf/example.swf&quot; pluginspage=&quot;http://www.adobe.com/go/getflashplayer&quot; flashvars=&quot;&quot;/&gt;
      &lt;div class=&quot;alt&quot;&gt; I&#039;m here ! &lt;/div&gt;
    &lt;/div&gt;
    

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: &#039;bar&#039; }`

  * `bgcolor`: Background color of the embedded object. Ex: `#cccccc`

  * `version`: Minimal version of flash player required to play the movie. Ex: &#039;6.0.65&#039;

  * `update`: If true (default), users without a compatible flash player will be prompted to update it

  * `expressInstall`: If true, an update will use [Express Install](http://www.adobe.com/cfusion/knowledgebase/index.cfm?id=6a253b75)
  
Any other usual tag attribute (such as `class`, `id`, etc.) is also accepted.

So a complex example of Flash insertion could be:

    
    &lt;div id=&quot;foobar&quot;&gt;
      I&#039;m here !
    &lt;/div&gt;
    &lt;?php UFO(&#039;#foobar&#039;, array(
      &#039;src&#039;            =&gt; &#039;swf/example.swf&#039;,
      &#039;width&#039;          =&gt; 150,
      &#039;height&#039;         =&gt; 250,
      &#039;flashvars&#039;      =&gt; &quot;{ foo: &#039;bar&#039; }&quot;,
      &#039;version&#039;        =&gt; &#039;6.0.65&#039;,
      &#039;expressInstall&#039; =&gt; true
      )
    ) ?&gt;
    

### Adding a Flash movie without DOM reference

The first example presented above uses an existing `&lt;div&gt;` tag to locate the place to put the Flash movie. If you don&#039;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.

    
    &lt;?php UFO_write(&#039;swf/example.swf&#039;, &#039;width=10 height=10 update=false&#039;) ?&gt;
    

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:

    
    &lt;a class=&quot;swf&quot; href=&quot;/swf/example.swf&quot;&gt;click me to see a flash movie&lt;/a&gt;
    &lt;?php UFO_flashify(&#039;.swf&#039;) ?&gt;
    

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:

    
    &lt;span class=&quot;flash-replaced&quot;&gt;
       &lt;embed width=&quot;320&quot; height=&quot;240&quot; type=&quot;application/x-shockwave-flash&quot; src=&quot;/swf/example.swf&quot; pluginspage=&quot;http://www.adobe.com/go/getflashplayer&quot; flashvars=&quot;&quot;/&gt;
       &lt;a class=&quot;swf alt&quot; href=&quot;/swf/example.swf&quot;&gt;click me to see a flash movie&lt;/a&gt;
    &lt;/span&gt;
    

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&#039;s limitations and render a text heading with a special font. See [Mike Davidson&#039;s website](http://www.mikeindustries.com/sifr/) 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&#039;s site for details). You can also specify a few style elements of the text. Here is an example:

    
    &lt;p class=&quot;sIFR&quot;&gt;Hi &lt;a href=&quot;toto.html&quot;&gt;mates&lt;/a&gt;!&lt;/p&gt;
    &lt;?php UFO_style(&#039;.sIFR&#039;, &#039;swf/itc_century.swf&#039;, &quot;linkcolor: &#039;#0000FF&#039;&quot;) ?&gt;
    

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:

    
    &lt;p class=&quot;sIFR&quot;&gt;Hi &lt;a href=&quot;toto.html&quot;&gt;mates&lt;/a&gt;!&lt;/p&gt;
    &lt;?php UFO_style_block() ?&gt;
    .sFIR {
     font: &#039;swf/tradegothic.swf&#039;;
     textcolor: &#039;#666666&#039;;
     linkcolor: #0000FF;
     hovercolor: &#039;#5500FF&#039;;
    }
    &lt;?php UFO_style_end_block() ?&gt;
    

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&#039;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: &#039;swf/tradegothic.swf&#039;;
     textcolor: #666666;
     linkcolor: #0000FF;
     hovercolor: #5500FF;
    }
    

Then, in the template:

    
    &lt;p class=&quot;sIFR&quot;&gt;Hi &lt;a href=&quot;toto.html&quot;&gt;mates&lt;/a&gt;!&lt;/p&gt;
    &lt;?php UFO_use_stylesheet(&#039;css/flash.css&#039;) ?&gt;
    

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