HOWTO: Write a plugin for your Flash Player

The goal of SWF Tools is to allow you to integrate any required Flash Player without worrying about the details of JavaScript Flash-replacement and other such details.

In the SWF Tools download, there are two very plain Flash Players, one for playing MP3 music files, and one for playing FLV format movies. The plug-in module that allows SWF Tools to use these players is in the file genericplayers.module.

This Generic Players module is structured like a stand-alone module, all it needs is a genericplayers.info file. So in the steps below, you would replace all occurances of "genericplayers" with your own module name.

Inform SWF Tools of your plugin

To begin with, you need some code to tell SWF Tools about your plugin. This enables SWF Tools to offer your Flash player as an optional default in the File Handling page.

/**
 * Implementation of swftools_methods hook
 * Report methods back to SWF Tools
 */

function genericplayers_swftools_methods() {

  $methods = array();
  $mp3_player = array (
    'name'        => 'generic_mp3', // This is a unique name of your choosing
    'module'      => 'genericplayers', // Simple the name of your module
    'shared_file' => 'generic/generic_mp3.swf',  // Tell SWF Tools where to find your player
    'title'       => t('Generic MP3 Player'), // Title for the admin pages.
  );
  // SWFTOOLS_MP3_DISPLAY is one of the "display methods"
  // constants defined at the top of swftools.module.
  $methods[SWFTOOLS_MP3_DISPLAY]['generic_mp3'] = $mp3_player;

  $flv_player = array (
    'name'        => 'generic_flv',
    'module'      => 'genericplayers',
    'shared_file' => 'generic/generic_flv.swf',
    'title'       => t('Generic FLV Player'),
  );
  // SWFTOOLS_FLV_DISPLAY is one of the "display methods"
  // constants defined at the top of swftools.module.
  $methods[SWFTOOLS_FLV_DISPLAY]['generic_mp3'] = $flv_player;
  return $methods;
}

Request a configuration page

Using the normal hook_menu, you can slot your page under the SWF Tools configuration area. Access control is set on the /swf part of the menu, so you don't need to define access control if you don't want to. You also don't need to define a callback, as SWF Tools manages this.

/**
 * Implementation of hook_menu(). Items such as access control is set by swftools automatically
 */
function genericplayers_menu($may_cache) {
  $items = array();
  if ($may_cache) {
    $items[] = array('path' => 'admin/swf/generic',
      'title' => t('Generic Players'),
      'description' => t('Basic Flash players that ship with SWF Tools'),
      );
  }
  return $items;
}

Define your configuration settings

Flash Players usually have options that you can pass into them. These are called "FlashVars". These FlashVars then become variables within the ActionScript of the Flash Player. On the settings page we can allow the site admin to define the default settings. In this case "autostart" is used by the Flash Player to determine whether the music/movie/animation should start automatically.

/**
 * Implementation of swftools_admin_hook_form. Return the system settings page.
 */
function swftools_admin_generic_form() {

  $form = array();
  $methods = swftools_methods_available(SWFTOOLS_EMBED_METHOD);
  $form['generic_mp3_autostart'] = array(
    '#type' => 'checkbox',
    '#default_value' => variable_get('generic_mp3_autostart', FALSE),
    '#title' => t('Autostart MP3'),
    '#description' => t('Automatically start playing the MP3 file.'),
  );
  $form['generic_flv_autostart'] = array(
    '#type' => 'checkbox',
    '#default_value' => variable_get('generic_flv_autostart', FALSE),
    '#title' => t('Autostart FLV'),
    '#description' => t('Automatically start playing the FLV file.'),
  );
  return system_settings_form($form);
}

Overriding FlashVars in a unique way

In this part of the code, SWF Tools has been asked to display some Flash. It has processed the general defaults, and overridden these defaults with settings passed into the swf() call.

At this point, your plugin module has the option of massaging the settings to suit your Flash Player. In this case, as an example, SWF Tools didn't know about the autostart default settings. So the plugin gets the last chance to modify the FlashVars and apply these defaults. You can do a lot of different things with the FlashVars in this hook, so this is just a simple example. Sometimes you may not need to use this hook.

/**
 * Implementation of swftools_flashvars hook.
 */
function genericplayers_swftools_flashvars($action, &$methods, &$vars) {
  switch ($action) {
    case SWFTOOLS_MP3_DISPLAY:
      $vars->flashvars['autostart'] = variable_get('generic_mp3_autostart', FALSE) ? 'true' : 'false';
      break;
    case SWFTOOLS_FLV_DISPLAY:
      $vars->flashvars['autostart'] = variable_get('generic_flv_autostart', FALSE) ? 'true' : 'false';
      break;
  }
  // Must return the flashvars component.
  return $vars->flashvars;
}

Now, you just need to add a .info file and your module is ready for action.

What we haven't covered here

There is also the ability to output a playlist in XML. This feature is not covered here (yet). Please see wijering.module for a working example if you are keen.