Custom Link-outs

In Tripal BLAST “Linkouts” refer to changing the hit name in the BLAST results table to a link. This link usually gives the user additional information and may link to pages in your Tripal site, external websites or genome browsers. You can configure link-outs per BLAST Database and depending on the type, many link-outs support regular expression for extracting parts of the name. The types provided by Tripal BLAST also require you select a Tripal Database (Tripal > Chado Modules > Databases) which contains the URL information for the link. If the link-out types supplied by Tripal BLAST do not fit your needs you can create a custom type using the documentation below.

To create custom link-outs for Tripal BLAST you need to first create your own Drupal module. If you are unfamiliar with this process there are a number of good tutorial available in addition to the Drupal Documentation.

Once you have a custom module you need to implement hook_blast_linkout_info() to tell Tripal BLAST about your custom link-out. You do this by creating a function with the name of your module replacing the word “hook”. For example:

/**
 * Implements hook_blast_linkout_info().
 * Provides a custom link-out type for my institutes genome browser.
 */
function mymodule_blast_linkout_info() {
  $types = array();

  $types['mybrowser'] = array(
    // Human-readable Type name to display to users in the BLAST Database
    // create/edit form.
    'name' => 'UofS Browser',
    // The function used to generate the URL to be linked to.
    // This function will have full access to the blast hit and database
    // prefix information and is expected to return a URL.
    'process function' => 'mymodule_generate_linkout_mybrowser',
    // Help text to show in the BLAST Database create/edit form so that
    // users will know how to use this link-out type. Specifically, info
    // about your assumptions for the URL prefix are very helpful.
    // HTML is aloud but do not enclose in <p>.
    'help' => 'This type assumes your blast database is the reference for one
      of the University of Saskatchewan Genome Browsers and that you have selected
      the Tripal Database referencing that browser below.',
    // Whether or not the link-out requires additional fields from the nodes.
    'require_regex' => TRUE,
    'require_db' => TRUE,
  );

  return $types;
}

Next you need to implement the process function that you indicated. This function is given a number of variables providing information about the hit, etc. and is expected to generate a fully rendered link based on that information. For example,

/**
 * Generate a link to the UofS Genome Browser for a given hit.
 *
 * @param $url_prefix
 *   The URL prefix for the BLAST Database queried.
 * @param $hit
 *   The blast XML hit object. This object has the following keys based on the
 *   XML: Hit_num, Hit_id, Hit_def, Hit_accession, Hit_len and Hit_hsps.
 *   Furthermore, a linkout_id key has beek added that contains the part of the
 *   Hit_def extracted using a regex provided when the blastdb node was created.
 * @param $info
 *   Additional information that may be useful in creating a link-out. Includes:
 *    - query_name: the name of the query sequence.
 *    - score: the score of the blast hit.
 *    - e-value: the e-value of the blast hit.
 * @param $options
 *   Any additional options needed to determine the type of link-out. None are
 *   supported by this particular link-out type.
 *
 * @return
 *   An html link.
 */
function tripal_blast_generate_linkout_link($url_prefix, $hit, $info, $options = array()) {

  if (isset($hit->{'linkout_id'})) {

    // This is where you would generate your link. If your link requires query parameters
    // then we suggest you use l() $options['query'] to encode them rather than appending
    // them to the URL prefix directly.
    // This StackExchange question shows a good example:
    //   http://drupal.stackexchange.com/questions/38663/how-to-add-additional-url-parameters
    $hit_url = $url_prefix . $hit->{'linkout_id'};

    // See the documentation for l():
    //  https://api.drupal.org/api/drupal/includes%21common.inc/function/l/7
    return l(
      $hit->{'linkout_id'},
      $hit_url,
      array('attributes' => array('target' => '_blank'))
    );
  }
  else {
    return FALSE;
  }
}