function swf in SWF Tools 6.2

Same name and namespace in other branches

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. If an array is passed then the array will be converted to a playlist automatically. If the file string 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.

$options=>$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.

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

$options=>$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.

$options=>$methods: 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.

5 calls to swf()

swf_list in ./swftools.module: Take an array of play list data and options, and return a markup string.
theme_swftools_formatter_playlist in ./swftools.module: Theme function to turn multiple value CCK filefield in to a playlist.
theme_swftools_formatter_swftools in ./swftools.module: Theme function to turn CCK filefield in to flash content.
_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 most likely SWF Tools action for a file, based on its extension.
_simpleviewer_vars in simpleviewer/simpleviewer.module: These are the default options and flashvars.
_swftools_filter_process_text in ./swftools.module

File

./swftools.module, line 197

Code

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

  // Initialise any $options array elements that weren't passed by the caller
  $options += array(
    'params' => array(),
    'flashvars' => array(),
    'othervars' => array(),
    'methods' => array(),
  );

  // If swf() was called with an array of files, make a playlist and call swf_list() for processing
  if (is_array($file)) {

    // Turn the array in to a playlist
    $playlist_data = swftools_prepare_playlist_data($file, '', isset($options['methods']['action']) ? FALSE : TRUE);

    // Call swf_list to process the playlist and create the markup
    return swf_list($playlist_data, $options);
  }

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

  // ACTION
  // Work out what SWF Tools should do with this file
  // Was an explicit action set in $options['methods']['action']
  $action = isset($options['methods']['action']) ? $options['methods']['action'] : FALSE;

  // If an explicit action wasn't set then try to determine an appropriate one using the filename
  if (!$action) {
    $action = swftools_get_action($file);
  }

  // HTML ALTERNATIVE
  // If an explicit value wasn't set in $options['othervars']['html_alt'] use a default
  $html_alt = isset($options['othervars']['html_alt']) ? $options['othervars']['html_alt'] : variable_get('swftools_html_alt', SWFTOOLS_DEFAULT_HTML_ALT);

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

  // PLAYER
  // Work out what player SWF Tools will need to use for this action
  // Was an explicit player set in $options['methods']['player']
  $player = isset($options['methods']['player']) ? $options['methods']['player'] : FALSE;

  // If an explicit player wasn't set then find out what player is configured for the current action
  if (!$player) {

    // Find out what player is assigned to handle the current action
    $player = swftools_get_player($action);

    // If still no player assignment then we don't know what to do with this action
    if (!$player) {

      // Build an array of descriptions for each possible action
      $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 we have a matching description for the specified action, create a meaningful message
      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 couldn't find a player for this content, so fallback to the alternate markup and return
      return $html_alt;
    }
  }

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

    // If the combination was found, place player information in to $resolved_methods
    $resolved_methods->player = $all_methods[$action][$player];
  }
  else {

    // If the action is display an swf directly then assume we have a custom player
    if ($action == SWFTOOLS_SWF_DISPLAY_DIRECT) {

      // Assign SWFTOOLS_CUSTOM data in to $resolved_methods
      $resolved_methods->player = $all_methods[$action][SWFTOOLS_CUSTOM];
      $resolved_methods->player['shared_file'] = $player;
    }
    else {
      drupal_set_message(t('Could not find the %player file for embedding.', array(
        '%player' => $player,
      )), 'error', FALSE);
      return $html_alt;
    }
  }

  // EMBED
  // Work out what embedding method SWF Tools should use for this content
  // Was an explicit embedding method set in $options['methods']['embed']
  $embed = isset($options['methods']['embed']) ? $options['methods']['embed'] : FALSE;

  // If an explicit embedding method wasn't set then find get the current default
  if (!$embed) {
    $embed = variable_get(SWFTOOLS_EMBED_METHOD, SWFTOOLS_NOJAVASCRIPT);
  }

  // Place the embedding method information in to $resolved_methods
  $resolved_methods->embed = $all_methods[SWFTOOLS_EMBED_METHOD][$embed];

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

  // OTHERVARS
  // If $options['othervars'] were supplied, add to $vars->othervars
  $vars->othervars = is_array($options['othervars']) ? $options['othervars'] : array();

  // PARAMS
  // $options['params'] could be an associative array, or in 'WIDTHxHEIGHT' format.
  // If $options were passed to the swf() function then process them
  if ($options['params']) {

    // If $options['params'] is an array then just add it to $vars
    if (is_array($options['params'])) {
      $vars->params = $options['params'];
    }
    else {
      $dimensions = explode('x', $options['params']);
      if (count($dimensions) == 2) {
        $vars->params = array(
          'width' => $dimensions[0],
          'height' => $dimensions[1],
        );
      }
    }
  }

  // FLASHVARS
  // Flashvars could be passed as an associative array, or as a string in 'a=1&b=2' format
  // If the flashvars have been passed as an array simply add to $varsa
  if (is_array($options['flashvars'])) {
    $vars->flashvars = $options['flashvars'];
  }
  else {

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

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

  // If the base path isn't set, or the path is not valid try to find a reasonable alternative
  if (!$base || !valid_url($base)) {

    // Use swftools_get_media_url() to obtain either the local path, or the remote media path
    $base = swftools_get_media_url('', FALSE);
  }

  // Strip $base_root if this is a local base path
  $base = swftools_strip_base_root($base);

  // Assign the resulting base path in to  $vars->params['base']
  $vars->params['base'] = $base;

  // PLAYLIST
  // Determine if we trying to generate a playlist
  // If $options['othervars']['playlist_data'] is set then we are processing a playlist
  if (isset($options['othervars']['playlist_data'])) {

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

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

    // If a file wasn't generated by swftools_generate_playlist then set an error and return alternate markup
    if (!$file) {
      drupal_set_message(t('Unable to create playlist.'), 'error');
      return $html_alt;
    }
  }

  // CACHING
  // To try and prevent the xml files from being cached append the time to the filename to try and force it to reload
  if (variable_get('swftools_playlist_caching', 'here') == 'always') {
    $nocache = '?nc=' . time();
  }
  else {
    $nocache = '';
  }

  // FILE
  // Make sure that the file path is $file is valid - we skip this section if $file is already a full url
  // Otherwise we try to expand it to a full url to the local file system or the remote media directory
  // If $file isn't already a valid url...
  //  if (!valid_url($file, TRUE)) {
  // If $file isn't a valid url, and if the file isn't going to be streamed, then try to work out where it is
  if (!valid_url($file, TRUE) && !isset($vars->othervars['stream'])) {

    // If we don't have a playlist...
    if (empty($playlist)) {

      // TODO : Is it necessary to have swftools_get_media_path() AND swftools_get_media_url()
      // Then check if files are being sourced locally, and if they are build a file path
      if (swftools_get_media_path()) {
        $file = file_create_path($file);
      }
    }

    // Try to turn $file in to a complete url, either local or remote
    $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;
  }
  else {
    $file_url = $file;
  }

  //  // Try to strip $base_root if this is a local path
  //  $file_url = swftools_strip_base_root($file_url);
  // Attach file_url to othervars so player modules have access if required
  $vars->othervars['file_url'] = $file_url;

  // SRC
  // 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:
      $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($vars->params['src_path']);
      break;
    default:
      $vars->params['src_path'] = swftools_get_player_path() . '/' . $resolved_methods->player['shared_file'];
      $vars->params['src'] = $GLOBALS['base_url'] . '/' . $vars->params['src_path'];
  }

  // Try to strip $base_root if this is a local path
  $vars->params['src'] = swftools_strip_base_root($vars->params['src']);

  // 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.
  if (module_hook($resolved_methods->player['module'], 'swftools_flashvars')) {

    // Get player flashvars - use a custom invoke to allow pass by reference
    $player_flashvars = swftools_flashvars_invoke($action, $resolved_methods, $vars);

    // Merge player flashvars with existing flashvars
    if (is_array($player_flashvars)) {
      $vars->flashvars = array_merge($vars->flashvars, $player_flashvars);
    }
  }

  // If the player made a flashvar assignment for the playlist, add it to the flashvars
  if (!empty($resolved_methods->player['file'])) {
    $vars->flashvars[$resolved_methods->player['file']] = $vars->othervars['file_url'];
  }

  // If the player requires a specific minimum flash version then assign it to the params
  if (isset($resolved_methods->player['version'])) {
    $vars->params['version'] = $resolved_methods->player['version'];
  }

  // Call function to set the size of the content
  swftools_set_size($vars, $resolved_methods->player);

  // 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.
  $embed_markup = module_invoke($resolved_methods->embed['module'], 'swftools_embed', $action, $resolved_methods, $vars, $html_alt);

  // Call theme function to return completed markup, e.g. add containing div
  return theme('swftools_embed', $embed_markup, $action, $resolved_methods, $vars, $html_alt);
}

You are here

function swf in SWF Tools 6.2

Parameters

File

Code

API Navigation