The following documentation provides instructions for creating a Tripal extension module. Anyone can create a module for Drupal or a module that interacts with Chado. But, if you would like your module to be considered a fully-fledge Tripal extension module the following criteria should be met.
All Tripal modules follow a standard directory strucutre. Below is a sample directory tree from the tripal_pub module. While this is not an extension module, it demonstrates the directory strucutre that all Tripal modules should follow:
/api /files /includes /theme /theme/css /theme/js /theme/[other module name] /views/handlers [module name].drush.inc [module name].info [module name].install [module name].module [module name].views.inc README.txt
Where [module name] is the name of your extension module. The meaning of the directories and files is as follows:
- /api: This directory is for PHP include files that provide API functions that your module will provide.
- /files: This directory is for any type of non PHP file that is required by your module. Drupal code standards require that 3rd party libraries not be included with modules so be careful not to include any 3rd party libraries here. Simply include files created for your module.
- /includes: This directory is for PHP include files that do not provide API functions but allow you to compartmentalize your code and keep it easy to read
- /views/handlers: If you create any new handlers for Drupal views they should go in this directory.
- [module name].drush.inc: This file is for creating Drush commands that can be used on the command-line to help manage your extension.
- [module name].info: This is the Drupal .info file that comes with all Drupal modules.
- [module name].install: This is the Drupal .install file that comes with all Drupal modules.
- [module name].module: This is the Drupal .module file that comes with all Drupal modules.
- [module name].views.inc: This is the file that allows your module to integrate with Drupal Views, such as providing default views related to your module.
- README.txt: The README.txt file contains information about the module as well as any specific installation instructions, such as for 3rd party libraries.
Requirments for the Module .info file
When creating your Tripal extension module you will need to have a .info file that indicates to Drupal the name of your module, dependencies and module version. At a minimum, all Tripal extension modules should have the following variables in their .info files:
- package = Tripal Extensions
- version = [drupal major version].x-[module major].[module minor]-tripal_v[tripal version]
- dependencies = tripal_core
All Tripal extension modules should have a package name set to 'Tripal Extensions'. This allows all extension modules to be grouped together when viewing the module list.
The version number of the extension module has three parts that follow the instructions provided provided by Drupal (http://drupal.org/node/467026). These three parts include the Drupal version, your module version and the Tripal version. It is in the format:
[drupal major version].x-[module major].[module patch level]-tripal_v[tripal version]
Where [drupal major version] is the Drupal number (e.g. 6, 7 or 8). Your module version has two numbers separated by a period. The first is the major release number. As you create new releases for your module you can increment this number. You should start with a major version of 1. The [module patch level] number should start with 0 and should be incremented each time you release a new version of your module with specific bug fixes, but no major imporvements. Finally, the '-tripal_v[tripal version] is attached to the end to indicate the version of Tripal your module is compatible with. An example version number could be:
Requirements for the .install file
The .install file allows your module to prepare the site for your module. Here you can create new database tables, create directories, etc. Tripal requires all extension modules to perform the following
- First, all modules should create a directory for any files that may need to be made available for download. use the tripal_create_moddir() API call to do this in the hook_install() function.
- If your extension module will be managing data in the Chado analysis tables for a specific analysis and will provide a new node type for that analysis (e.g. blast, KEGG, InterProScan etc..) you must register your new analysis node type using the tripal_analysis_register_child() API call.
Use of the Tripal API to Interact with Data in Chado
In order for a module to be considered a full Tripal module it should use the Tripal API to query, insert or update records into Chado. The Tripal API is documented online. Here is a quick link to the Chado API portion of the Tripal API: http://tripal.info/sites/default/files/tripal_v1.0_api/d5/db8/group__tripal__chado__api.html
At a minimum, the chado_query() function should be used, rather than Drupal's db_query() when executing any SQL statement that will use tables in Chado. But, there are several other API function calls for selecting, inserting, updating and deleting records in Chado that are preferred over SQL when possible:
See the API documentation for specific use of these functions. Also, please take time to review the API function calls. There may be the case that an API function already exists for what you'd like to do. Feel free to email the Tripal developers mailing list if you have questions about the API or would like to suggest a new function.
Add Your Project to a Drupal's GIT
If you would like to share you module with others you should create an account on the Drupal website and create a Drupal Sandbox project following these instructions: http://drupal.org/node/1068950. By using GIT to manage your coding it will be easier to share your module and have it reviewed.
Follow Drupal Coding Standards
All Tripal modules should follow standard Drupal coding standards. You can check your module to see if it follows coding standards by using the Coder module: http://drupal.org/project/coder. You can install this module into your development site and use it to ensure your module follows common Drupal coding standards. You can find a list of coding standards on this page: http://drupal.org/coding-standards. Additionally, you can check your module for proper coding standards using Ventral reviewer: http://ventral.org/pareview (you must have your module in the Drupal Sandbox).
List your Module on Tripal's site
After your module is complete and you would like to share it, please email the Tripal Developer's mailing list. The Tripal developers will work with you to make your module accessible via the Tripal website.