tripal/tripal_core/tripal_core.module

<?php
/**
 * @file
 * The Tripal Core module
 */

/**
 * @defgroup tripal_core Tripal Core Module
 * @ingroup tripal_modules
 * @{
 * Functionality useful for all other Tripal modules including the Tripal jobs, files,
 * materialized views and custom table functions.
 * @}
 */

// APPLICATION PROGRAMMER INTERFACE -------------
// Chado API
require_once 'api/tripal_core.chado_general.api.inc';
require_once 'api/tripal_core.chado_query.api.inc';
require_once 'api/tripal_core.chado_variables.api.inc';
require_once 'api/tripal_core.chado_schema.api.inc';
require_once 'api/tripal_core.chado_nodes.api.inc';
require_once 'api/tripal_core.chado_nodes.properties.api.inc';
require_once 'api/tripal_core.chado_nodes.dbxrefs.api.inc';
require_once 'api/tripal_core.chado_nodes.relationships.api.inc';

// Table API
require_once 'api/tripal_core.custom_tables.api.inc';
require_once 'api/tripal_core.mviews.api.inc';

// Miscellaneous API
require_once 'api/tripal_core.files.api.inc';
require_once 'api/tripal_core.jobs.api.inc';
require_once 'api/tripal_core.tripal.api.inc';

require_once 'api/tripal_core.DEPRECATED.inc';

// INCLUDES -------------------------------------
require_once 'includes/tripal_core.jobs.inc';
require_once 'includes/tripal_core.mviews.inc';
require_once 'includes/tripal_core.custom_tables.inc';
require_once 'includes/tripal_core.chado_install.inc';
require_once 'includes/tripal_core.form_elements.inc';

tripal_core_set_globals();
/**
 * This function is used to set the global Chado variables
 *
 * @ingroup tripal_core
 */
function tripal_core_set_globals() {
  // these global variables are meant to be accessed by all Tripal
  // modules to find the chado version installed and if Chado is local.
  // these variables are stored as globals rather than using the drupal_set_variable
  // functions because the Drupal functions make databaes queries and for long
  // running loaders we don't want those queries repeatedly.
  $GLOBALS["chado_is_installed"]  = chado_is_installed();
  if ($GLOBALS["chado_is_installed"]) {
    $GLOBALS["chado_is_local"]      = chado_is_local();
    $GLOBALS["chado_version"]       = chado_get_version();
    $GLOBALS["exact_chado_version"] = chado_get_version(TRUE);
  }
}

/**
 * Implements hook_init().
 * Used to set the search_path, create default content and set default variables.
 *
 * @ingroup tripal_core
 */
function tripal_core_init() {
  global $base_url;

  // create the 'tripal' controlled volcabulary in chado but only if it doesn't already exist, and
  // only if the chado database is present.
  if ($GLOBALS["chado_is_installed"]) {

    // if the Tripal cv is missing then add
    $results = chado_query("SELECT * FROM {cv} WHERE name = 'tripal'");
    $tripal_cv = $results->fetchObject();
    if (!$tripal_cv) {
      $results = chado_query(
        "INSERT INTO {cv} (name,definition) " .
        "VALUES ('tripal', 'Terms used by Tripal for modules to manage data such as that stored in property tables like featureprop, analysisprop, etc')"
      );
    }

    // if the Tripal db is missing then add it
    $results = chado_query("SELECT * FROM {db} WHERE name = 'tripal'");
    $tripal_db = $results->fetchObject();
    if (!$tripal_db) {
      $results = chado_query(
        "INSERT INTO {db} (name,description) " .
        "VALUES ('tripal', 'Used as a database placeholder for tripal defined objects such as tripal cvterms')"
      );
    }
  }

  // add some variables for all javasript to use for building URLs
  $theme_dir = drupal_get_path('theme', 'tripal');
  $clean_urls = variable_get('clean_url', 0);
  drupal_add_js(
    " var baseurl  = '$base_url';
      var themedir = '$theme_dir';
      var isClean  =  $clean_urls;",
    'inline', 'header');

  // make sure the date time settings are the way Tripal will insert them
  // otherwise PostgreSQL version that may have a different datestyle setting
  // will fail when inserting or updating a date column in a table.
  db_query("SET DATESTYLE TO :style", array(':style' => 'MDY'));

  // If we want AHAH elements on the node forms (e.g. chado_pub form) then we need to include
  // the node.pages file. Otherwise this error message is given:
  //
  // warning: call_user_func_array() expects parameter 1 to be a valid callback,
  // function 'node_form' not found or invalid function name
  // in /var/www/includes/form.inc on line 382.
  module_load_include('inc', 'node', 'node.pages');

}

/**
 * Implements hook_menu().
 * Defines all menu items needed by Tripal Core
 *
 * @ingroup tripal_core
 */
function tripal_core_menu() {
  $items = array();

  // Triapl setting groups
  $items['admin/tripal'] = array(
    'title' => 'Tripal',
    'description' => "Manage the behavior or Tripal and its various modules.",
    'weight' => -8,
    'page callback' => 'system_admin_menu_block_page',
    'access arguments' => array('administer tripal'),
    'file' => 'system.admin.inc',
    'file path' => drupal_get_path('module', 'system'),
  );
  $items['admin/tripal/schema'] = array(
    'title' => 'Chado Schema',
    'description' => "Tools to extend the chado schema through custom tables & materialized views.",
    'weight' => -2,
    'access arguments' => array('administer tripal'),
  );
  $items['admin/tripal/chado'] = array(
    'title' => 'Chado Modules',
    'description' => 'Configuration for specific chado data types such as Vocabularies, Features, etc.',
    'access arguments' => array('administer tripal'),
    'type' => MENU_NORMAL_ITEM,
    'weight' => -6
  );
  $items['admin/tripal/loaders'] = array(
    'title' => 'Chado Data Loaders',
    'description' => 'Tools facilitating loading data into the chado database. Includes a generic tab-delimited loader (Bulk Loader).',
    'access arguments' => array('administer tripal'),
    'type' => MENU_NORMAL_ITEM,
    'weight' => -4
  );
  $items['admin/tripal/extension'] = array(
    'title' => 'Extension Modules',
    'description' => 'Configuration for Tripal extension modules.',
    'access arguments' => array('administer tripal'),
    'type' => MENU_NORMAL_ITEM,
    'weight' => 0
  );

  // Tripal Setup
  $items['admin/tripal/setup'] = array(
    'title' => 'Setup Tripal',
    'description' => 'Tools for initial setup of Tripal',
    'access arguments' => array('administer tripal'),
    'weight' => -8
  );
  $items['admin/tripal/setup/customize'] = array(
    'title' => 'Customize Tripal',
    'description' => 'Information on how to customize tripal',
    'page callback' => 'theme',
    'page arguments' => array('tripal_core_customize'),
    'access arguments' => array('administer tripal'),
    'weight' => 10
  );
  $items['admin/tripal/setup/chado_install'] = array(
    'title' => 'Install Chado Schema',
    'description' => 'Installs the Chado database tables, views, etc., inside the current Drupal database',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('tripal_core_chado_load_form'),
    'access arguments' => array('install chado'),
    'type' => MENU_NORMAL_ITEM,
    'weight' => -10
  );

  // Jobs Management
  $items['admin/tripal/tripal_jobs'] = array(
    'title' => 'Jobs',
    'description' => 'Jobs managed by Tripal',
    'page callback' => 'tripal_jobs_admin_view',
    'access arguments' => array('administer tripal'),
    'type' => MENU_NORMAL_ITEM,
    'weight' => -10
  );
  $items['admin/tripal/tripal_jobs/help'] = array(
    'title' => 'Help',
    'description' => 'Help for the tripal job management system',
    'page callback' => 'theme',
    'page arguments' => array('tripal_core_job_help'),
    'access arguments' => array('administer tripal'),
    'type' => MENU_LOCAL_TASK,
    'weight' => 10
  );
  $items['admin/tripal/tripal_jobs/cancel/%'] = array(
    'title' => 'Jobs',
    'description' => 'Cancel a pending job',
    'page callback' => 'tripal_cancel_job',
    'page arguments' => array(4),
    'access arguments' => array('administer tripal'),
    'type' => MENU_CALLBACK,
  );
  $items['admin/tripal/tripal_jobs/rerun/%'] = array(
    'title' => 'Jobs',
    'description' => 'Re-run an existing job.',
    'page callback' => 'tripal_rerun_job',
    'page arguments' => array(4),
    'access arguments' => array('administer tripal'),
    'type' => MENU_CALLBACK,
  );
  $items['admin/tripal/tripal_jobs/view/%'] = array(
    'title' => 'Jobs Details',
    'description' => 'View job details.',
    'page callback' => 'tripal_jobs_view',
    'page arguments' => array(4),
    'access arguments' => array('administer tripal'),
    'type' => MENU_CALLBACK,
  );
  $items['admin/tripal/tripal_jobs/views/jobs/enable'] = array(
    'title' => 'Enable Jobs Administrative View',
    'page callback' => 'tripal_views_admin_enable_view',
    'page arguments' => array('tripal_core_admin_jobs', 'admin/tripal/tripal_jobs'),
    'access arguments' => array('administer tripal'),
    'type' => MENU_CALLBACK,
  );

  // Materialized Views
  $items['admin/tripal/schema/mviews'] = array(
    'title' => 'Materialized Views',
    'description' => 'Materialized views are used to improve speed of large or complex queries.',
    'page callback' => 'tripal_mview_admin_view',
    'access arguments' => array('administer tripal'),
    'type' => MENU_NORMAL_ITEM,
    'weight' => -10
  );
  $items['admin/tripal/schema/mviews/help'] = array(
    'title' => 'Help',
    'description' => 'Help for the materialized views management system',
    'page callback' => 'theme',
    'page arguments' => array('tripal_core_mviews_help'),
    'access arguments' => array('administer tripal'),
    'type' => MENU_LOCAL_TASK,
    'weight' => 10
  );
  $items['admin/tripal/schema/mviews/report/%'] = array(
    'title' => 'Materialized View',
    'description' => 'Materialized views are used to improve speed of large or complex queries. These are database views as compared to Drupal views.',
    'page callback' => 'tripal_mview_report',
    'page arguments' => array(5),
    'access arguments' => array('administer tripal'),
    'type' => MENU_CALLBACK,
  );
  $items['admin/tripal/schema/mviews/new'] = array(
    'title' => 'Create Materialized View',
    'description' => 'Create a new materialized view.',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('tripal_mviews_form'),
    'access arguments' => array('administer tripal'),
    'type' => MENU_CALLBACK,
  );
  $items['admin/tripal/schema/mviews/edit/%'] = array(
    'title' => 'Edit Materialized View',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('tripal_mviews_form', 5),
    'access arguments' => array('administer tripal'),
    'type' => MENU_CALLBACK,
  );
  $items['admin/tripal/schema/mviews/update/%'] = array(
    'title' => 'Create Materialized View',
    'description' => 'Materialized views are used to improve speed of large or complex queries.',
    'page callback' => 'tripal_mviews_add_populate_job',
    'page arguments' => array(5),
    'access arguments' => array('administer tripal'),
    'type' => MENU_CALLBACK,
  );
  $items['admin/tripal/schema/mviews/delete/%'] = array(
    'title' => 'Create Materialized View',
    'description' => 'Materialized views are used to improve speed of large or complex queries.',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('tripal_mviews_delete_form', 5),
    'access arguments' => array('administer tripal'),
    'type' => MENU_CALLBACK,
  );

  // Custom Tables
  $items['admin/tripal/schema/custom_tables'] = array(
    'title' => 'Custom Tables',
    'description' => 'Creation of custom tables that are added to Chado database.',
    'page callback' => 'tripal_custom_table_admin_view',
    'access arguments' => array('administer tripal'),
    'type' => MENU_NORMAL_ITEM,
    'weight' => -10
  );
  $items['admin/tripal/schema/custom_tables/help'] = array(
    'title' => 'Help',
    'description' => 'Help for the tripal job management system',
    'page callback' => 'theme',
    'page arguments' => array('tripal_core_job_help'),
    'access arguments' => array('administer tripal'),
    'type' => MENU_LOCAL_TASK,
    'weight' => 10
  );
  $items['admin/tripal/schema/custom_tables/view/%'] = array(
    'title' => 'Custom Tables',
    'description' => 'Custom tables are added to Chado.',
    'page callback' => 'tripal_custom_table_view',
    'page arguments' => array(4),
    'access arguments' => array('administer tripal'),
    'type' => MENU_CALLBACK,
  );
  $items['admin/tripal/schema/custom_tables/new'] = array(
    'title' => 'Create Custom Table',
    'description' => 'An interface for creating your own custom tables.',
    'page callback' => 'tripal_custom_table_new_page',
    'access arguments' => array('administer tripal'),
    'type' => MENU_CALLBACK,
  );
  $items['admin/tripal/schema/custom_tables/edit/%'] = array(
    'title' => 'Edit Custom Table',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('tripal_custom_tables_form', 5),
    'access arguments' => array('administer tripal'),
    'type' => MENU_CALLBACK,
  );
  $items['admin/tripal/schema/custom_tables/delete/%'] = array(
    'title' => 'Create Custom Table',
    'description' => 'Custom tables are added to Chado.',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('tripal_custom_tables_delete_form', 5),
    'access arguments' => array('administer tripal'),
    'type' => MENU_CALLBACK,
  );
  $items['admin/tripal/schema/custom_tables/views/tables/enable'] = array(
    'title' => 'Enable Custom Tables Administrative View',
    'page callback' => 'tripal_views_admin_enable_view',
    'page arguments' => array('tripal_core_admin_custom_table', 'admin/tripal/schema/custom_tables'),
    'access arguments' => array('administer tripal'),
    'type' => MENU_CALLBACK,
  );

  // Relationshi API autocomplete callback
  $items['tripal_ajax/relationship_nodeform/%/%/name_to_id'] = array(
    'page callback' => 'chado_add_node_form_relationships_name_to_id_callback',
    'page arguments' => array(2,3),
    'access arguments' => array('access content'),
    'type' => MENU_CALLBACK
  );

  return $items;
}

/**
 * Implements hook_permission().
 *
 * Set the permission types that the chado module uses.  Essentially we
 *  want permissionis that protect creation, editing and deleting of chado
 *  data objects
 *
 * @ingroup tripal_core
 */
function tripal_core_permission() {
  return array(
    'install chado' => array(
      'title' => t('Install Chado'),
      'description' => t('Allow the user to install or upgrade a Chado database in the existing Drupal database.')
    ),
    'administer tripal' => array(
      'title' => t('Administer Tripal'),
      'description' => t('Allow the user to access administrative pages of Tripal.')
    ),
  );
}

/**
 * Implements hook_theme().
 * Registers template files/functions used by this module.
 *
 * @ingroup tripal_core
 */
function tripal_core_theme($existing, $type, $theme, $path) {
  return array(
    'tripal_core_customize' => array(
      'arguments' => array('job_id' => NULL),
      'template' => 'tripal_core_customize',
      'path' => "$path/theme/templates"
    ),
    'theme_file_upload_combo' => array(
      'render element' => 'element',
    ),
    'theme_sequence_combo' => array(
      'render element' => 'element',
    ),
    'tripal_core_jobs_help' => array(
      'template' => 'tripal_core_jobs_help',
      'variables' =>  array(NULL),
      'path' => "$path/theme/templates"
    ),
    'tripal_core_customtables_help' => array(
      'template' => 'tripal_core_customtables_help',
      'variables' =>  array(NULL),
      'path' => "$path/theme/templates"
    ),

    // Chado Node API Themes
    // --------------------------------
    // Properties Node Form
    'chado_node_properties_form_table' => array(
      'function' => 'theme_chado_add_node_form_properties',
      'render element' => 'element',
    ),
    // Additional Dbxrefs Nore Form
    'chado_node_additional_dbxrefs_form_table' => array(
      'function' => 'theme_chado_add_node_form_dbxrefs_table',
      'render element' => 'element',
    ),
    // Relationships Nore Form
    'chado_node_relationships_form_table' => array(
      'function' => 'theme_chado_add_node_form_relationships_table',
      'render element' => 'element',
    ),

    // Admin messages theme
    // --------------------------------
    'tripal_admin_message' => array(
      'function' => 'theme_tripal_admin_message',
      'variables' => array('message' => NULL),
    )
  );
}


/**
 * Implements hook_job_describe_args().
 * Describes the arguements for the tripal_populate_mview job to allow for greater
 * readability in the jobs details pages.
 *
 * @param $callback
 *   The callback of the current tripal job (this is the function that will be executed
 *   when tripal_launch_jobs.php is run.
 * @param $args
 *   An array of arguments passed in when the job was registered.
 *
 * @return
 *   A more readable $args array
 *
 * @ingroup tripal_core
 */
function tripal_core_job_describe_args($callback, $args) {
  $new_args = array();
  if ($callback == 'tripal_populate_mview') {
    // get this mview details
    $sql = "SELECT * FROM {tripal_mviews} WHERE mview_id = :mview_id ";
    $results = db_query($sql, array(':mview_id' => $args[0]));
    $mview = $results->fetchObject();
    $new_args['View Name'] = $mview->name;
  }

  elseif ($callback == 'tripal_core_install_chado') {
     $new_args['Action'] = $args[0];
  }
  return $new_args;
}

/**
 * this is just a wrapper for backwards compatibility with a naming mistake.
 * it can go away in the future as it only is useful for jobs created by v0.3b
 *
 * @todo remove this function
 */
function tripal_core_load_gff3($gff_file, $organism_id, $analysis_id, $add_only = 0,
  $update = 0, $refresh = 0, $remove = 0, $job = NULL) {

  tripal_feature_load_gff3($gff_file, $organism_id, $analysis_id, $add_only,
    $update, $refresh, $remove, $job);
}

/**
 * Implements hook_coder_ignore().
 * Defines the path to the file (tripal_core.coder_ignores.txt) where ignore rules for coder are stored
 */
function tripal_core_coder_ignore() {
  return array(
    'path' => drupal_get_path('module', 'tripal_core'),
    'line prefix' => drupal_get_path('module', 'tripal_core'),
  );
}

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


/**
 * After the node is built, we want to add instructions to each
 * content section letting the administrator know which template
 * they can customize
 *
 * @param unknown $build
 */
function tripal_core_node_view_alter(&$build) {
  global $theme;

  //dpm($build);

  // if the $build['tripal_toc'] element is not present, then this is not
  // a full node view so we do not want to alter
  if (!array_key_exists('tripal_toc', $build)) {
    return;
  }

  $cache = cache_get("theme_registry:$theme", 'cache');
  $node = $build['#node'];
  $toc = array();
  $toc_html = '';
  
  // if we are looking at a Tripal node template then we want to
  // make some changes to each block of content so that we can associate
  // a table of contents and add administrator and curator messages
  if (preg_match('/chado_/', $node->type)) {

    // iterate through all the elements of the $build array and for those
    // that are wanting to provide content for this node
    $markup = array();
    foreach ($build as $key => $value) {

      // skip the body element as the Tripal node types do not use it
      if ($key == 'body') {
        continue;
      }

      // examine elements without a '#' prefix as these should be adding
      // contents to the page. Skip the table of contents and links as those
      // will be placed elsewhere
      if (!preg_match('/^#/', $key) and $key != 'tripal_toc' and $key != 'links') {

        //-----------------------
        // INITIALIZE THE CONTENT VARIABLES
        //-----------------------
        $toc_item_title = $key;
        $toc_item_id    = $key;
        $toc_item_link  = '';

        // get the title for the table of contents.  Tripal templates should
        // have a '#tripal_toc_title' element in the build array
        if (array_key_exists('#tripal_toc_title', $build[$key])) {
          $toc_item_title = $build[$key]['#tripal_toc_title'];
        }
        // other elements in the $build array may just have a '#title' element,
        if (array_key_exists('#title', $build[$key])) {
          $toc_item_title = $build[$key]['#title'];
        }
        $toc_item_title = ucwords($toc_item_title);

        if (array_key_exists('#tripal_toc_id', $build[$key])) {
          $toc_item_id = $build[$key]['#tripal_toc_id'];
        }
        $toc_item_link = "<div class=\"tripal_toc_list_item\"><a id=\"$toc_item_id\" class=\"tripal_toc_list_item_link\" href=\"?block=$toc_item_id\">$toc_item_title</a></div>";


        //-----------------------
        // GET THE MARKUP FOR EACH ELEMENT
        //-----------------------
        $markup = '';

        // find the markup. Some fields will have a '#markup' and others, such
        // as CCK elements may have a set of '#markup' elements organized by
        // numerical keys.
        if (array_key_exists('#markup', $build[$key]) and trim($build[$key]['#markup'])) {
          $markup = $build[$key]['#markup'];
        }
        // For backwards copmatibility we should support the '#value' element as well.
        elseif (array_key_exists('#value', $build[$key]) and trim($build[$key]['#value'])) {
          $markup = $build[$key]['#markup'];
        }

        // if we have no '#markup' field then this element has not yet
        // been rendered.  Let's render it and substitute that for markup
        if (!$markup) {
          $markup = trim(render($build[$key]));
          $build[$key] = array(
            '#markup' => $markup,
          );
        }

        // if we still don't have markup then skip this one
        if (!$markup) {
          continue;
        }

        //-----------------------
        // FIND THE TEMPLATE PATH
        //-----------------------
        // get the template path so we can put it in an admin message box
        $path = '';
        if (array_key_exists($key, $cache->data) and array_key_exists('path', $cache->data[$key])) {

          $path = $cache->data[$key]['path'] . '/' . $key . '.tpl.php';

          $path = tripal_set_message("Administrators, you can
            customize the way the content above is presented.  Tripal provides a template
            file for each block of content.  To customize, copy the template file to your
            site's default theme, edit then " .
            l('clear the Drupal cache', 'admin/config/development/performance', array('attributes' => array('target' => '_blank'))) . ".
            Currently, the content above is provided by this template: <br><br>$path",
            TRIPAL_INFO,
            array('return_html' => 1)
          );
        }

        //-----------------------
        // SET THE WEIGHTS FOR THE TOC ELEMENTS
        //-----------------------
        // set the weight of the TOC item and add it to our $toc array
        // for building of the TOC below
        $weight = 0;
        if (array_key_exists('#weight', $build[$key])) {
          $weight = $build[$key]['#weight'];
        }
        $toc[$weight][$toc_item_title] = $toc_item_link;

        //-----------------------
        // CREATE THE DATA BLOCK
        //-----------------------
        // add a surrounding <div> box around the content
        $updated_markup = "
          <div id=\"$toc_item_id-tripal-data-block\" class=\"tripal-data-block\">
            <div class=\"$toc_item_id-tripal-data-block-title tripal-data-block-title\">$toc_item_title</div>
              $markup
              $path
            </div>
          </div>
        ";

        $build[$key]['#markup'] = $updated_markup;
        $build[$key]['#weight'] = $weight;
      }
    }
  }

  //-----------------------
  // BUILD THE TABLE OF CONTENTS LINKS
  //-----------------------
  // first sort the links numerically by their weight
  ksort($toc, SORT_NUMERIC);
  $toc_html = '';
  foreach ($toc as $weight => $links) {
    // for links in the same weight, sort them alphabetically
    ksort($links);
    foreach ($links as $toc_item_title => $toc_item_link) {
      $toc_html .= $toc_item_link;
    }
  }
  $build['tripal_toc']['#markup'] = "<div id=\"$node->type-tripal-toc-block\" class=\"tripal-toc-block\">$toc_html</div>";
  //dpm($cache);
  //dpm($build);
}

/**
 *
 * @ingroup tripal_core
 */
function tripal_core_node_view($node, $view_mode, $langcode) {

  // if this node type is a chado-based node (i.e. Tripal node)
  // the we want to add a table of contents to it's content list
  // this table of contents will be an empty
  if (preg_match('/^chado_/', $node->type)) {
    // Show feature browser and counts
    if ($view_mode == 'full') {
      $node->content['tripal_toc'] = array(
        '#markup' => "<div id=\"$node->type-tripal-toc-block\" class=\"tripal-toc-block\"></div>",
      );
    }
  }
}