1. 2.x tripal_views/api/tripal_views.api.inc tripal_views_api
2. 1.x tripal_views/api/tripal_views.api.inc tripal_views_api

Provides functions to help extension modules add their own tripal views integrations as well as functions for managing default views.

Managing Default Views:

When you create administrative default views (or really any default view) you really have no way to ensure that the site administrator keeps these views enabled. In some cases this is a good thing and provides the site administrator the ability to disable views that don't apply to their particular installation or to replace your default view with a custom view of their own. But in other cases, particularily for administration views, you want to gaurd against accidental disabling of your views.

One way to do this is to add a landing page using a heook_menu() definition to a custom callback returning HTML. You can use this page to render the view if it is enabled but provide logic to display a message if the view is disabled. Furthermore, it's often helpful to provide a link allowing site administrators to enable the view from your page rather than expecting them to go to the views administration UI. This is done for all the administration views provided by Tripal. The following is an example of how to achomplish this functionality for your own module:

function mymodule_menu() {
 $items = array();

 // Create the landing page
 $items['admin/tripal/<PATH-TO-YOUR-LANDING-PAGE>'] = array(
   'title' => 'MyModule Administration',
   'description' => 'Administration of my module.',
   'page callback' => 'mymodule_admin_landing_page',
   'access arguments' => array('<YOUR-PERMISSION-KEY>'),
   'type' => MENU_NORMAL_ITEM,
 );

 // Create one of these for each of your default views
 $items['admin/tripal/<PATH-TO-YOUR-ADMIN-SECTION>/views/<VIEW-MACHINE-NAME>/enable'] = array(
   'title' => 'Enable <VIEW-HUMAN-READABLE-NAME>',
   'page callback' => 'tripal_enable_view',
   'page arguments' => array('<VIEW-MACHINE-NAME>', '<PATH-TO-REDIRECT-TO-AFTERWARDS>'),
   'access arguments' => array('<YOUR-PERMISSION-KEY>'),
   'type' => MENU_CALLBACK,
 );

 return $items;
}

function mymodule_admin_landing_page() {

 // Get the View Embed Code
 // This function will return FALSE if your view is not enabled
 $view_code = views_embed_view('<VIEW-MACHINE-NAME>', '<DISPLAY-MACHINE-NAME');
 // If your view is enabled then embed it in this page by returning the embed code
 if (isset($view_code)) {
   $output .= $view_code;
 }
 else {
   // Provide the landing page with links to the menu item created in hook_menu to
   // to enable your view
   $output .= '<p>The My Module module uses primarily views to provide an '
     . 'administrative interface. Currently one or more views needed for this '
     . 'administrative interface are disabled. <strong>Click each of the following links to '
     . 'enable the pertinent views</strong>:</p>';
   $output .= '<ul>';
   // NOTE: <URL-FROM-MENU-TO-ENABLE-VIEW> is
   // admin/tripal/<PATH-TO-YOUR-ADMIN-SECTION>/views/<VIEW-MACHINE-NAME>/enable
   // from above hook_menu().
   $output .= '<li>' . l('<VIEW-HUMAN-RADABLE-NAME>', '<URL-FROM-MENU-TO-ENABLE-VIEW>') . '</li>';
   $output .= '</ul>';
 }

 return $output;
}

Adding your own Tripal Views Integrations:

One of the main ways the Tripal View API is likely to be used is if your module needs to create it's own tripal views integration. You might need to do this for any number of reasons but the following examples are thought to be the most common:

1) Your module wants to add handlers with better functionality to fields it has more knowledge of than the general integration for all tables

  mymodule_views_data() {

   // First check that your integration has not already been added
   // When selecting a priority, do not choose -10 or -9 and make sure it is below 0
   // so that individual sites still have the ability to override it, if needed
   $table_name = 'my_chado_table';
   $priority = -5;
   if (!tripal_is_table_integrated($table_name, $priority)) {

     // If you really only need to tweak an existing integration you can clone it
     // If you want to clone the integration that is currently taking priority
     // then use tripal_get_lightest_views_integration_priority() as below
     $lightest_priority = tripal_get_lightest_views_integration_priority($table_name);
     $setup_id = tripal_clone_views_integration($table_name, $priority, $lightest_priority);

     // And then make a few changes
     // First get the definition array created via the clone above
     $defn_array = tripal_export_views_integration($setup_id);

     // Then make some changes to the array here

     // And finally save the changes to the integration
     tripal_update_views_integration($setup_id, $defn_array);

   }

 }

2) Your module creates a chado table that is not already integrated.

 mymodule_views_data() {

   // First check that your integration has not already been added
   // When selecting a priority, do not choose 10 or 9 and make sure it is below 0
   // so that individual sites still have the ability to override it, if needed
   $table_name = 'my_chado_table';
   $priority = 5;
   if (!tripal_is_table_integrated($table_name, $priority)) {

     // Describe your table using a large array as specified by tripal_add_views_integration().
     $defn_array = array(
       'table' => $table_name, //tablename or materialized view name
       'name' => 'My Chado Table', // Human readable name
       'type' => 'chado', //either chado or mview depending on tablename
       'description' => 'Create a listing from my chado table.', //description seen when creating a view of this type
       'priority' => $priority, //For Base tripal modules: 10; custom modules: 9 to 0;
       'base_table' => TRUE //either TRUE or FALSE depending on whether the current table should show up in the add view list
       'fields' => array(
         'feature_id' => array(
           'name' => 'feature_id', //field name in database
           'title' => 'Feature ID', //human-readable name -seen in Views UI
           'description' => 'This is the unique identifier for features', //help/description seen in Views UI
           'type' => 'int', // the type of field
           'handlers' => array(  //possible keys are field, filter, sort, argument, relationship
             'field' => array(
               'name' => 'chado_views_handler_numeric' //name of handler
             ),
             'filter' => array( ... ),
             ...
           ),
           // Describe any joins involving this field.
           // Note: you can include both foreign keys (feature.type_id => cvterm.cvterm_id)
           // and referring tables (ie: feature.feature_id <= feature_relationship.subject_id)
           'joins' => array(
             'feature_relationship' => array( //table to join to.
               'subject_id' => array( //field in above table (feature_relationship)
                 'table' => 'featureprop', //table to join to
                 'field' => 'feature_id', //field in above table (feature_relationship)
                 'handler' => 'views_join', //handler to use for joining
                 'relationship_handler' => 'views_handler_relationship', //handler to use when a relationship is added.
                 'relationship_only' => FALSE, //whether to join automatically (FALSE) or not (TRUE)
               ),
               ...
             ),
             ...
           ),
         )
       ),
     );
     // Actually create the entry
     tripal_add_views_integration($defn_array);

   }

 }

Parent topics

File

tripal_views/api/tripal_views.api.inc, line 7

API functions for Tripal Views Integration

Functions

Name	Location	Description
tripal_enable_view	tripal_views/api/tripal_views.api.inc	Programatically enable view
tripal_disable_view	tripal_views/api/tripal_views.api.inc	Programatically disable view.
tripal_get_lightest_views_integration_priority	tripal_views/api/tripal_views.api.inc	Retrieve the priority of the lightest priority for a given table.
tripal_get_lightest_views_integration_setup	tripal_views/api/tripal_views.api.inc	Retrieve the views integration setup_id with the lightest priority for a given table
tripal_get_views_integration_setup_id	tripal_views/api/tripal_views.api.inc	Retrieve the views integration setup_id with the given priority/table combination.
tripal_is_table_integrated	tripal_views/api/tripal_views.api.inc	Check to see if this table already has an integration record with the given priority.
tripal_is_lightest_priority_setup	tripal_views/api/tripal_views.api.inc	Checks if you are dealing with the lightest priority setup for a given table. This is a good way to determine whether your modules integration is being used by views.
tripal_rebuild_views_integrations	tripal_views/api/tripal_views.api.inc	Rebuilds all the default integrations.
tripal_add_views_integration	tripal_views/api/tripal_views.api.inc	Add views integration records into the tripal_views* tables.
tripal_export_views_integration	tripal_views/api/tripal_views.api.inc	Export Views integration records.
tripal_remove_views_integration	tripal_views/api/tripal_views.api.inc	Removes a View Integration Entry when you only know the table the integration was created for and the priority.
tripal_update_views_integration	tripal_views/api/tripal_views.api.inc	Update an existing Views Intregration Entry. This essentially removes and then re-adds the integration.
tripal_clone_views_integration	tripal_views/api/tripal_views.api.inc	Clone an integration. This is often a great way to create your own module-specific integration while still benifiting from an existing (or even the lightest priority) integration.
tripal_add_field_to_views_integration	tripal_views/api/tripal_views.api.inc	Adds the given field to an existing or cloned integration. In the case of a cloned integration, the lightest integration is used as the template for the clone.
tripal_add_join_to_views_integration	tripal_views/api/tripal_views.api.inc	Adds the given field to an existing or cloned integration. In the case of a cloned integration, the lightest integration is used as the template for the clone.
tripal_remove_join_from_views_integration	tripal_views/api/tripal_views.api.inc	Remove a join from an integration. This is usually done after cloning an existing integration using tripal_clone_views_integration().