Customize Download Page Summary

You can provide a summary to your user of the current download. This is done before the file is generated and is meant to provide context and a reminder of what they are waiting for. Be default, the Tripal Download API will not give a summary to your user. This is because it would be too difficult to generically generate a good summary. As such you are strongly recommended to implement your own summary function for every Tripal Download Type. To provide a summary, specify the 'summarize' key under 'functions' to define a custom function which will generate a very short summary.

/**
 * Implements hook_register_trpdownload_type().
 */
function trpdownload_example_register_trpdownload_type() {
  $types = array();

  // The example download type will be used for the following example:
  $types['feature_csv'] = array(
    'type_name' => 'Feature CSV',
    'format' => 'Comma-separated Values',
    'functions' => array(
      'generate_file' => 'trpdownload_feature_csv_generate_file',
      // NOTE: provide a summary to the user on the download page.
      'summarize' => 'trpdownload_feature_csv_summarize_download',
      'get_filename' => 'trpdownload_feature_csv_get_filename',
      'get_file_suffix' => 'trpdownload_feature_csv_get_suffix',
    ),
  );

  return $types;
}

The custom function specified above by the 'summarize' key will be passed all the query arguments from the path passed to the Tripal Download API in addition to some other useful information. You can then use this information to generate a short snippet of HTML (I recommend an unordered list) to summarize the file that will be generated. I suggest one bullet per filter criteria choosen with the restriction that if your form has too many filter criteria, you choose the most informative ones to display. I recommend you keep your summaries to 3-4 bullet points but the download page will expand to handle larger summaries if needed.

Our example download type is expected to be called from the default Tripal Feature User view. This means the following filter criteria are available:

• Unique Name (operator exposed)
• Name (operator exposed)
• Feature Type
• Organism Common Name The following example shows each of the above filter criteria summarized in it's own bullet.

/** 
 * Summarize the current download for Feature CSV download type.
 *
 * @param $vars
 *   An array of variables available to this function. Including:
 *     - ['download_args']['q']: all the arguments in the path passed to the Tripal Download API
 *     - ['download_args']['safe_site_name']: a sanitized version of the site-name for use in filenames
 *     - ['download_args']['type_info']: what you defined in hook_register_trpdownload_type() for the current download type
 * @return
 *   A string representing the summary (can include html).
 */
function trpdownload_feature_csv_summarize_download($vars) {
  $output = ''; // The variable storing the HTML output.

  // First, put the query arguments in a more accessible variable.
  $q = $vars['download_args']['q'];

  $output .= '<span>Sequence features where</span>';
  $output .= '<ul>';

  // Unique Name:
  // Since the operator is exposed we have two variables: uniquename_op has the operator and uniquename has the value.
  // Check the URL of your view after filtering to determine what these variables will be.
  if (!empty($q['uniquename'])) {
    $output .= '<li>Unique Name ' . $q['uniquename_op'] . ' <em>"' . $q['uniquename'] . '"</em></li>';
  }

  // Name: Handle the same as uniquename.
  if (!empty($q['name'])) {
    $output .= '<li>Unique Name ' . $q['name_op'] . ' <em>"' . $q['name'] . '"</em></li>';
  }

  // Feature Type:
  // The type_id is saved in the URL.
  if (!empty($q['type_id']) AND is_int($q['type_id'])) {
     // Since the type_id is not very friendly to the users, look up the name of the type first.
     $name = chado_query('SELECT name FROM {cvterm} WHERE type_id=:id',
       array(':id' => $q['type_id']))->fetchField();
     if ($name) {
       $output .= '<li>Only "'.$name.'"</li>';
     }
  }

  // Organism Common Name:
  // Luckily the full common name is stored in the path.
  if (!empty($q['organism'])) {
    $output .= '<li>From <i>"'.$q['organism'].'"</i></li>';
  }

  $output .= '</ul>';
  return $output;
}

This should add the following to the right of the download link on the download page:

Summary: Sequence features where

• Unique Name contains "frd"
• Name contains "Fred"
• Only chromosome(s)
• From "Tripalus databasica"

Again, keep in mind that this summary is generated immediately and doesn't have access to the actual file generated. As such you need to use the query parameters to summarize the file.