You are here

Home » API reference » SWF Tools 6 » swftools.module

function swf in SWF Tools 6

Same name and namespace in other branches
  1. 5 swftools.module \swf()
  2. 6.3 swftools.module \swf()
  3. 6.2 swftools.module \swf()

Return output, which might be embed markup, or pre-flash markup that includes the appropriate jQuery added to the <head>

Parameters

$file: The file to be played. If it is a SWF file it will usually be embedded directly. Use a full URL, a path relative to webroot, or a path relative to the configured files directory.

$params: An associative array of <param> variables to set.eg. array('bgcolor'=>'FF00FF') To set height and width: array('width'=>'200', 'height'=>'120'). However, as a convenient alternative for the common requirement of just height and width you can also pass a text string like '200x100'. If you pass nothing, and the file to play is a .swf, swftools will try and establish a natural width and height from the actual .swf file that you've passed into $file.

$flashvars: An associative array of flashvar variables to set. eg. array('playlist'=>'files/my_playlist.xml')

$othervars: An associative array of variables that might be required by the $player or $embed technique. These values are not output as params or flashvars.

$method: Explicitly declare an action, player or action by passing an array of the form: array('action'=>'dosomething','player'=>'withsomething','embed'=>'withthisjavascript'). These usually default to the administration settings and also you will usually use a CONSTANT which will be documented further at a later stage.

3 calls to swf()
swf_list in ./swftools.module
Output a playlist via a flash file. Note that $playlist_data has a specific format that will be documented later.
_swftools_filter_process_text in ./swftools.module
_swftools_test_content in ./swftools.admin.status.inc
4 string references to 'swf'
swfobject2_swftools_embed in swfobject2/swfobject2.module
Implementation of swftools_embed hook Returns the markup for the page, plus set necessary javascript.
swftools_get_action in ./swftools.module
Identify the best action based on the file type that is passed
_simpleviewer_vars in simpleviewer/simpleviewer.module
These are the default options and flashvars.
_swftools_filter_process_text in ./swftools.module

File

./swftools.module, line 180

Code

function swf($file, $options = array()) {

  // Merge in defaults
  $options += array(
    'params' => SWFDEFAULT,
    'flashvars' => SWFDEFAULT,
    'othervars' => SWFDEFAULT,
    'methods' => SWFDEFAULT,
  );

  // For now turn array back in to original strings to avoid re-writing rest of code below
  // Can tidy this up later!
  $params = $options['params'];
  $flashvars = $options['flashvars'];
  $othervars = $options['othervars'];
  $methods = $options['methods'];

  // Get all the actions, tools and embedding options available to us.
  $all_methods = swftools_methods_available();

  // ACTION
  // Explicit action on the $methods parameter?
  $action = isset($methods['action']) ? $methods['action'] : FALSE;
  if (!$action) {

    // Still no action?
    $action = swftools_get_action($file);
  }

  // HTML ALTERNATIVE
  // Get the html which will be used in case flash cannot be displayed.
  $html_alt = $othervars['html_alt'] ? $othervars['html_alt'] : variable_get('swftools_html_alt', SWFTOOLS_DEFAULT_HTML_ALT);

  // 'resolved' refers to the fact that these are the methods we
  // intend to use, not /all/ methods available.
  $resolved_methods = new stdClass();

  // PLAYER
  // Explicit player on the $methods parameter?
  $player = isset($methods['player']) ? $methods['player'] : FALSE;
  if (!$player) {

    // Still no player?
    $player = swftools_get_player($action);
    if (!$player) {
      $descriptions = array(
        SWFTOOLS_IMAGE_DISPLAY_LIST => 'a series of images',
        SWFTOOLS_FLV_DISPLAY => 'a single flv file',
        SWFTOOLS_FLV_DISPLAY_LIST => 'a series of flv files',
        SWFTOOLS_MP3_DISPLAY => 'a single mp3 file',
        SWFTOOLS_MP3_DISPLAY_LIST => 'a series of mp3 files',
        SWFTOOLS_MEDIA_DISPLAY_LIST => 'a series mixed media files',
      );
      if (isset($descriptions[$action])) {
        drupal_set_message(t('No player is configured to play ' . $descriptions[$action] . '. Check the SWF Tools file handling settings on the configuration page.'), 'error');
      }
      else {
        drupal_set_message(t('No player is configured for the action %action. Check the SWF Tools file handling settings on the configuration page.', array(
          '%action' => $action,
        )), 'error');
      }

      // We pass back the alternative html to be displayed as is.
      return $html_alt;
    }
  }

  // Assign the player info.
  if (isset($all_methods[$action][$player])) {
    $resolved_methods->player = $all_methods[$action][$player];
  }
  else {
    if ($action == SWFTOOLS_SWF_DISPLAY_DIRECT) {

      // We seem to have a custom player. We make the method custom and assign the player.
      $resolved_methods->player = $all_methods[$action][SWFTOOLS_CUSTOM];
      $resolved_methods->player['shared_file'] = $player;

      // Don't check existence of player file.
    }
    else {

      // All else fails ...
      drupal_set_message(t('Could not find the %player file for embedding.', array(
        '%player' => $player,
      )), 'error', FALSE);
      return $html_alt;
    }
  }

  // EMBED
  // Explicit embed strategy on the $methods parameter?
  $embed = isset($methods['embed']) ? $methods['embed'] : FALSE;
  if (!$embed) {

    // Still not sure?
    $embed = variable_get(SWFTOOLS_EMBED_METHOD, SWFTOOLS_NOJAVASCRIPT);
  }

  // Assign the embed info.
  $resolved_methods->embed = $all_methods[SWFTOOLS_EMBED_METHOD][$embed];

  // Put all the variables on a simple object to make internal function calls simpler.
  $vars = new stdClass();

  // OTHERVARS
  $vars->othervars = is_array($othervars) ? $othervars : array();

  // PARAMS
  // params could be an associative array, or in 'WIDTHxHEIGHT' format.
  if ($params) {
    if (is_array($params)) {
      $vars->params = $params;
    }
    else {
      $dimensions = explode('x', $params);
      if (count($dimensions) == 2) {
        $vars->params = array(
          'width' => $dimensions[0],
          'height' => $dimensions[1],
        );
      }
    }
  }
  else {
    $vars->params = array();
  }

  // FLASHVARS
  // flashvars could be an associative array, or in 'a=1&b=2' format.
  if ($flashvars) {
    if (is_array($flashvars)) {
      $vars->flashvars = $flashvars;
    }
    else {

      // Parse the string as if in 'a=1&b=2' format.
      parse_str($flashvars, $vars->flashvars);
    }
  }
  else {
    $vars->flashvars = array();
  }

  // BASE
  // Determine a reasonable 'base' directory, if a remote url is set, use that
  // If file is local, set to the file directory
  $base = !empty($vars->params['base']) ? $vars->params['base'] : '';
  if (!$base || !valid_url($base)) {

    // swftools_get_media_url() returns remote path if it is set,
    $base = swftools_get_media_url('', FALSE);
  }
  $vars->params['base'] = $base;

  // PLAYLIST
  // Are we trying to generate a playlist?
  if (isset($othervars['playlist_data'])) {

    // Flag that a playlist is being generated
    $playlist = TRUE;

    // Generate a playlist in the files directory
    $file = swftools_generate_playlist($othervars['playlist_data'], $playlist_name, $resolved_methods, $vars, FALSE);

    // If a file wasn't generated return an error
    if (!$file) {
      drupal_set_message(t('Unable to create playlist.'), 'error');
      return $html_alt;
    }
  }
  $nocache = '';
  if (variable_get('swftools_playlist_caching', 'here') == 'always') {

    // Not currently working. Sometimes you may see xml caching.
    $nocache = '?nc=' . time();
  }

  // FILE
  // Process the file if not already a full url
  if (!valid_url($file, TRUE)) {

    // If we have a file and not a playlist
    if (empty($playlist)) {

      // Then if files are local ensure it is a properly formatted path
      if (swftools_get_media_path()) {
        $file = file_create_path($file);
      }
    }

    // Try to turn $file in to a complete url
    $file_url = swftools_get_media_url($file);

    // If $file_url was not generated then file doesn't exist so return $html_alt
    if (!$file_url) {
      return $html_alt;
    }

    // Append $nocache string to complete the url

    //$file_url = $file_url . $nocache;
    $file_url = $file_url;
  }
  else {

    // We already had a url, so set $file_url to $file
    $file_url = $file;
  }

  // Attach file_url to othervars so player modules have access if required
  $vars->othervars['file_url'] = $file_url;

  // Determine the "src" attribute of the embed (also applies to the 'movie' attribute).
  // Usually this is the Flash Player, but it can also be a swf file, or a custom file
  // passed on othervars['shared_file'].
  switch ($player) {
    case SWFTOOLS_SWF:

      // The original file is the src file.
      $vars->params['src_path'] = $file;
      $vars->params['src'] = $file_url;
      break;
    case SWFTOOLS_CUSTOM:
      $vars->params['src_path'] = $resolved_methods->player['shared_file'];

      // May need the local path for dimensions.
      $vars->params['src'] = swftools_get_media_url($resolved_methods->player['shared_file']);
      break;
    default:
      $vars->params['src_path'] = swftools_get_player_path() . '/' . $resolved_methods->player['shared_file'];
      $vars->params['src'] = $GLOBALS['base_url'] . '/' . swftools_get_player_path() . '/' . $resolved_methods->player['shared_file'];
  }

  // Merge default and user defined "params".
  $vars->params = array_merge(_swftools_params(), $vars->params);

  // Ask the module implementing the player what flashvars are required, pass
  // all existing values by reference to allow optional override at the player.module level.
  $player_flashvars = call_user_func_array($resolved_methods->player['module'] . '_swftools_flashvars', array(
    $action,
    &$resolved_methods,
    &$vars,
  ));
  $vars->flashvars = array_merge($vars->flashvars, $player_flashvars);

  // Apply the values as requested by the player.module (if applicable).
  if (isset($resolved_methods->player['file'])) {
    $vars->flashvars[$resolved_methods->player['file']] = $file_url;
  }
  if (isset($resolved_methods->player['version'])) {
    $vars->params['version'] = $resolved_methods->player['version'];
  }

  // Not a pretty piece of code, but should be ok for the moment. We are
  // purposefully passing the width and height
  // if we have them. Unsure if this will cause problems with some players.
  // It's an ugly piece of code, but will remain in this form until a clearer
  // solution arises.
  //
  // It may be that, in hook_swftools_methods, the flash player indicates that
  // it *want* certain values copied b/t params and flashvars.
  //
  if (empty($vars->flashvars['width']) && empty($vars->flashvars['height'])) {
    if (!empty($vars->params['width']) && !empty($vars->params['height'])) {
      $vars->flashvars['width'] = $vars->params['width'];
      $vars->flashvars['height'] = $vars->params['height'];
    }
  }
  if (empty($vars->params['width']) && empty($vars->params['height'])) {
    if (!empty($vars->flashvars['width']) && !empty($vars->flashvars['height'])) {
      $vars->params['width'] = $vars->flashvars['width'];
      $vars->params['height'] = $vars->flashvars['height'];
    }
  }

  // If still empty, we try and get them from the file to be embedded.
  if (empty($vars->params['height']) && empty($vars->params['width'])) {
    $info = swftools_get_info($vars->params['src_path']);
    if ($info) {
      $vars->params['height'] = $info['height'];
      $vars->params['width'] = $info['width'];
    }
  }

  // Build a string out of the flashvars array.
  $vars->params['flashvars'] = _swftools_get_flashvars_string($vars->flashvars);

  // Call the embedding code to get the html and set the javascript if necessary.
  $output = module_invoke($resolved_methods->embed['module'], 'swftools_embed', $action, $resolved_methods, $vars, $html_alt);

  // The $html code is already built, but allow it to be changed.
  // TODO $preview is undefined, what is it??
  $preview = NULL;
  return theme('swftools_embed', $output, $action, $resolved_methods, $vars, $preview);
}