SWF Embed

SWF Embed is a simple developer-centered module for working with Macromedia Flash-based content. It provides the necessary hooks for adding Flash content on the server-side, as well as the necessary JavaScript and jQuery for working with the Flash on the client-side.

This handbook describes how the SWF Embed module can be used to add Flash files to your site.

Overview of the Module

The SWF Embed module has two parts: The server-side module and the client-side JavaScript libraries. Many tasks will require only light server-side programming, but more sophisticated applications may use the JavaScript libraries directly, too.

The swfembed.module File

The swfembed.module file houses the server-side code. Practically speaking, there are only two items in this file that you will need to know about:

1. The SWFObject class.
2. The swfembed_embed theme implementation.

The first describes the Flash file and its configuration. The second takes that description and renders it into the appropriate JSON data structure for transmission to the client.

The JavaScript Libraries

There are two JavaScript libraries included with the module:

1. jquery.swfembed.js: A jQuery plugin that provides Flash support.
2. behavior.swfembed.js: A Drupal behavior that takes the JSON data and creates a Flash object.

Most of the time, no specific JavaScript coding is necessary for this library to work.

With a basic intro behind us, let's look at an example.

Using the SWF Embed Module

Let's assume that we have a module called my module. Inside of this module directory is a file called my.module. That is the file we will be working with.

In that file, we will add a simple function that declares a new Flash file and sends it to the client. Here is the relevant PHP code to do this:

/**
 * Implements hook_menu().
 */
function my_menu() {
  $items = array();

  $items['swfembed'] = array(
    'title' => t('Title'),
    'description' => t('Description'),
    'page callback' => 'my_test',
    'page arguments' => array(),
    'access arguments' => array('access content'),
    'type' => MENU_NORMAL_ITEM,
  );
  return $items;
}

/**
 * A simple function that loads an SWF file and sends it as a page to the client.
 * 
 * @return
 *   Returns HTML as a string.
 */
function my_test() {
  // Creates a new object wrapping the given file (path)
  $swf = new SWFObject('/sites/default/modules/flashy/flashy/videoPlayer.swf');

  // With that object, first we add a param to allow full screen.
  $swf->param('allowFullScreen', 'true')
    // Add another param to set the type to movie.
    ->param('type','movie')

    // Set some flash variables, beginning with the aspect ratio...
    ->flashVar('maintainAspectRatio', 'true')
    // Set volume variable
    ->flashVar('volume', 50)
    // Set video source
    ->flashVar("video", "http://example.com/sites/default/modules/flashy/flashy/a.flv")

    // Set the height and width of the player.
    ->height(342)
    ->width(510)

    // Set a message for non-Flash capable clients.
    ->noFlash('Install flash.')

   // Declare the minimal Flash version required for this object.
    ->minimumVersion('9.0.28');

  // Theme the object and return that to the client.
  return theme('swfembed_embed', array('swf' => $swf));
}

NOTE: For Drupal 6 the signature of the theme function is different. In D6 you need to call the theme function like this:

return theme('swfembed_embed', $swf);

The example above contains two functions. The first is a standard implementation of hook_menu(), which we will not cover.

The second function is the main point of interest. This my_test() function declares a new flash object and formats it for display.

The first step in creating a new flash media file is to create a new instance of the SWFObject class:

$swf = new SWFObject('path/to/flash.swf');

This simply creates a new SWF Object instance that points to the specified file.

Once you have this object, you can begin configuring it. Since the object supports chainable method invocation (sometimes called a Fluent Interface), you can call multiple functions on the same object by chaining them together:

$swf->height(10)->width(20);

In the example above, we break this up with newlines so that it is easier to read (and comment).

The above example shows all of the important mutators (setter methods) that are available for the SWFObject, save one: You can also use $swf->expressRedirectURL($url) to set an express redirect URL, should you have one. This will make it easier for clients to install the requisite Flash version.

This is all there is to using the SWF Embed module. There is, however, one potentially confusing aspect to this module. let's take a look at the param() and flashVar() methods.

The param() and flashVar() Methods

There are two important methods that might, at first glance, seem confusingly similar. These are $swf->param() and $swf->flashVar().

The first, $swf->param(), is used to set parameter elements inside of an object or embed HTML tag. The standard Flash parameters should all be passed in using $swf->param().

Using this method will result in param elements that look like this:

<param name="allowFullScreen" value="true"/>

The second method, $swf->flashVar(), is used to set variables inside of the flashvars param. Using it will result in HTML elements like this:

<param name="flashvars" value="maintainAspectRatio=true&volume=50&video=http://example.com/sites/default/modules/flashy/flashy/a.flv"/>

Note that all flash variables are concatenated together and appropriately encoded.

Where to Go from Here

Once you start testing the waters by writing your own code, you may find that you need more information. The example here (and another similar one) is included in the swfembed.module file itself.

You may also want to look at the Flashy module (http://drupal.org/project/flashy), which uses SWF Embed to add a Flash movie player.

If these fail, you may want to check out the issue queue at http://drupal.org/project/swfembed. Others may have had (and solved) similar issues.

Want documentation on just the jQuery plugin (which you can easily use by itself, inside or outside of Drupal)? There is a brief introduction available at TechnoSophos.com