function swf in SWF Tools 6.3

Same name and namespace in other branches

Processes a file, or an array of files, and returns the relevant mark-up to render a Flash based player.

Parameters

mixed $content: The content 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. If an array is passed then the array will be converted to a playlist automatically. If it is a string and it is a complete url then SWF Tools will pass it along unaltered. If the string is a partial path then it will either be resolved to the local file system, or to a remote host, depending whether the swftools_media_url variable is set.

array $options: An associative array of optional paramters and settings containing:

params: An associative array of <param> variables to set.eg. array('bgcolor'=>'FF00FF'), or to set the height and width: array('width'=>'200', 'height'=>'120'). 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.
methods: An array of data to explicitly declare an action, player or embed method and over-ride the default value that SWF Tools will otherwise use. Contains the following optional keys:
- action: (string) A specific action to be taken, e.g. image_list
- player: (string) A specific player to be used, e.g. flowplayer3
- embed: (string) A specific embedding method, e.g. swftools_direct

Return value

string A markup string.

File

./swftools.module, line 263: The primary component of SWF Tools that enables comprehensive media handling.

Code

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

  //  $time_start = microtime(true);
  // TODO: We should put SWF Tools own settings somewhere safe in the othervars array
  // If someone passes a variable from the input filter it could collide.
  // Maybe put them under #swftools (since the data are properties of swftools?)
  // A finished item has player, profile, cid, id, file_url, src_path, src
  // Initialise any $options array elements that weren't passed by the caller
  swftools_initialise_options($options);

  // Initialise othervars with some defaults
  $options['othervars'] += array(
    'profile' => '',
    'return' => SWFTOOLS_RETURN_MARKUP,
    'playlist_data' => '',
    'image' => '',
    'stream' => FALSE,
    'xml' => '',
  );

  // Initialise methods with some defaults
  $options['methods'] += array(
    'action' => '',
    'player' => '',
    'embed' => '',
  );

  // Initialise params with some defaults
  $options['params'] += array(
    'base' => swftools_get_base(),
  );

  // See if we can get this item from the SWF Tools cache
  if (($ret = swftools_get_from_cache($content, $options)) && variable_get('swftools_cache', CACHE_NORMAL)) {

    //      $time_end = microtime(true);
    //      $time = $time_end - $time_start;
    //      dsm('Used cache in ' . $time);
    if ($ret->headers && ($script_location = variable_get('swftools_javascript_location', SWFTOOLS_JAVASCRIPT_INLINE))) {
      drupal_add_js($ret->headers, 'inline', $script_location == SWFTOOLS_JAVASCRIPT_HEADER ? 'header' : 'footer');
    }
    return $options['othervars']['return'] == SWFTOOLS_RETURN_CID ? $options['othervars']['cid'] : $ret->data['html'];
  }

  // Ensure id is unique, or assign an id if one isn't set
  $options['othervars']['id'] = swftools_get_id($options['othervars']['id']);

  // If swf() was called with an array of files, make a playlist
  if (is_array($content)) {

    // Turn the array in to a playlist and attach it to othervars
    swftools_prepare_playlist($content, $options);
  }

  // ACTION
  // Work out what SWF Tools should do with this file (e.g. video, audio)
  // If an explicit action wasn't set then try to determine an appropriate one using the filename
  $options['methods']['action'] = $options['methods']['action'] ? swftools_fix_old_action_names($options['methods']['action']) : swftools_get_action($content);

  // RESOLVE PLAYER AND EMBEDDING
  // 'resolved' refers to the fact that these are the methods we now intend to use, not /all/ methods available.
  // PLAYER
  // Work out what player SWF Tools will need to use for this action
  // If an explicit player wasn't set then find out what player is configured for the current action
  $options['methods']['player'] = $options['methods']['player'] ? swftools_fix_old_player_names($options['methods']['player']) : swftools_get_player($options['methods']['action'], $options['othervars']['profile']);

  // If there is no player assigned we don't what to do with this action
  if (!$options['methods']['player']) {

    // Get the descriptions that go with the actions
    $actions = swftools_get_actions();

    // If we have a matching description for the specified action, create a meaningful message
    if (isset($actions[$options['methods']['action']]['#description'])) {

      // If we also have a meaningful profile name use that too
      if ($options['othervars']['profile']) {
        if (function_exists('swftools_profiles_get_profile') && ($profile = swftools_profiles_get_profile($options['othervars']['profile']))) {
          $profile = $profile['name'];
        }
        else {
          $profile = $options['othervars']['profile'];
        }
        $profile = t('@profile profile', array(
          '@profile' => $profile,
        ));
      }
      else {
        $profile = 'SWF Tools';
      }

      // And output a message
      swftools_set_error('swftools', 'No player is configured for %action. Check the %profile file handling settings.', array(
        '%action' => $actions[$options['methods']['action']]['#description'],
        '%profile' => $profile,
      ), WATCHDOG_WARNING);
    }
    else {
      swftools_set_error('swftools', 'No modules have registered the action %action. Check any required supporting modules are enabled.', array(
        '%action' => $options['methods']['action'],
      ), WATCHDOG_WARNING);
    }

    // We couldn't find a player for this content, so fallback to the alternate markup and return
    return theme('swftools_html_alt', $options);
  }

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

  // Check that the action / player combination is valid (it should appear in the array of all methods)
  if (isset($all_methods[$options['methods']['action']][$options['methods']['player']])) {

    // The combination was found, place player information in to resolved_methods
    $options['resolved_methods']['player'] = $all_methods[$options['methods']['action']][$options['methods']['player']];
  }
  else {

    // Get the descriptions that go with the actions
    $actions = swftools_get_actions();

    // Set an error
    swftools_set_error('swftools', 'The combination of %player with %action is not valid. Check that the player is available and that it supports the requested action.', array(
      '%player' => $options['methods']['player'],
      '%action' => $options['methods']['action'],
    ), WATCHDOG_WARNING);

    // Return alternate markup
    return theme('swftools_html_alt', $options);
  }

  // EMBED
  // Work out what embedding method SWF Tools should use for this content
  // If an explicit embed method was not set then assign one now
  $options['methods']['embed'] = $options['methods']['embed'] ? $options['methods']['embed'] : variable_get('swftools_embed_method', 'swftools_direct');

  // Place the embedding method information in to resolved_methods
  $options['resolved_methods']['embed'] = $all_methods['swftools_embed_method'][$options['methods']['embed']];

  // PARAMS
  // If $options['params'] is not an array then assume it is width x height as a string
  // TODO: This is an ugly legacy - can we retire it?
  if (!is_array($options['params'])) {

    // Explode string
    $dimensions = explode('x', $options['params']);

    // If we got two pieces assume success
    if (count($dimensions) == 2) {
      $options['params'] = array(
        'width' => $dimensions[0],
        'height' => $dimensions[1],
      );
    }
  }

  // FLASHVARS
  // If the flashvars were passed as a string then turn it in to an array
  // Does the filter pass the flashvars as a string? Could we explode the string in
  // their, and then we know we only get an array?
  if (!is_array($options['flashvars'])) {
    parse_str($options['flashvars'], $options['flashvars']);
  }

  // XML PLAYLIST
  // Determine if we are trying to generate a playlist that needs xml output, and create it if required
  // If $options['othervars']['playlist_data'] is set then we are processing a playlist
  if ($options['othervars']['playlist_data']) {

    // Try to generate an xml playlist and get the path to the xml file. $content will be an empty string if we don't need xml.
    $content = swftools_generate_playlist($options);
  }

  // FILE
  // Make sure that the file path in $content is valid, and as necessary try to
  // expand it to a relative url on the local file system, or point to the remote media directory
  // First we assume that we can just set $file_url to the value in $content
  $file_url = $content;

  // If we are not streaming this file, and $content isn't empty, then we might need to process it to get a proper path
  if (!$options['othervars']['stream'] && $content) {

    // Process to get a url (in src) and expand the path (in src_path) if necessary
    $source = swftools_get_url_and_path($content);

    // If FALSE was returned then the file doesn't exist so return $html_alt
    if (!$source) {
      return theme('swftools_html_alt', $options);
    }

    // $file might need to be changed to reflect a path on the local file system
    // This happens when the user just supplied a filename and files are being sourced locally
    // Put $content = $source['filepath'] in case that happened
    $content = $source['filepath'];

    // In all cases $file_url is now an absolute, or relative, url to the file that we can use
    $file_url = $source['fileurl'];
  }

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

  // Depending if we are outputting a swf or using a player we need to attach $file in different places
  switch ($options['methods']['player']) {

    // Embedding an swf directly - no player
    case 'swf':
      $options['othervars']['filepath'] = $content;
      $options['othervars']['fileurl'] = $file_url;
      break;

    // Embedding with a player
    default:
      if ($options['resolved_methods']['player']['library']) {
        $options['othervars']['filepath'] = $options['resolved_methods']['player']['library'];
        $options['othervars']['fileurl'] = base_path() . $options['othervars']['filepath'];
      }
  }

  // Merge default and user defined parameters, with user defined ones taking precedence
  $options['params'] = array_merge(_swftools_params(), $options['params']);

  // If player requires a higher version of flash than the current default then over-ride the default
  if (version_compare($options['resolved_methods']['player']['version'], $options['params']['version'], '>')) {
    $options['params']['version'] = $options['resolved_methods']['player']['version'];
  }

  /**
   * We used to call hook_flashvars, using the module name, but we are starting to do a lot
   * more than just flashvars. So we will borrow from the theme system and implement
   * hook_swftools_preprocess_[playername]. Normally you would just expect the module that
   * defines the player to handle its own players, but in theory anyone can hook in at this
   * point and manipulate the entire data array just before we output it.
   */
  $preprocess = 'swftools_preprocess_' . $options['resolved_methods']['player']['name'];
  foreach (module_implements($preprocess) as $module) {
    $function = $module . '_' . $preprocess;
    $function($options);
  }

  // TODO: Can we deprecate this - we are accommodating the ability to specify width x height in a string on params.
  // We used to set height and width on $vars->params, but they're not actually params and they were
  // being unset in individual embedding functions. So we'll move them to $vars->othervars.
  // We will continue to let users pass the data on $vars->params so as not to break existing code.
  if (!isset($options['othervars']['height']) && !empty($options['params']['height'])) {
    $options['othervars']['height'] = $options['params']['height'];
    unset($options['params']['height']);
  }
  if (!isset($options['othervars']['width']) && !empty($options['params']['width'])) {
    $options['othervars']['width'] = $options['params']['width'];
    unset($options['params']['width']);
  }

  // Try and make sure we have a size set on this content
  swftools_set_size($options);

  // Change html_alt to include the first image when handling an image list
  // TODO: Should this be an option that can be disabled?
  if ($options['methods']['action'] == 'image_list') {
    swftools_image_html_alt($options);
  }

  // See if anyone wants to alter anything just before it is output
  drupal_alter('swftools', $options);

  // Call theme function
  $output = theme('swftools_embed', $options);

  // See if the embed placed a script for us to cache
  $script = ($data = drupal_get_js($options['othervars']['id'])) ? str_replace(array(
    "<script type=\"text/javascript\">\n<!--//--><![CDATA[//><!--\n",
    "\n//--><!]]>\n</script>\n",
  ), '', $data) : '';

  // Cache the result using an array to store the markup and any associated xml
  cache_set($options['othervars']['cid'], array(
    'html' => $output,
    'xml' => $options['othervars']['xml'],
  ), 'cache_swftools', CACHE_TEMPORARY, $script);

  // If we want just the cid then return that
  if ($options['othervars']['return'] == SWFTOOLS_RETURN_CID) {
    return $options['othervars']['cid'];
  }

  // Return the markup
  return $output;
}

You are here

function swf in SWF Tools 6.3

Parameters

Return value

Related topics

File

Code

API Navigation