tripal/tripal_example/tripal_example.module

<?php

/**
 * @file
 * This file contains all Drupal hooks for the module other than any
 * node hooks and block hooks. Those go in the [module name].chado_node.inc file
 * and [module_name].blocks.inc respectively
 *
 */

// EXPLANATION: include any files needed for this module.  That includes any 
// API file, the theme file, or include files.
require('api/tripal_example.api.inc');
require('theme/tripal_example.theme.inc');
require('includes/tripal_example.admin.inc');
require('includes/tripal_example.chado_node.inc');


/**
 * Implementation of hook_permissions()
 * 
 * Set the permission types that this module uses.
 * 
 * @ingroup tripal_example
 */
function tripal_example_permission() {
  
  // EXPLANATION:  here we want to setup any of the permission types
  // that this module needs.  Our exmample module creates a new
  // chado node type called 'chado_example'.  Therefore, we need 
  // permissions to view, edit, delete, create our new node type.  Additionally,
  // we want to add a permission that allows for administration of this 
  // module.  These permissions will appear in the 'People' -> 'Permissions'
  // configuration page and allow the site admin to specify which user roles
  // are allowed to perform specific actions.
  return array(
    'access chado_example content' => array(
      'title' => t('View Examples'),
      'description' => t('Allow users to view example pages.'),
    ),
    'create chado_example content' => array(
      'title' => t('Create Examples'),
      'description' => t('Allow users to create new example pages.'),
    ),
    'delete chado_example content' => array(
      'title' => t('Delete Examples'),
      'description' => t('Allow users to delete example pages.'),
    ),
    'edit chado_example content' => array(
      'title' => t('Edit Examples'),
      'description' => t('Allow users to edit example pages.'),
    ),
    'administer tripal example' => array(
      'title' => t('Administer Examples'),
      'description' => t('Allow users to administer all examples.'),
    ),
  );
}

/**
 * Implements hook_menu()
 * 
 * Specifies menu items and URLs used by this module.
 *
 * @ingroup tripal_example
 */
function tripal_example_menu() {
  $items = array();
  
  // EXPLANATION:  the $items array should be popluated to contain a list of 
  // menu items or URL callbacks that our module needs.  
  // all Tripal Extension modules shoudl provide at least these menu items:
  //  * A menu item for an administrative home page
  //  * A menu item for 'Help' documentation
  //  * A menu item for a module configuration page
  //
  // Additionally, if your module defines a custom node type that is linked
  // to a record in Chado:
  //  * A menu item for syncing drupal nodes with Chado records.   
  //    
  
  // EXPLANATION:  all extension modules should have an administrative menu item
  // with the path set to 'admin/tripal/extension/[module name]'.  This will
  // place the menu item in the 'Tripal' -> 'Extesion Modules' page.  Because this
  // is an administrative menu item we must be sure to set the 'access arguments'
  // to be 'administer tripal example' which is a permission type we created
  // in the tripal_example_permissions() function above.
  $items['admin/tripal/extension/tripal_example'] = array(
    'title' => 'Examples',
    'description' => 'Example module for help with development of new extension modules.',
    'page callback' => 'tripal_example_admin_examples_listing',
    'access arguments' => array('administer tripal example'),
    'type' => MENU_NORMAL_ITEM,
  );

  // EXPLANATION: all extension modules should provide help documentation to 
  // describe the functionality of the module and any installation or setup
  // tasks that may be required.  The menu 'type' is MENU_LOCAL_TASK so that
  // the link appears in a tab on the extension module's administrative page.
  // here the 'page callback' specifies that we are using Drupal's theme 
  // function and the 'page_arguments' indicate the name of the template file
  // Thus, all help documentation should be provided in the 
  // [module name]/theme/tripal_example_help.tpl.php file. 
  $items['admin/tripal/extension/tripal_example/help'] = array(
    'title' => 'Help',
    'description' => 'Basic Description of Tripal Library Module Functionality',
    'page callback' => 'theme',
    'page arguments' => array('tripal_example_help'),
    'access arguments' => array('administer tripal example'),
    'type' => MENU_LOCAL_TASK,
    'weight' => 10
  );

  // EXPLANATION: all extension modules should provide a configuration page. 
  // Even if your module does not need configuration the menu item and page
  // should be created. This helps users recognize that the module is installed
  // and working.  The configuration page can simply state that no 
  // configuration settings are available.  Typically a form is provided for the 
  // module's configuration settings. Therefore the 'page callback' uses the
  // drupal_get_form() function and the 'page argument' indicates the form
  // to call is named 'tripal_eample_admin'.  The function that describes
  // to form is in the includes/tripal_example.admin.inc file.
  $items['admin/tripal/extension/tripal_example/configuration'] = array(
    'title' => 'Settings',
    'description' => 'Configure the Tripal Library module',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('tripal_example_admin'),
    'access arguments' => array('administer tripal example'),
    'type' => MENU_LOCAL_TASK,
    'weight' => 5
  );
  
  // EXPLANATION: If your module defines a new chado node type and that node
  // type directly links to a record in Chado, then you can use the Tripal API
  // to quickly provide syncing functionality.  See the API documentation here
  // for more information on how that is setup:
  // http://api.tripal.info/api/tripal/tripal_core%21api%21tripal_core.chado_nodes.api.inc/function/chado_node_sync_form/2.x
  $items['admin/tripal/extension/tripal_example/sync'] = array(
    'title' => ' Sync',
    'description' => 'Create pages on this site for examples stored in Chado',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('chado_node_sync_form', 'tripal_example', 'chado_example'),
    'access arguments' => array('administer tripal example'),
    'type' => MENU_LOCAL_TASK,
    'weight' => 2
  );
  
  // EXPLANATION: If your module defines a new node type that uses the default
  // table of contents (left-side bar of content panes on a page). Then a 
  // 'TOC' link will automatically appear on the node page to allow for 
  // customization of the TOC.  However those customizations are only node
  // specific.  To provide a tab in the module's administrative pages add the
  // following menu item. This menu will provide a form similar to the one
  // found on the node that allows the user to set global TOC settings for the
  // content type.
  $items['admin/tripal/chado/tripal_example/toc'] = array(
    'title' => ' TOC',
    'description' => 'Manage the table of contents for example nodes.',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('tripal_core_content_type_toc_form', 'chado_example'),
    'access arguments' => array('administer tripal example'),
    'type' => MENU_LOCAL_TASK,
    'file' =>  'includes/tripal_core.toc.inc',
    'file path' => drupal_get_path('module', 'tripal_core'),
    'weight' => 3
  );
  
  return $items;
}

/**
 * Implements hook_views_api()
 * 
 * This hook tells drupal that there is views support for
 * for this module which then automatically includes the tripal_db.views.inc 
 * where all the views integration code is found.
 *
 * @ingroup tripal_example
 */
function tripal_example_views_api() {
  return array(
    'api' => 3.0,
  );
}


/**
 *  We need to let drupal know about our theme functions and their arguments.
 *  We create theme functions to allow users of the module to customize the
 *  look and feel of the output generated in this module
 *
 * @ingroup tripal_example
 */
function tripal_example_theme($existing, $type, $theme, $path) {
  $core_path = drupal_get_path('module', 'tripal_core');

  // EXPLANATION: this function defines all of the functions and templates
  // that this module needs to provide content.  These details are provided
  // in the form of an array the indicates which functions or templates
  // provide content.  Please see the Drupal theming guide for an in-depth
  // description for how theming works in Drupal:
  // https://drupal.org/documentation/theme
  
  $items = array(
    
    // EXPLANATION:  If this module defines a new node type that displays
    // Chado data then we should use Tripal's default node template.  This
    // template ensures that all content provided by Tripal and Tripal 
    // extension modules has the same look and feel.  It is designed to be
    // generic such that it won't intefer with the look-and-feel of the default
    // theme.  This generic template will organize the node into a table
    // of contents found on the left-side of the page and place the content
    // in the center of the page.  User's will cycle through content on the 
    // page by clicking the links in the table of contents. If you do not want
    // to use the default Tripal template you can change this array to your
    // liking.
    'node__chado_example' => array(
      'template' => 'node--chado-generic',
      'render element' => 'node',
      'base hook' => 'node',
      'path' => "$core_path/theme/templates",
    ),

    // EXPLANATION: the following defines all of the template files used for
    // this module. Templates are named with underscores separating words, and
    // correspond directly to a file with the extension '.tpl.php'. For example
    // the 'tripal_example_base' template will have a corresponding
    // tripal_example_base.tpl.php file where the display code is housed.
    // The only required templates are the 'base',  'help' and 'teaseer' templates.
    // The base template provides the basic information about the record in 
    // in Chado.  The 'help' template provides the adminstrative help documenation,
    // and the teaser provides a brief summary of the record that can be used
    // as short description of the record in aggregated lists.
    
    // the base template
    'tripal_example_base' => array(
      'variables' => array('node' => NULL),
      'template' => 'tripal_example_base',
      'path' => "$path/theme/templates",
    ),
    // the help template
    'tripal_example_help' => array(
      'template' => 'tripal_example_help',
      'variables' =>  array(NULL),
      'path' => "$path/theme/templates",
    ),
    // the teaser template.
    'tripal_example_teaser' => array(
      'variables' => array('node' => NULL),
      'template' => 'tripal_example_teaser',
      'path' => "$path/theme/templates",
    ),
    
    
    // EXPLANATION: Typically, a different template is created for each subset of data.
    // for example, most Chado tables have a 'XXXXprop', 'XXXX_cvterm',
    // 'XXXX_dbxref', 'XXXX_synonyms', 'XXXX_relationships' tables. Therefore,
    // a template is created to display data from each of these tables.
    
    'tripal_example_properties' => array(
      'variables' => array('node' => NULL),
      'template' => 'tripal_example_properties',
      'path' => "$path/theme/templates",
    ),
    'tripal_example_references' => array(
      'variables' => array('node' => NULL),
      'template' => 'tripal_example_references',
      'path' => "$path/theme/templates",
    ),
    'tripal_example_relationships' => array(
      'variables' => array('node' => NULL),
      'template' => 'tripal_example_relationships',
      'path' => "$path/theme/templates",
    ),

    // EXPLANATION: sometimes a module may want to add content to another
    // modules' node types. For example, the feature module does this by
    // adding a 'feature summary' data to an organism.  To add data to another
    // module's node, the templates belong to this module and are 
    // specified in the same way as above.  However, the naming of the 
    // template is changed to include the name of the module that supplies
    // the node type followed by our record name: 

    // tripal_organism templates
    'tripal_organism_examples' => array(
      'variables' => array('node' => NULL),
      'template' => 'tripal_organism_examples',
      'path' => "$path/theme/templates",
    ),
  );
  
  return $items;
}

/**
 * Implements hook_help()
 * 
 * Adds a help page to the module list
 */
function tripal_example_help ($path, $arg) {
  
  // EXPLANATION: in the tripal_example_menu() function above we created 
  // a menu item for the help documentation.  The menu item specified 
  // a function that should be called when the menu item is clicked.  This 
  // is that function.  But, rather than place HTML code in this function
  // we want to have our help documentation in a template file.  We 
  // specified in the tripal_example_theme() function that we have a template
  // file so now we want to use get the contents of that template file and
  // return it.
  if ($path == 'admin/help#tripal_example') {
    return theme('tripal_example_help', array());
  }
}


/**
 * Implements hook_cron()
 *
 * @ingroup tripal_example
 */
function tripal_example_cron() {

  // EXPLANATION: here we can add any code that needs to be executed when
  // the Drupal cron is run.
}


/**
 * Implementation of hook_form_alter()
 * 
 * Allows a module to alter any form prior to it being rendered. For more
 * details about Drupal's Form API see this page:
 * 
 * https://api.drupal.org/api/drupal/includes!form.inc/group/form_api/7
 *
 */
function tripal_example_form_alter(&$form, &$form_state, $form_id) {
  
  if ($form_id == "chado_example_node_form") {
    
    // EXPLANATION:  The hook_form_alter() Drupal hook is used to alter
    // a form before it is displayed.  This allows any module to provide new
    // form elements or change the form that another module creates.  We do
    // not need to alter a form created by another module, but we do want to
    // alter the form for our new node type.  For example, all node types
    // will automatically have a 'Preview' button.  For inserting or updating
    // data for Chado we don't really need a Preview button and it complicates
    // the form.  So, we use the following code to disable the Preview button.
    // if you want to keep the preview button then remove this code.
    // turn of preview button for insert/updates
    $form['actions']['preview']['#access'] = FALSE;
    
    // EXPLANATION: Drupal always adds a 'body' field to all node types.
    // Our node type doens't use the 'body' field so we remove it from the form.
    unset($form['body']);
  }
}