Tripal Demo Tree module
-----------------------
This module has been developped during the Tripal Hackathon at PAG 2017 in San
Diego. It is a simple example that displays a tree from Chado table phylonode
using D3JS. It renders the tree that has the phylotree_id "1" (value hardcoded
into theme/tripal_dt.theme.inc) at the URL "<www.yoursite.org>/tripal_dt/".
An example dataset is provided and can be loaded into Chado:
% INSERT INTO phylotree VALUES
    (1,  1, 'Banana testing tree', 1, NULL, 'A tree for testing.');
% INSERT INTO phylonode VALUES
    (1, 1, NULL, 1, 14, 1, NULL, 'Musaceae', NULL),
    (2, 1, 1, 2, 9, 1, NULL, 'Musa', NULL),
    (3, 1, 1, 10, 13, 1, NULL, 'Ensete', NULL),
    (4, 1, 2, 3, 8, 1, NULL, 'Eumusa', NULL),
    (5, 1, 4, 4, 5, 1, NULL, 'acuminata', NULL),
    (6, 1, 4, 6, 7, 1, NULL, 'balbisiana', NULL),
    (7, 1, 3, 11, 12, 1, NULL, 'lasiocarpa', NULL);

Here is how this tree looks like (with left and right indices arround labels):

       1#Musaceae#14
        /       `°°°°°°°°°°°\
    2#Musa#9             10#Ensete#13
       |                     |
    3#Eumusa#8           11#lasiocarpa#12
       |   `°°°°°°°°°\
    4#acuminata#5  6#balbisiana#7

We used the tripal_example module as a skeleton that we modify. We only kept a
couple of files we needed and dropped the rest.

First we copied the example module where modules are installed:
$ cd <drupal_sites_directory>/all/modules/
or
$ cd <drupal_sites_directory>/<your_sub_site_directory>/modules/
then 
$ cp -r tripal/tripal_example tripal_dt
$ cd tripal_dt

Then, in order to have Drupal detecting our module, we needed to rename the
files we used:
$ mv tripal_example.info tripal_dt.info
$ mv tripal_example.install tripal_dt.install
$ mv tripal_example.module tripal_dt.module
$ mv theme/tripal_example.theme.inc theme/tripal_dt.theme.inc
$ mv theme/templates/tripal_example_base.tpl.php  theme/templates/tripal_dt_tree_page.tpl.php
$ mv theme/css/tripal_example.css theme/css/tripal_dt.css
And we added 2 javascript files:
- theme/js/d3.min.js: 
- theme/js/d3.dndtree.js

Then we modified the content of the files.

How this module works?
When you access the URL "/tripal_dt/", Drupal will know, through our
implementation of the "hook_menu", that we handle this URL. Drupal will call
the "theme()" function and give it the parameter "tripal_dt_tree". We could
have used our own custom function rather than the "theme()" one but it would
have been less interesting for this example and we would also prevent other
module to interact with our module at the same time. When we use the "theme()"
function, Drupal can call other hooks that enables other module to interact with
our module and maybe enrich the content.

The "theme()" function uses data generated by the implemntations of hook_theme,
like our "tripal_dt_theme()" implementation. This data is cached so each time
you modify your hook implementation, you may need to clear the theme cache.
So, the "theme()" function will have a look into our key 'tripal_dt_tree' and
see that it should use the template file "tripal_dt_tree_page" + ".tpl.php" in
the directory "$path/theme/templates" where $path will be replaced by the
tripal_dt module path.

But before processing that template file, it will prepare the data that will be
used by that template by calling any implementation of the hook
"hook_preprocess_tripal_dt_tree" (where "tripal_dt_tree" comes from the key
of the theme hash). Since we implemented that hook through
"tripal_dt_preprocess_tripal_dt_tree" in "theme/tripal_dt.theme.inc", it will be
called. In that function, we compute the required stuff and we store the
results into the $variables hash. Each key of that hash will become a PHP
variable that we will be able to use inside the template file. So
"$variables['tree']" in this function will become "$tree" in the template
"theme/templates/tripal_dt_tree_page.tpl.php".

Finally, the template "theme/templates/tripal_dt_tree_page.tpl.php" is processed
and the resulting HTML code generated will be returned by the "theme()" function
to Drupal that will display the result on the corresponding site page.

The client web browser will display the page and execute the
javascript/jQuery/D3JS code to render the tree.