Tripal Developer's Handbook
From GMOD
This document is currently under construction
Contents
|
Introduction
Tripal provides two Application Programming Interfaces (APIs) that allows developers to interact and customize Tripal and Chado content:
- Tripal Themeing API: allows customization of the look-and feel of the site through API function calls and template files.
- Tripal Module Development API: allows addition of new or custom functionality through module development.
The Themeing API provides an interface for developers who want to change the look-and feel of their site. These developers may not necessarily want to create new modules, but want to customize how their data is presented. The first section in this handbook describes how to use the API to make such changes. A knowledge of Chado and the relationships between tables is necessary to understand the Themeing API.
The Module Development API provides an interface for module developers to interact with the Chado database as well as the other Tripal core functionality such as jobs management, working with materialized views, and generating in-house vocabularies. An in-depth understanding of the Drupal API and Drupal module development is required.
If you find details in this document lacking, please subscribe to the Tripal mailing list and let us know!
Theming API
Skills Required
In order to use the Tripal Theming API to customize templates the developer should have the following skills:
- Knowledge of PHP
- Knowledge of Chado and relationships between tables (at least tables where data of interest is stored).
- Understanding of the Tripal Theming API
- Understanding of how Drupal theming works
Brief Introduction to Drupal Theming
Drupal is designed to allow for relatively easy changes to the look-and-feel of the website. PHP code dedicated to the user presentation is intended to be housed in special template files for site developers to customize. The Drupal package comes with several themes as part of the default offering, however thousands of user-contributed themes are available for site-developers to download, install, and almost instantly change the look and feel of their sites. A Drupal Theme repository is available for searching user-contributed themes.
Each theme is physically a directory within the Drupal site that contains a set of PHP template files, JavaScript and CSS files. Some of the files in the theme directory are required and some are named according to Drupal naming styles so that Drupal can properly find them. For an in-depth overview of theming within Drupal, please see the Drupal Theming Guide.
Introduction to the Tripal Theme
The Tripal v0.6x-0.3.1b package comes with a base theme. A base theme is one which is not intended to be used as the default theme for the site, but rather provides a set of supportive templates for the default theme. The screen shot below shows the Drupal theme administration page (Administer → Site Building → Themes) of a demo Tripal installation. As shown in the screen shot below, the Tripal theme is enabled, but is not default. In the example screen shot, the Sky theme is default. Thus the primary look-and-feel of the site is controlled by the Sky theme, and the Tripal theme only provides a look-and-feel for Chado-based content:
Structure of the Tripal Theme Directory
In a typical Drupal installation, the Tripal theme is installed in the directory:
/[drupal dir]/sites/all/themes/theme_tripal
Inside of the Tripal theme are the following files and directories:
- tripal.info: a file required by Drupal to identify the theme and specify location of theming components
- logo.png: a file of the Tripal logo seen when viewing the Drupal Theme administrative page
- node.tpl.php: a default template file used for Tripal derived content when no other template is available. In practice this file is currently not used as each content type created by Tripal has template file.
- node-[content type].tpl.php: a series of PHP template files use to theme specific Chado content, where [content] is the name of a content type such as 'feature', 'library', etc. These names correspond to the same content types available when creating new content in Drupal.
- tripal_[content type]: a series of directories with sub templates for each Chado content type.
- js: a directory that houses all of the javascript files for the theme. Each Tripal module has its own Javascript file.
- css: a directory that houses all of the CSS files for the theme. Each Tripal module has its own CSS file.
- images: a directory for storing images referenced by any of the template files.
Tripal Content Types Themes
Each content type in Drupal, also called a node, has a programmatic name. And, when Drupal shows a content type (or node) for display it attempts to find an appropriate theming template file by using the programmatic name of the node for a file named in the following way:
node-[content type].tpl.php
where [content type] is the programmatic name of the node type. You can find the names of all content types in Drupal by navigating to the administer content page: Administer → Content Management → Content Types (screen shot below). A listing of all available content types is provided and the programmatic name is given in the 'type' column of the table.
For the core Tripal package, the following content type names are available:
- chado_analysis
- chado_feature
- chado_library
- chado_organism
- chado_stock
Additionally, several commonly used extension modules have the following content type names:
- chado_analyis_blast (Blast Analysis Extension)
- chado_analysis_interpro (Interpro Analysis Extension)
- chado_analysis_kegg (KEGG Analysis Extesion)
- chado_analysis_unigene (Unigene Analysis Extension)
For any Tripal content type, either from the base Tripal package or a Tripal extension a template file should be available for customization. As described previously, the names of these template files follow the naming scheme: node-[content type].tpl.php, where [content type] is the programmatic name of any Tripal content type. For example, the node-chado_feature.tpl.php file is the template file for the chado_feature content type.
Drupal's Theme Search Path
By default, Drupal will search for a node's template file by first looking in the module directories. Tripal does not house any theme template files in modules. Next, Drupal searches the enabled Tripal base theme and if it finds an appropriate template will use it. However, if a template of the same name exists in the current default theme that template file takes precedence.
| Best Practice Tip. It is best to always copy any templates files out of the Tripal theme directory into your default theme for editing. This way, future upgrades to Tripal, that may have change the default theme layout will not affect customizations to your site look-and-feel. |
Layout of a Tripal Node Template
Each content type provided by Tripal follows the same layout pattern. Below is a screen shot of an organism page (chado_organism content type) from the Citrus Genome Database.
In the screen shot above, there are two distinct regions added by the Tripal templates. The first is the main content section on the left-hand side of the middle of the screen. This section provides a display of the data. The second region is the right sidebar that lists additional Resources for this content type. This layout structure is created in the node-[content_type].tpl.php template file for each node (for this example, the node-chado_organism.tpl.php template). A more in depth description of the code in this file will be provided next. All of the node template files follow this same structure
|
| Best Practices: If you would like to maintain this layout structure for any themes of new content types for new Tripal extensions, you will want to follow this same structure in your template files. See the next section for more details. |
Dissecting a Tripal Node Template File
Template Basics
All of the Tripal node templates are identical in structure, although each one is suited for the content it serves. Therefore, to demonstrate the layout of the Tripal node templates, this guide will use the chado_feature content type template as the example. In order to understand where and how to edit the node template files, the various sections of the chado_feature template will be shown and explained. The following descriptions assume some familiarity with the PHP language.
Each content type in Tripal corresponds roughly to a table module in Chado. For a listing of Chado modules, see this page: http://gmod.org/wiki/Chado_-_Getting_Started#Modules. It is normally easy to identify which Tripal module, and hence which content type corresponds to each Chado module as the naming is consistent (i.e. Tripal stock module and 'chado_stock' content type correspond to the Chado stock module). One exception is the Tripal feature module and the 'chado_feature' content type, which was inadvertently named 'chado_feature' in Tripal.
Tripal exports automatically the data needed for each content type template. Drupal makes a $variables associative array available to all templates, and Tripal adds data to this variable. Thus, in the 'chado_feature' template, the following line appears near the top of the template:
$feature = $variables['node']->feature;
Using the node ID of the chado_feature node, Tripal queries the feature table of Chado, as well as those linked by foreign key constraints, and adds the results to the $variables['node']->feature array. In the example code above, this is simplified to a variable named $feature.
Layout Sections
As mentioned previously, the node template files have two major regions:
- a details section
- a resources sidebar.
In the template file, each of these sections is defined by div tags with special CSS class names. First is the details section:
<div id="tripal_feature_details" class="tripal_details">
<!-- Basic Details Theme -->
<?php include('tripal_feature/tripal_feature_base.tpl.php'); ?>
<!-- Database References -->
<?php include('tripal_feature/tripal_feature_references.tpl.php'); ?>
<!-- Properties -->
<?php include('tripal_feature/tripal_feature_properties.tpl.php'); ?>
<!-- Synonyms -->
<?php include('tripal_feature/tripal_feature_synonyms.tpl.php'); ?>
<!-- Sequence -->
<?php
if(strcmp($feature->type_id->name,'scaffold')!=0 and
strcmp($feature->type_id->name,'chromosome')!=0 and
strcmp($feature->type_id->name,'supercontig')!=0 and
strcmp($feature->type_id->name,'pseudomolecule')!=0)
{
include('tripal_feature/tripal_feature_sequence.tpl.php');
}
?>
<!-- Formatted Sequences -->
<?php include('tripal_feature/tripal_feature_featureloc_sequences.tpl.php'); ?>
<!-- Relationships -->
<?php include('tripal_feature/tripal_feature_relationships.tpl.php'); ?>
<!-- Feature locations -->
<?php
if(strcmp($feature->type_id->name,'scaffold')!=0 and
strcmp($feature->type_id->name,'chromosome')!=0 and
strcmp($feature->type_id->name,'supercontig')!=0 and
strcmp($feature->type_id->name,'pseudomolecule')!=0)
{
include('tripal_feature/tripal_feature_featurelocs.tpl.php');
}
?>
<?php print $content ?>
</div>
In the example code above, taken from the node-chado_feature.tpl.php file, a div block is created with a unique id name of tripal_feature_details and the CSS class name is tripal_details. It is the assignment of the CSS class tripal_details that gives this details box the styling seen on all Tripal node pages.
Also, within this div block are several include statements one of which is as follows:
<?php include('tripal_feature/tripal_feature_base.tpl.php'); ?>
These includes instruct Drupal to load subtemplates. These subtemplates are used to house the code for subcontent and are intended to keep the primary node template concise and from becoming excessively long. More on these subtemplates is described in a later section.
By default, some conditional logic is present in the template for filtering large datasets. For example, the following if statement only includes the tripal_feature_sequence.tpl.php subtemplate if the feature type is not a scaffold, chromoosme, supercontig or pseudomolecule. This is because those datasets typically have very large sequences that would be too slow for the page.
<!-- Sequence -->
<?php
if(strcmp($feature->type_id->name,'scaffold')!=0 and
strcmp($feature->type_id->name,'chromosome')!=0 and
strcmp($feature->type_id->name,'supercontig')!=0 and
strcmp($feature->type_id->name,'pseudomolecule')!=0)
{
include('tripal_feature/tripal_feature_sequence.tpl.php');
}
?>
Finally, the resources side-bar is the last thing defined in the default node templates. The code is as follows:
<div id="tripal_feature_toc" class="tripal_toc"> <div id="tripal_feature_toc_title" class="tripal_toc_title">Resources</div> <ul id="tripal_feature_toc_list" class="tripal_toc_list"> </ul> </div>
Here, the div block is given a unique name of tripal_feature_toc and the class defined is tripal_toc. This tripal_toc class is responsible for theming the resources sidebar to look the way it does. Additionally, the title of the side bar is provided in the div block with the class tripal_toc_title and an empty HTML list block, ul tag, with the class tripal_toc_list appears below. This empty list is where the list of resources will appear.
You can add custom link to the resources side-bar by simply adding as elements of the the tripal_toc_list block. For example, the following screen shot shows the resources sidebar on an organism page of the Citrus Genome Database. The JGI Genome Assembly v0.9 link shown in the screen shot is a custom link manually added to the template file, as well as the External Links section towards the bottom. The code to add these links is as follows:
|
<div id="tripal_organism_toc" class="tripal_toc">
<div id="tripal_organism_toc_title" class="tripal_toc_title">Resources</div>
<ul id="tripal_organism_toc_list" class="tripal_toc_list">
<?php if($organism->species == 'clementina'){?>
<li><a href="/species/clementina/genome0.9">JGI Genome Assembly v0.9</a></li>
<?php } ?>
<?php if($organism->species == 'sinensis'){?>
<li><a href="/species/sinensis/genome1.0">JGI Genome Assembly v1.0</a></li>
<?php } ?>
</ul>
<b>External links</b>
<ul>
<?php if($organism->species == 'clementina'){?>
<li><a href="http://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi?mode=Undef&name=Citrus+clementina&lvl=0&srchmode=1" target="_blank">NCBI</a></li>
<li><a href="http://www.ars-grin.gov/cgi-bin/npgs/html/taxon.pl?314344" target="_blank">GRIN</a></li>
<?php } ?>
<?php if($organism->species == 'sinensis'){?>
<li><a href="http://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi?mode=Undef&name=Citrus+sinensis&lvl=0&srchmode=1" target="_blank">NCBI</a></li>
<li><a href="http://www.ars-grin.gov/cgi-bin/npgs/html/taxon.pl?10782" target="_blank">GRIN</a></li>
<li><a href="http://www.eol.org/pages/582206" target="_blank">Encylopeida of Life</a></li>
<li><a href="http://www.ncbi.nlm.nih.gov/nuccore/114329635?report=graph">Chloroplast genome</a></li>
<?php } ?>
<?php if($organism->species == 'trifoliata'){?>
<li><a href="http://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi?mode=Undef&name=Citrus+trifoliata&lvl=0&srchmode=1" target="_blank">NCBI</a></li>
<li><a href="http://www.ars-grin.gov/cgi-bin/npgs/html/taxon.pl?29344" target="_blank">GRIN</a></li>
<?php } ?>
</ul>
</div>
|
Notice in the example code the link for the genome assembly appears in the ul block with the class tripal_toc_list. This ensures that the custom links will appear in the list where other Chado content is added. But notice that the External links appear as a separate ul block. The additional content links do not get added to this second ul block and therefore it appears below.
- Summary
In Summary, each node template file has two major sections:
- a div block defined with a class of tripal_details to serve as the container for content
- this section contains include statements for subtemplates and logic to include subtemplates under different conditions.
- a div block defined with a class of tripal_toc to serve as the resources side bar
- a title for the resources sidebar defined by a block with a class of tripal_toc_title
- a list section for the resources sidebar defined by a block with a class of tripal_tocl_list
|
| Best Practices: A Tripal compatible template file should only have one div block for the details region and one block the resources side bar: tripal_details and respectively. |
Subtemplates
In the template layout section described previously it was shown how subtemplates are incorporated into the principle template file. These subtemplates are included using PHP include statements within the details div block. For the feature content type the following subtemplates are available:
- tripal_feature_base.tpl.php
- tripal_feature_featureloc_sequences.tpl.php
- tripal_feature_featurelocs.tpl.php
- tripal_feature_libraries.tpl.php
- tripal_feature_properties.tpl.php
- tripal_feature_references.tpl.php
- tripal_feature_relationships.tpl.php
- tripal_feature_sequence.tpl.php
- tripal_feature_synonyms.tpl.php
- tripal_feature_teaser.tpl.php
The following templates will also be available for the chado_feature content type if the GO, Blast, KEGG, Interpro and Unigene Extension modules are installed:
- tripal_feature_go_terms.tpl.php
- tripal_feature_blast_results.tpl.php
- tripal_feature_interpro_results.tpl.php
- tripal_feature_kegg_terms.tpl.php
- tripal_feature_unigenes.tpl.php
Each of these subtemplates adds to the details section of the page a specific category of data. For example, the tripal_feature_synonyms.tpl.php template will add a listing of synonyms for the feature. And the tripal_feature_references.tpl.php template will add a listing of external reference for the feature. Both of these data are extracted directly from tables in Chado through foreign key relationships. By default, the first subtemplate included in the details section is displayed when the page is first loaded. Content from the other subtemplates are then visible by clicking the links in the resources side bar. These links are added automatically for all subtemplates to the sidebar using Javascript described in the next section.
|
| Best Practices: By convention, the default subtemplate (the one listed first) should have the word base in the template name. This is to easily identify it as a type of "home page" for the content type. |
All subtemplates for a content type should be stored in a directory with a similar name as that of the content type. For the chado_feature content type, a 'tripal_feature' directory exists. Any subtemplate intended to incorporate data into the chado_feature template should be housed in this directory. The same is true for all content types.
Each subtemplate file follows the same structural layout:
- A top section where variables are defined
- A div block of class tripal-info-box to define the container for the content. All data should be displayed within this block.
- Two internal div boxes:
- One to identify the title of the container with a class of tripal-info-box-title
- One to provide a description of the content of class of tripal-info-box-desc
The following code taken from the tripal_feature_base.tpl.php template
<div id="tripal_feature-base-box" class="tripal_feature-info-box tripal-info-box"> <div class="tripal_feature-info-box-title tripal-info-box-title"><?php print $feature->type_id->name ?> Details</div> <div class="tripal_feature-info-box-desc tripal-info-box-desc"></div> [.... additional content here ....] </div>
Node Template JavaScript
The content from subtemplates is substituted by PHP into the location in the primary template file where they are included. However, despite all of the include statements in the details div block, not all of the content appears at one time on the page. Only content from one subtemplate will be shown at a time. The Resources sidebar on the right is used for interactive cycling through the content contributed by each subtemplate. This behavior is controlled by JavaScript and CSS classes to be explained in the following section.
<script type="text/javascript">
if (Drupal.jsEnabled) {
Drupal.behaviors.organismBehavior = function (context){
// hide all tripal info boxes at the start
$(".tripal-info-box").hide();
// iterate through all of the info boxes and add their titles
// to the table of contents
$(".tripal-info-box-title").each(function(){
var parent = $(this).parent();
var id = $(parent).attr('id');
var title = $(this).text();
$('#tripal_feature_toc_list').append('<li><a href="#'+id+'" class="tripal_feature_toc_item">'+title+'</a></li>');
});
// when a title in the table of contents is clicked, then
// show the corresponding item in the details box
$(".tripal_feature_toc_item").click(function(){
$(".tripal-info-box").hide();
href = $(this).attr('href');
$(href).fadeIn('slow');
// we want to make sure our table of contents and the details
// box stay the same height
$("#tripal_feature_toc").height($(href).parent().height());
return false;
});
// we want the base details to show up when the page is first shown
// unless the user specified a specific block
var block = window.location.href.match(/[\?|\&]block=(.+?)\&/)
if(block == null){
block = window.location.href.match(/[\?|\&]block=(.+)/)
}
if(block != null){
$("#tripal_feature-"+block[1]+"-box").show();
} else {
$("#tripal_feature-base-box").show();
}
$("#tripal_organism_toc").height($("#tripal_feature-base-box").parent().height());
};
}
</script>
