Added developers guide.

docs/dev_guide.rst

@@ -0,0 +1,12 @@
+
+Developer Guide
+================
+
+A guide for module developers on how to customize and/or extend Tripal BLAST UI.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   dev_guide/custom_linkouts
+   dev_guide/custom_styling.rst

docs/dev_guide/custom_linkouts.rst

@@ -0,0 +1,90 @@
+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:
+
+.. code:: php
+
+  /**
+   * 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,
+
+.. code:: php
+
+  /**
+   * 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;
+    }
+  }

docs/dev_guide/custom_styling.rst

@@ -0,0 +1,6 @@
+Custom Styling
+===============
+
+The BLAST module forms can be styled using CSS stylesheets in your own theme. By default it will use the default form themeing provided by your particular Drupal site allowing it to feel consistent with the look-and-feel of your Tripal site without customization being needed.
+
+Additionally, the results page, waiting pages and the alignment section of the results page have their own template files (``blast_report.tpl.php``, ``blast_report_pending.tpl.php``, and ``blast_report_alignment_row.tpl.php``, respectively) which can easily be overridden in your own theme providing complete control over the look of the BLAST results.

docs/index.rst

@@ -7,3 +7,4 @@ Tripal BLAST Documentation!
    :caption: Contents:
 
    user_guide
+   dev_guide