Add a New Custom Pane Template

Page Sections

As mentioned in a previous section, the Tripal core template provides a page layout that includes a table of contents sidebar and a main section where "panes" of content are displayed.  When the links in the sidebar are clicked, the corresponding content pane appears.  The content displayed in each pane is derived from a template file (as described previously).  Tripal provides many templates for commonly used data types in Chado, however, it may be necessary to create your own template for custom data views.   There are two primary methods to add new custom templates to a page.  The first method requires adding a new template file to your existing theme and informing Drupal that it exists.   The second method is to create your own custom module in which your templates can be housed.  This section describes how to add templates using the first method by directly adding a template your site's theme directory.  To demonstrate how to add a custom pane we will assume that the site developer would like to add a new 'Gene Groups' link on the sidebar of a Feature page that contains gene information.  

Create The template

The first step to create a custom pane is to create the template file that will provide the content needed.   Before creating your template file, plan where you would like these template files to reside.  A suggestion is to create a templates directory inside of your theme.  All customized template files can reside in that directory.  Because we want to add a new template that should appear on the Feature page we'll name the template with a prefix of 'tripal_feature'.  The full name for this example will be,  tripal_feature_gene_groups.tpl.php, and the location will be

[theme directory]/templates/tripal_feature_gene_groups.tpl.php

Where [theme directory] is the path to your site's theme.   Also, the prefix 'tripal_feature' is not required for adding a pane to the Tripal Feature content type. It's just used for convenience to help identify where the template will provide its content.   The suffix .tpl.php in the template file name is required.   It is inside of this file that the site developer can add custom PHP code that will be displayed on the desired page.   To learn how to use the Tripal API to access content from Chado within the template, please see the Tripal Developers Handbook--a section of this guide.

The Theme's template.php File

Now that we have our template file we need to inform Drupal of its existence.  Each theme comes with it's own template.php file.  It is in this file that we can inform Drupal of our new template.  We will need to add three new PHP functions, or hooks, that Drupal recognizes.    For this example we will assume that the site's default theme is garland. Thus, the prefix for the functions described below is the theme name garland.  However, you should substitute the name of your site's theme as the prefix for these functions.

The first step is to create an instance of the Drupal hook:  hook_theme_registry_alter().  We will add an entry to the theme_registry associative array that will inform Drupal of our new template.  The following code provides an example implementation.  The meaning of each key/value pair in the associative array is explained using in-line comments:

/**
 * Override the theme registry.
 */
function garland_theme_registry_alter(&$theme_registry) {
  $theme_registry['tripal_feature_gene_groups'] = array(
    // We want to pass into the template the node variable. This will
    // provide access to properties of the page as well as content form
    // Chado (e.g. feature data) that has been attached to the node.
    'variables' => array('node' => NULL),
    // The name of the template (this is the template file name without
    // the .tpl.php extension).
    'template' => 'tripal_feature_gene_groups',
    // The path where the template file is stored.  We use the
    // Drupal API function drupal_get_path() to retrieve the 
    // path to the 'garland' theme rather than hard-code it.  For
    // our example, we're placing the template files in a subfolder
    // named 'templates':
    'path' =>  drupal_get_path('theme', 'garland') . '/templates',
    // The following keys are set as defaults:
    'theme path' => '',
    'type' => 'module',
    'preprocess functions' => array(),
    'process function' => '',
  );
}
Next, we need to tell Drupal where our new template should be used.  We can do this by using Drupal's hook_node_view_alter() hook.  The inline comments explain the meaning of each line.
 
/**
 * Adds custom templates to a node.
 */
function garland_node_view_alter(&$build) {

  // Check to see if this the Tripal Feature content type.  This has a 
  // bundle name of 'chado_feature'.
  if ($build['#bundle'] == 'chado_feature') {

    // We only want to show our template on full page views (not on teaser views).
    // If this is not a full page then return.
    if ($build['#view_mode'] != 'full' OR array_key_exists('tripal_feature_gene_groups', $build)) {
      return;
    }

    // The following addition to the $build argument will add the content
    // provided by our template to the page.  Here we indicate the name of
    // the theme (this is the same name we used in the 
    // hook_theme_registry_alter() function above.  
    $build['tripal_feature_gene_groups'] = array(
      '#theme' => 'tripal_feature_gene_groups',
      // We indicate in the hook_theme_registry_alter() function that our
      // template would accept a node variable. Here we set it. 
      '#node' => $build['#node'],
      // So that this content page shows up on the Tripal TOC sidebar
      // we need to add a unique ID and a human-readable title.  
      '#tripal_toc_id' => 'gene_groups',
      '#tripal_toc_title' => 'Gene Groups',
    );
  }
}
The bundle name for each content type is a combination of the prefix 'chado_' and the Chado table where the data is coming from.  For example, the content type for data housed in the Chado stock table will be 'chado_stock', for publications the content type is 'chado_pub', etc.
 
Finally, we need to make sure that our implementation of the hook_node_view_alter() above is called before Tripal tries to create the table of contents for the sidebar.  To do this we can use Drupal's hook_module_implements_alter() to tell Drupal to load our function first:
 
/**
 *
 */
function garland_module_implements_alter(&$implementations, $hook) {
  // Move processing of the garland_node_view_alter() before the
  // processing of the tripal_core_node_view_alter() hook so
  // we can get in our changes before Tripal builds the TOC.
  if ($hook == "node_view_alter") {
    $implementations = array('garland' => FALSE) + $implementations;
  }
}
Note:  be sure to change the occurance of the theme name 'garland' in the code above to the name of your default theme.      
 
The last step is to clear Drupal's cache.  You can do this through the website by Navigating to Configuration -> Peformance or by issuing the following Drush command:
 
cd [drupal dir]
drush cc all
 
Where [drupal dir] is the path where Drupal is installed.  
 
If your template generates HTML then you can visit a feature page and see the 'Gene Groups' link in the sidebar.  For this example, we would need to ensure that we customize the template file so that HTML is only generated for 'gene' types and not for other feature types (such as SNPs, markers, etc.).