<?php
// $Id: object.php,v 1.2 2009-08-23 07:35:12 stuartgreenfield Exp $

/**
 * @file
 * These hooks are defined by the embed module and are used to declare data
 * about themes/handles to the embed module.
 */

/**
 * @addtogroup hooks
 * @{
 */

/**
 * Report information about an embedding handler to the embed module.
 * 
 * Modules implementing a theme that can be used to render objects should use this hook to notify the embed
 * module of the theme, and to provide data that is used on the settings page. The hook should return
 * an array of arrays. The key to each sub-array is the name of the theme, and the sub-array contains
 * information about the theme. Each sub-array contains the following items:
 *
 * - title (required): 
 *   The human readable name of the theme that will be shown in the swf API settings page
 *   with an option button to select this theme.
 *   
 * - types (required):
 *   An array of mime types that the theme is capable of handling (e.g. application/x-shockwave-flash).
 *   The types are defined as mime types.
 *   
 * - description (optional):
 *   A description of the theme that will displayed on the settings page to help explain to the user
 *   and details or special features of the theme. Although optional it is recommended that something
 *   is included here.
 *   
 * - multiple values (optional):
 *   This works like CCK. If the theme can handle only single objects it should omit this key, or declare
 *   it with a value of EMBED_HANDLE_CORE. In this case collections of objects will be rendered individually
 *   on the page. It a theme can handle an array of objects it can declare the value of this key to be
 *   EMBED_HANDLE_MODULE. In this case arrays of objects will be passed to the handler for processing.
 *   
 * - elements (optional):
 *   A theme can add additional elements to an existing element by declaring an array under this key. A
 *   common use would be to register additional pre- or post-render callbacks by setting the keys #pre_render
 *   and #post_render. This might be used to provide a custom handler in the event the emedding fails. Any
 *   custom pre-render functions are called after the core pre-render call back, so additional pre-render
 *   callbacks will receive the object id.
 * 
 * - resource (optional):
 *   If the theme requires the use of a supporting file, normally a JavaScript one, then its path
 *   should be give here. The data in this key is used by the API to verify that the file
 *   exists and to present a warning message on the settings page if the file cannot be found. It is not
 *   necessary to use this key and if omitted then no checks will be done. Because the API can check for
 *   any file a full path must be used - see swfobject2_api_embed_info() for
 *   an example. Because it is possible to include any path the swf API settings page can check for the
 *   existence any file, including one that belongs to a different module. The API only checks
 *   a single file - it is assumed that for resources that use multiple files that either the whole library
 *   is present, or none of it is present.
 * 
 * - download (optional):
 *   A url to the supporting library can be provided in this key. When present the API settings
 *   page will use it provide a convenient link to the library to help the user find the files needed to make
 *   the embedding method work.
 * 
 * - private (optional):
 *   Some themes may implement specialist embedding methods that are not designed to handle general
 *   swf content. If this key is included and given the value of TRUE then the theme will not be displayed for
 *   use on the settings page. Other modules may access the theme only by explicitly setting the #theme property
 *   of an swf element. An example of this would be the FlowPlayer embedding library which is only designed for
 *   use with FlowPlayer.
 *   
 * - operations (optional):
 *   A path to a settings page for the handler, expressed as a partial menu path, e.g. admin/settings/my_module.
 *   A link to this page will be rendered in the settings table if this is set.
 *   
 * - TODO cacheable (required|optional?):
 *   Is the theme suitable for use with embedding content via an input filter where the result is cached? Will
 *   use this to provide a status message or icon on the settings page?
 * 
 * @return
 *   An array of data describing the theme.
 */
function hook_embed_info() {

  return array(

    'embed_swfembed' => array(
      'title' => 'SWF Embed',
      'description' => t('This is an interface layer that allows the embed module to communicate with the SWF
                          Embed module (which must also be enabled). The SWF Embed module uses its own jQuery
                          script to place the swf content on the page and does not require any additional
                          supporting resources. This theme can support the express install feature, but a
                          path to a suitable express installer must be given when calling the API. Because
                          this module uses Drupal.settings to store the flash content it is NOT suitable
                          for use as an embedding method for content generated using an input filter.'),
      'types' => array('application/x-shockwave-flash'),
    ),
    
  );
  
}


/**
 * Perform alterations to an object element before it is rendered.
 * 
 * This hook is designed to let modules get access to the element immediately
 * before it is rendered, and the hook is called before any pre-rendering is done.
 * Note that the hook is called as part of embed_pre_render(), so if an object is
 * rendered without calling the standard pre-render handler then the hook will not
 * be fired. In most cases it is unlikely that a custom pre-render will be assigned,
 * but if it is then it is important to note this. If a module is calling embed
 * through a "non standard" way then that module could implement it's own call to
 * hook_object_alter() if it wanted to. Alternatively it could choose to ignore the
 * hooks and prevent its objects from being altered.
 *
 * @param $element
 *   The element that is about to be rendered.
 * @return
 *   Nothing - the element is passed by reference.
 */
function hook_object_alter(&$element) {
  
  // Example - ensure the content will be in cacheable format
  $element['#cacheable'] = TRUE;
  
}


/**
 * @} End of "addtogroup hooks".
 */