Sharing Your Custom Modules

Page Sections

Tripal has been designed to facilitate sharing of code, modules, themes, etc. between different groups.   If you find that you are creating custom modules and themes for your Tripal site and you feel that what you are creating may be useful or help other groups please consider sharing your modules with others. However, some design decisions should be considered to more easily share code.  This section provides some tips and suggestions for design to help with sharing

Be Active in the Tripal Developers Community

The best way to ensure your custom modules or themes are of use to others is to be active in the Tripal Developer's community.  The community consists of Tripal core developers, and site developers who communicate via monthly developer conference calls and via a dedicated developers mailing list.  Any topic related to site setup, development of new custom extension modules, and direction of the core code of Tripal is typically discussed, and collaborations on development can be made.  You can subscribe to the Tripal developer's mailing list by following the links for the mailing list on the support page of the Tripal.info website.  Additionally, you can find archived meeting notes from past developer meetings on the support page as well.

How to Share Your Modules

Before releasing your module, please communicate with the Tripal Developer's Group to let others know about your efforts (you may find collaborators). To share your modules, please request an account on the Tripal.info website by sending an email to the Tripal Developers Mailing list.   Once given access, you can then create a page on the Tripal.info site that advertizes your new module.  Your module will also be visible as installable on every other Tripal website in the world.   

Development Tips for Custom Modules

Think Generic and Plan Long-Term

Custom modules typically have specific needs that are required by the site.  The site may require custom visualization, custom search tools, custom page displays, custom data loaders, etc.  Sometimes these customizations require use of 3rd party tools, JavaScript libraries, etc.  Before designing your custom module, consider which needs are truly unique to your site and which are more generally applicable for other sites.   Also, before implementation consider the long-term goals for the module.  It is undesirable to discover your code must be rewritten because it doesn't meet new needs. Try to anticipate as many future expectations as possible.  As part of this long-term plan, consider how others may want to use your shared module, or how they may want to customize if the "generic" functionality you provide isn't quite enough for them.  

Use Drupal Coding Standards

It is important that your custom modules are readable by others.  The best way to avoid this is to follow Drupal coding standards.  You can find coding standards described here: https://www.drupal.org/coding-standards.  These ensure that all of us create code in a similar readable way.  

Write Secure Code

Drupal provides a set of functions and coding standards to help ensure code is secure from common hacking methods.  If the Drupal API is properly used then the security burden can be handled primarily by Drupal. You can find information about writing secure Drupal code on the following pages: https://www.drupal.org/writing-secure-code.

Use Inline Doxygen Documentation

The Tripal core modules use inline code comments that meet two needs:  code readability, and online documentation.  The Doxygen commenting style is recommended by Drupal for inline code comment.  You can find information about how to use Doxygen in your code here: https://www.drupal.org/coding-standards/docs.  By using Doxygen, Tripal commenting follows a uniform method and it enables creation of online documentation such as the Tripal API pages.  If you use Doxygen style commenting your code will follow the same commenting style as Tripal, it will be more readable, and it will allow you (and others) to create readable online documentation for your module.

Use the Drupal API

Unfortunately, Drupal has a somewhat lengthy learning curve.   The best recommendation is to purchase a book to walk you through all of API functions and hooks that are used for constructing a module.  It can be tempting to forge on using experience with PHP to create modules.  However, doing so may result in a module that may be difficult for others to customize, or to update in the future.  Drupal typically does not maintain backwards compatibility between major upgrades (E.g. from Drupal 6 to 7 and 7 to 8).  However, proper use of Drupal API and hooks should help reduce the time needed to upgrade modules for use by future major releases of Drupal.   Some useful tips include:

  • Avoid writing HTML inside of module code.  One of the core principles of Drupal is that everyone should have complete control of their site.  Writing HTML inside of a module forces the user of you module to follow the style you have set.  Always try to fit your HTML inside of a template files. This allows for complete control by the user.  In some cases, however, you may need to use HTML to force a style that must be static. In this case, consider using theme hook function as supported by Drupal.
  • Never put HTML styles in module code or theme templates.   Always use a Cascading Style Sheet (CSS) when styling your output.   This allows site developers to tweak your module to match the look-and-feel of their site.  Avoid the temptation to add style directly into code as a "quick" test that you will fix later. Odds are the fix will not happen.  Try to prefix any HTML IDs or names used by your CSS with the module name to avoid naming conflicts with other modules.
  • Always use Drupal's Form API when creating editable forms (do not try to hard code the HTML for forms).
  • Use Druapl's theme hooks for creating tables and lists (do not try to hard code the HTML for these).
  • Use the security functions to help reduce security vulnerabilities in your code.

Use the Tripal API

The Tripal API provides common functions primarily for access to Chado.  You can use the API to select, insert, update and delete records from any Chado table.  It also provides functions that support the jobs management system, materialized views, custom tables and more.  Using the Tripal API ensures compatibility with other Tripal sites.  The Tripal developers are committed to maintain backwards compatibility (despite Drupal major upgrades) for the API, thus use of the API should help with long-term manageability of your code.  You can find examples for how to use the Tripal API in the Developer's Handbook section of this user's guide.  Additionally, the Tripal package comes with an example module that provides a framework for starting your own custom module.  It includes the most commonly used Drupal hooks and makes proper use of the Tripal API for the most common functionality.

There are times, however, when the Tripal API can not be fully used.  When SQL queries become very complex, such as multiple joins, performance may be improved by writing SQL rather than using the API functions for selecting, inserting, updating or deleting records.  Data loaders can improve performance by using SQL rather than the API functions.  But, when possible, module developers should strive to use the Tripal API functions when working with data in Chado.

No SQL in Template files

The Tripal Developer's Handbook describes how to use the Tripal API inside of Template files.  To ensure readability, never write SQL statements inside of template files.  Template files should always be given all the data they need to layout content, or they should use the chado_generate_var() and chado_expand_var() functions to expand existing Chado data variables.  If you find you must write SQL to obtain data for template files, consider writing a Drupal preprocess hook that can generate the necessary variables that can be passed to the templates.

Create Administrative Pages

Often when developing a module you have specific needs for your particular site. Sometimes these needs may only be of interest to your site. It is important not to hard-code behavior that is of no use to anyone else.  Someone who decides to use your module may be unfortunately disappointed after installing your module only to discover it forces functionality on them that they don't quite want, or enforces a look-and-feel that doesn't match their site.   To help with adoptability of your module, consider adding an administrative page that only site administrators can access.  Such a page can allow the site developer to turn on or off functionality, provide alternate configuration settings, or adjust the look-and-feel of the custom content.   Unfortunately, creating site administration pages can increase the development and release time for your module.  However, it will go a long way in ensuring your module is used by others.  Moreover, greater adoption of your module by others can help to justify future requests for project funding.  Thus the extra effort can have greater benefits long-term.

 

Use of 3rd Party Libraries and Module Dependencies

Module Dependencies

Drupal allows modules to be dependent on one another and enforces that dependent modules are already installed.   There are no restrictions on which or how many other modules your custom modules can use as dependencies.  However, reliance on other people's modules can cause problems, especially if modules upon which yours is dependent are not properly maintained or updated.  They can greatly complicate upgrade of a site from one major Drupal version to another if those dependent modules have not yet upgraded their code to support the new versions.   Therefore, it is recommended to limit the number of dependent Drupal modules that your module requires.  If you can code the necessary functionality it may be best to do that than to rely on another module to provide it.  However, if you do need to use another module, try to use those that are well supported with responsive developers.

3rd Party JavaScript Libraries

There are no restrictions on the use of 3rd Party libraries (such as JQuery, d3, AngularJS, etc).   Drupal supports use of 3rd party libraries and recommends placing the code for those libraries in the sites/all/libraries directory of your Drupal installation. It also includes some API functionality to assist with management of libraries.   Because of licensing conflicts, Drupal requires that libraries are never packaged with a module.  Users should be required to download and install 3rd party libraries separately.  If you need to use a 3rd-party library try to select those that are well documented and well maintained.  

There are a few items to consider when planing to use 3rd party libraries.   Use of 3rd party libraries can greatly decrease your development time, but it increases the installation and complexity of installation and site management for others who may use your module.   The more modules a site has installed, and the more 3rd party modules are required by those modules the more complex management becomes.  Also, if the site developer has need to customize your module, there will be some training required to use the 3rd party libraries you have selected.   Therefore, if possible, try to use 3rd party modules that are used by other Tripal developers.  This will help reduce the number of 3rd party modules site developers must learn.  By default Drupal supports JQuery, and Tripal developers have agreed to make use of the d3 library for visualizations.

Non PHP libraries

At times it may be more useful to use libraries written in other languages (e.g. Perl, Python).  There are no restrictions for using these libraries.  But the recommendation is to limit these and to not use them if possible. If you can recreate the functionality in PHP it helps reduce site complexity and management.  Non PHP libraries complicate Tripal setup because they often require systems-level setup and configuration. For example, managing Perl dependencies adds another burden to the site administrator.  A major goal for Tripal is to reduce complexity in setup and maintenance of a biological website, and server installation and management can be a major point of complication for some users.  It is therefore recommended to avoid the use of libraries in other languages (other than PHP, CSS, HTML and JavaScript) if possible.