trpdownload_api.module

<?php
/**
 * @file
 */

require_once "includes/trpdownload_api.tripal_jobs.inc";

/**
 * Register a download type that can be used with this API.
 * @return
 *   An associative array of tripal download types to register. The keys on the outer
 *   array are the machine names of each type, and the values are arrays containing
 *   information about the type. Each information array should contain the following
 *   key/value pairs:
 *    - format_name: a human-readable name of the format to be displayed to the user.
 *    - functions: an array of functions that will return specific information, etc.
 *        - generate_file: the name of the function that will generate the file. This
 *            function will be called by tripal jobs on the command-line.
 *        - summarize: the name of a function that will provide summary information about
 *            the file that will be generated.
 *        - get_filename: a function that will return an informative file name based on
 *            the arguements that will be used to generate the file.
 *    - theme: an array of theme functions to use to render specific parts of the file.
 *        The part of the file to be rendered is the key and the value is the name
 *        of a theme implementation (ie: key in hook_theme).
 */
function hook_register_trpdownload_type() {
  $types = array();

  return $types;
}

/**
 * Retrieve information for a given download type.
 *
 * @param $machine_name
 *   The machine name of the tripal download type to return information on.
 * @return
 *   The array supplied in hook_register_trpdownload_type().
 */
function trpdownload_get_download_type_info($machine_name) {

  $internal_types = hook_register_trpdownload_type();
  if (isset($internal_types[$machine_name])) {
    return $internal_types[$machine_name];
  }

  $custom_types = module_invoke_all('register_trpdownload_type');
  if (isset($custom_types[$machine_name])) {
    return $custom_types[$machine_name];
  }

  return FALSE;
}

/**
 * Implements hook_menu().
 */
function trpdownload_api_menu() {
  $items = array();

  $items['tripal/progress/job/%/%'] = array(
    'title' => t('Tripal Job progress'),
    'page callback' => 'tripal_job_progress_json',
    'page arguments' => array(3,4),
    'access callback' => TRUE,
    'type' => MENU_CALLBACK,
  );

  return $items;
}
/******************************************************************************
 * @section
 * Generic Download Page
 */

/**
 * Implements hook_theme().
 */
function trpdownload_api_theme($existing, $type, $theme, $path) {
  $items = array();

  $items['trpdownload_page'] = array(
    'template' => 'theme/generic_download_page',
    'variables' => array('trpdownload_key' => NULL, 'arg1' => NULL, 'arg2' => NULL),
  );

  return $items;
}

/**
 * Simply renders the download page template.
 */
function trpdownload_download_page($trpdownload_key, $arg1 = NULL, $arg2 = NULL) {
  $path = drupal_get_path('module','trpdownload_api');

  $variables = array(
    'trpdownload_key' => $trpdownload_key,
    'arg1' => $arg1,
    'arg2' => $arg2,
  );
  trpdownload_api_prepare_download_page_vars($variables);

  if (isset($variables['job_id'])) {
    // Add the JS needed for AJAX updating based on job progress.
    drupal_add_js('misc/progress.js');
    drupal_add_js($path . '/theme/js/trpdownloadApiProgressBar.js');
    drupal_add_js($path . '/theme/js/trpdownloadApiFileBoxFeedback.js');

    // Add settings needed by the above JS scripts.
    drupal_add_js(
     array(
       'trpdownloadApiProgressBar' => array(
         'progressPath' => url('/tripal/progress/job/'.$trpdownload_key.'/'.$variables['job_id'])
       )
     ),
     'setting'
   );
  }

  drupal_add_css($path . '/theme/css/generic_download_page.css');

  return theme('trpdownload_page', $variables);
}

/**
 * Prepare the variables needed for the generic download page.
 * Note: If there is no job_id arguements then this function will create a new tripal job.
 *
 * @param $variables
 *   An array of variables to be made available to the theme function.
 */
function trpdownload_api_prepare_download_page_vars(&$variables) {

  // Save the query parameters.
  $variables['q'] = drupal_get_query_parameters();
  $variables['job_code'] = (isset($variables['arg1'])) ? $variables['arg1'] : NULL;

  // If we have the job_id encoded in the URL then we should show the user progress
  // on the generation of their download file. All of the variables needed to show them
  // this progress should have been saved in the job so pull them out now :-).
  if ($variables['job_code']) {
    $variables['job_id'] = trpdownload_api_reveal_secret($variables['job_code']);
    $variables['job'] = tripal_get_job($variables['job_id']);
    $variables['job']->arguments = unserialize($variables['job']->arguments);
    $variables['download_args'] = $variables['job']->arguments['variables'];
    $info = $variables['download_args']['type_info'];
  }
  // Otherwise we should parse the URL and create a tripal job to generate the file
  // and then save that job_id in the URL.
  else {
    $variables['download_args']['q'] = $variables['q'];
    $variables['download_args']['safe_site_name'] = preg_replace('/\W+/','',ucwords(strip_tags(variable_get('site_name', 'Drupal'))));

    // First get information for the specified download type.
    $info = trpdownload_get_download_type_info($variables['trpdownload_key']);
    $variables['download_args']['type_info'] = $info;

    // Determine the suffix the file should be given.
    $variables['download_args']['suffix'] = (isset($info['file_suffix'])) ? $info['file_suffix'] : 'txt';
    if (isset($info['functions']['get_file_suffix']) AND function_exists($info['functions']['get_file_suffix'])) {
      $variables['download_args']['suffix'] = call_user_func($info['functions']['get_file_suffix'], $variables);
    }

    // Deteremine the file name to give the generated file.
    $variables['download_args']['filename'] = NULL;
    if (isset($info['functions']['get_filename']) AND function_exists($info['functions']['get_filename'])) {
      $variables['download_args']['filename'] = call_user_func($info['functions']['get_filename'], $variables);
    }
    if (!$variables['download_args']['filename']) {
      $variables['download_args']['filename'] = $variables['download_args']['safe_site_name'] .'.'. $variables['trpdownload_key'] .'.'. date('YMj-his');
    }
    $variables['download_args']['filename'] .= '.' . $variables['download_args']['suffix'];

    // Determine the human-readable name of the file format.
    $variables['download_args']['format_name'] = 'Text';
    if (isset($info['format'])) {
      $variables['download_args']['format_name'] = $info['format'];
    }
    elseif (isset($info['type_name'])) {
      $variables['download_args']['format_name'] = $info['type_name'];
    }
    if (isset($info['functions']['get_format']) AND function_exists($info['functions']['get_format'])) {
      $variables['download_args']['format_name'] = call_user_func($info['functions']['get_format'], $variables);
    }

    // Now create the tripal job to generate the file :-D.
    if (isset($info['functions']['generate_file']) AND function_exists($info['functions']['generate_file'])) {
      global $user;
      $variables['job_id'] = tripal_add_job(
        'Download '.$info['type_name'],
        'trpdownload_api',
        $info['functions']['generate_file'],
        array('variables' => $variables['download_args']),
        $user->uid
      );

      // Encode the URL.
      $variables['job_code'] = trpdownload_api_make_secret($variables['job_id']);

      // Determine the path to redirect to.
      global $base_url;
      $variables['path'] = $base_url . '/' . current_path() . '/' . $variables['job_code'];

      // Load the job so my progress bar knows what to display ;-).
      $variables['job'] = tripal_get_job($variables['job_id']);

    }
    else {
      tripal_report_error(
        'trpdownload_api',
        TRIPAL_CRITICAL,
        'Function to generate file for %type is not set or doesn\'t exist.',
        array('%type' => $variables['trpdownload_key'])
      );
    }
  }

  if (isset($variables['job_id'])) {
    // Used by javascript to determine the status of the job and update this page via ajax.
    $variables['progress_path'] = url('/tripal/progress/job/'.$variables['trpdownload_key'].'/'.$variables['job_id']);
  }

  // Determine the URL of the file once it's been generated.
  $variables['file_download_url'] = file_create_url(variable_get('trpdownload_relpath', NULL) . $variables['download_args']['filename']);
}