<?php
// $Id: swftools.php,v 1.3 2010-05-06 19:58:39 stuartgreenfield Exp $

/**
 * @file
 * Doxygen documentation for SWF Tools.
 */

/**
 * @defgroup swftools SWF Tools
 * @{
 * Enables comprehensive support for Flash based media.
 *
 * SWF Tools provides a convenient way to enable Flash based media within a
 * Drupal website. It can be used to place a simple .swf file on the page, and the
 * module is easily extended with other components to enhance its capabilities.
 * Modules are available to enable play back of audio, video and image based
 * content through a variety of Flash based media players.
 * 
 * The features of SWF Tools can be accessed in a number of ways.
 * 
 * For simple display of a single file directly within a node the module makes
 * an SWF Tools input filter available. Enable this for an input format and
 * Flash, audio and video can be rendered directly from within the node using
 * [swf file="myFile.swf"] or [swf files="myAudio.mp3&&moreAudio.mp3&&otherAudio.mp3"]
 *  
 * From within PHP SWF Tools is accessed via a simple function call such as 
 *  
 * @code $output = swf($file, $options); @endcode
 * 
 * It is also possible to include Flash, audio or video within a form definition
 * by using the swftools element.
 * 
 * @code $form['mySWF'] = array(
 *   '#type' => 'swftools',
 *   '#value' => 'myFlash.swf',
 * ); @endcode
 * 
 * SWF Tools has built in integration with CCK and Views. By default it will
 * expose some basic formatters that can be used with file fields, text fields
 * and link fields. These allow the fields to be rendered in to a series of discrete
 * players, or assembled in to a playlist.
 * 
 * With the addition of the SWF Tools Profiles module different player setups
 * can be created and these are all exposed as additional formatters. This makes
 * it possible to have different styles of player associated with different CCK
 * content types.
 * 
 * Integration with Views lets SWF Tools act as a handler to render a query into
 * a playlist. For example, a query could extract all the uploaded files from a
 * content type and return the five most recent items. The results can be
 * passed to any player profile to be rendered. This makes it very simple to
 * create a page or a block that shows customised views.
 * 
 * With players like LongTail Player and FlowPlayer 3 playlists can include a
 * thumbnail image. This will be displayed in the player when it is waiting for
 * the content to play, or as a background image when audio is playing.
 * 
 * SWF Tools supports a number of image gallery modules, such as SimpleViewer
 * and LongTail Image Rotator. These can be used directly in a node as a
 * formatter for a CCK content type, but they are most effective when used in
 * conjunction with Views to generate a Flash based slideshow.
 * 
 * User topics:
 * 
 * Developer topics:
 * - @link hook_swftools_methods Registering players with SWF Tools @endlink
 */

/**
 * Reports an embedding method or a player to SWF Tools.
 * 
 * Embedding methods and players should implement hook_swftools_methods() to
 * register themselves with SWF Tools.
 * 
 */
function hook_swftools_methods() {
  
  /**
   * First define the player as an array of properties.
   */
  $myplayer = array(
    'module'      => 'swftools_myplayer',
    'version'     => 9,
    'title'       => t('My Player'),
    'download'    => 'http://myplayer.org',
    'width'       => 500,
    'height'      => 375,
    'library'     => swftools_get_library('myplayer') . 'myplayer/myplayer.swf',
    'profile'     => array(
      'path' => 'myplayer',
      'settings' => array('swftools_myplayer', 'swftools_myplayer_colors'),
      'file' => 'swftools_myplayer.admin.inc',
      'page argument' => 'swftools_myplayer_form',
    ),
  );
  
  /**
   * Then associate the player with actions that it can process.
   * [action][name_of_player] = [player_details]
   */
  $methods['video']['myplayer'] = $myplayer;
  $methods['video_list']['myplayer'] = $myplayer;
  $methods['audio']['myplayer'] = $myplayer;
  $methods['audio_list']['myplayer'] = $myplayer;
  $methods['image_list']['myplayer'] = $myplayer;
  $methods['swftools_media_display']['myplayer'] = $myplayer;
  $methods['media_list']['myplayer'] = $myplayer;

  // Return the method results
  return $methods;

}


/**
 * Processes a playlist ready for use by the specified player.
 * 
 * If a player can process a playlist then it should implement this
 * hook to perform processing that turns the SWF Tools array of data in to the
 * format that the player will ultimately use.
 * 
 * If the player uses xml based playlists then this hook should return a string
 * of markup. SWF Tools will take care of storing the playlist and giving it a
 * file name. The filename will be available on the ['othervars']['file_url'] key
 * when the player is ready to be rendered.
 * The filename is a 32 character hexadecimal string that is built by hashing the
 * playlist with the specified player options. This should generate a unique
 * string for a given playlist in a given player. Playlists are not physically
 * written to the file system but are stored in the table {cache_swftools}. All
 * the player needs to do is assign the ['othervars']['url'] value to access it.
 * What actually happens is that SWF Tools is providing a menu path. When the
 * browser requests the file SWF Tools serves it directly from the cache. When the
 * site caches are flushed SWF Tools will rebuild the playlists when they are next
 * requested.
 * 
 * Players such as FlowPlayer 3 do not use an xml based playlist system. Instead
 * they use a configuration array that is written out directly as part of the player
 * configuration. In these cases the processing does not necessarily have to be
 * done in hook_swftools_playlist_PLAYER() and it could be handled in
 * hook_swftools_preprocess_PLAYER(). However, it is a good idea to use the
 * playlist hook as it separates the logic of preparing a playlist from the logic of
 * outputting the player. When preparing a non-xml playlist the code in this hook
 * should directly modify $data, and it should return the value SWFTOOLS_NON_XML_PLAYLIST
 * to notify SWF Tools that xml generation should be skipped.
 * 
 * For examples of xml based playlist generation see:
 * - swftools_wijering4_swftools_playlist_jwplayer4()
 * - swftools_simpleviewer_swftools_playlist_simpleviewer()
 * 
 * For examples of non-xml based playlist generation see:
 * - swftools_wpaudio_swftools_playlist_wpaudio()
 * - swftools_flowplayer3_swftools_playlist_flowplayer3()
 * 
 * @param $data
 *   An array of SWF Tools data representing the media that is to be rendered.
 *   
 * @see hook_swftools_preprocess_PLAYER()
 */
function hook_swftools_playlist_PLAYER(&$data) {

  // Get array of image rotator settings
  $saved_settings = _swftools_PLAYER_settings($data['othervars']['profile']);
  
  // Initialise a string to contain the elements
  $xml = '';
  
  // Iterate over the playlist to build elements xml
  foreach ($data['othervars']['playlist_data']['playlist'] AS $track => $details) {
    
    // If imagecache is enabled see if we need to use a modified thumbnail
    if ($saved_settings['imagecache'] != SWFTOOLS_UNDEFINED) {
      $details['fileurl'] = swftools_imagecache_create_path($saved_settings['imagecache'], $details['fileurl']);
    }
    
    // Create an individual xml element on the raw playlist
    $xml .= theme('swftools_PLAYER_playlist_element', $details);
    
  }
  
  // Add xml wrapper around the elements
  $xml = theme('swftools_PLAYER_playlist_wrapper', $data['othervars']['playlist_data']['header'], $xml);
  
  // Return the resulting xml
  return $xml;

}


/**
 * Does the final preparation prior to rendering the specified player.
 * 
 * This hook is called just before the player is output on to the page. At this
 * point the SWF Tools data array is complete and the element is almost ready for
 * display.  Prior to this hook being called SWF Tools has been working out what
 * action is needed, and what player and embedding method is going to be used. It
 * is up to the implementing module to do the final preparations and configuration
 * of the Flash element. For example, it the player requires a specific flashvar to
 * be set in order to find the playlist then this should be done in this hook.
 * 
 * A common flow of logic in this hook is to determine whether a splash image is
 * being used, and if so assign it to a flashvar, followed by assignment of the
 * generated xml playlist to another flashvar.
 * 
 * More complex code is possible, and sometimes necessary. For example, the
 * FlowPlayer 3 module uses JSON notation to create a single flashvar that holds
 * the entire configuration. In that case the hook function is more complex since
 * it must assemble the JSON array from the constituent data in the $data array.
 * 
 * This function does not return anything - $data should be passed by reference and
 * then modified directly.
 * 
 * If any supporting JavaScript is required then it can be added via this hook.
 * Some care is needed when using JavaScript dependent players to make sure that the
 * JavaScript is always available on the finished page. In particular, if the site
 * allows content to be added via the input filter then this hook is only called the
 * first time the content is generated. The resulting markup is cached by the input
 * filter and on subsequent views the cached version will be used. The module must
 * therefore make sure it adds JavaScript to every page by using hook_init().
 * 
 * For examples of hook_swftools_preprocess_PLAYER() see:
 * - swftools_wijering4_swftools_preprocess_jwplayer4()
 * - swftools_flowplayer3_swftools_preprocess_flowplayer3()
 * 
 * @see hook_swftools_playlist_PLAYER()
 */
function hook_swftools_preprocess_PLAYER(&$data) {
  
  // Get current defaults for the player
  $saved_settings = _swftools_PLAYER_flashvars($data['othervars']['profile']);
  
  // Prepare an array of flashvars by merging defaults and user values
  $data['flashvars'] = array_merge($saved_settings, $data['flashvars']);
  
  // If an image has been set then use it  
  if ($data['othervars']['image']) {
   
    // Get source path to the image file
    $source = swftools_get_url_and_path($data['othervars']['image']);
    
    // If $source succeeded add image to the playlist
    if ($source) {
      
      // See if we need to apply an imagecache preset
      if ($saved_settings['imagecache_player'] != SWFTOOLS_UNDEFINED) {
        $source['fileurl'] = swftools_imagecache_create_path($saved_settings['imagecache_player'], $source['fileurl']);
      };

      // Store result in a flashvar called image
      $data['flashvars']['image'] = $source['fileurl'];

    }

  }
  
  // Don't output imagecache_variables
  unset($data['flashvars']['imagecache_player']);
  
  // Attach the generated path the xml based playlist
  $data['flashvars']['file'] = $data['othervars']['file_url'];
  
}


/**
 * @} End of "defgroup swftools".
 */