Tripal
Functions
Chado Views Integration
Chado
Collaboration diagram for Chado Views Integration:

Functions

 tripal_enable_view ($view_name, $redirect_link=FALSE)
 
 tripal_disable_view ($view_name, $redirect_link=FALSE)
 
 tripal_make_view_compatible_with_external ($view)
 
 tripal_get_lightest_views_integration_priority ($table_name)
 
 tripal_get_lightest_views_integration_setup ($table_name)
 
 tripal_get_views_integration_setup_id ($table_name, $priority)
 
 tripal_is_table_integrated ($table_name, $priority=NULL)
 
 tripal_is_lightest_priority_setup ($setup_id, $table_name)
 
 tripal_rebuild_views_integrations ($delete_first=FALSE)
 
 tripal_add_views_integration ($defn_array, $setup_id=FALSE)
 
 tripal_export_views_integration ($setup_id)
 
 tripal_remove_views_integration ($identifiers, $options=[])
 
 tripal_update_views_integration ($setup_id, $defn_array)
 
 tripal_clone_views_integration ($table_name, $new_priority=NULL, $template_priority=NULL)
 
 tripal_add_field_to_views_integration ($table_name, $priority, $field)
 
 tripal_add_join_to_views_integration ($table_name, $priority, $join)
 
 tripal_remove_join_from_views_integration ($setup_id, $base_table, $base_field, $left_table, $left_field)
 

Detailed Description

Provides API functions that support direct integration of Chado tables with Drupal Views. This is different from the entity and field integration that Tripal v3 provides. Here Chado tables are directly integrated. Tripal provides a web interface that allows site developers to customize how a Chado table is integrate with Views. However, these functions provide programmatic access to the same functionality.

Function Documentation

◆ tripal_add_field_to_views_integration()

tripal_add_field_to_views_integration (   $table_name,
  $priority,
  $field 
)

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.

NOTE: If that field already exists in the specified integration then it will first be deleted and the new one added.

Parameters
$table_nameThe name of the table the integration is for
$priorityThe priority of the integration to use; pass NULL to use the lightest integration
$fieldAn array describing the field ot add; uses the same format as the $defn_array
Returns
TRUE if the field was added successfully; FALSE otherwise

◆ tripal_add_join_to_views_integration()

tripal_add_join_to_views_integration (   $table_name,
  $priority,
  $join 
)

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.

NOTE: If that field already exists in the specified integration then it will first be deleted and the new one added.

Parameters
$table_nameThe name of the table the integration is for
$priorityThe priority of the integration to use; pass NULL to use the lightest integration
$fieldAn array describing the join to add. it should contain the following keys: base_table, base_field, left_table, left_field, handler, relationship_handler, relationship_only
Returns
TRUE if the field was added successfully; FALSE otherwise

◆ tripal_add_views_integration()

tripal_add_views_integration (   $defn_array,
  $setup_id = FALSE 
)

Add views integration records into the tripal_views* tables.

This is the programatic way to add your own integrations to the tripal views integrations list. Keep in mind that the priority set in your $defn_array needs to be lighter than any existing integrations to be used by views and that it should still be below 0 in order to allow site administrators to override it should they need to.

Parameters
$defn_arrayAn array describing the structure and fields of the table.
Returns
True/False if completed successfully/not.

Example usage (in hook_install()):

$defn_array = array(
'table' => 'feature', //tablename or materialized view name
'name' => 'Sequence Features', // Human readable name
'type' => 'chado', //either chado or mview depending on tablename
'description' => 'Create a listing of features.', //description seen when
creating a view of this type
'priority' => 10, //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)
),
...
),
...
),
)
),
);
tripal_add_views_integration($defn_array);
tripal_add_views_integration
tripal_add_views_integration($defn_array, $setup_id=FALSE)
Definition: tripal_chado_views.api.inc:515

◆ tripal_clone_views_integration()

tripal_clone_views_integration (   $table_name,
  $new_priority = NULL,
  $template_priority = NULL 
)

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.

Parameters
$table_nameThe table for which you'd like to clone an integration
$new_priorityThe priority of the clone; this is the integration which will be created. If no priority is supplied then one lighter then the $template_priority will be used.
$template_priorityThe priority of the template to be used for the clone; this is an existing integration. If no priority is supplied then the lightest priority will be used.

◆ tripal_disable_view()

tripal_disable_view (   $view_name,
  $redirect_link = FALSE 
)

Programatically disable view.

This should be used in a hook_menu definition as the callback to provide a link to disable the view (first example). It can also be called directly if needed (second example).

//Create a URL that when the user navigates there, a given view will be
//disabled.
//You will still need to provide a link to this menu item somewhere
//appropriate.
function mymodule_menu() {
$items = array();
//Create one of these for each of your default views
$items['admin/tripal/<PATH-TO-YOUR-ADMIN-SECTION>/views/<VIEW-MACHINE-NAME>/disable']
= array(
'title' => 'Disable <VIEW-HUMAN-READABLE-NAME>',
'page callback' => 'tripal_disable_view',
'page arguments' => array('<VIEW-MACHINE-NAME>',
'<PATH-TO-REDIRECT-TO-AFTERWARDS>'),
'access arguments' => array('<YOUR-PERMISSION-KEY>'),
'type' => MENU_CALLBACK,
);
return $items;
}
//Call this function directly to disable a view
//The example shows disabling your own default view when your module is
//uninstalled
function mymodule_uninstall() {
$view_name = '<VIEW-MACHINE-NAME>';
tripal_disable_view($view_name);
}
tripal_disable_view
tripal_disable_view($view_name, $redirect_link=FALSE)
Definition: tripal_chado_views.api.inc:132
Parameters
$view_nameThe machine-name of the view to be enabled
$redirect_linkThe path to redirect to. FALSE if no redirect needed

◆ tripal_enable_view()

tripal_enable_view (   $view_name,
  $redirect_link = FALSE 
)

Programatically enable view

This should be used in a hook_menu definition as the callback to provide a link to enable the view (first example). It can also be called directly if needed (second example).

Create a URL that when the user navigates there, a given view will be
enabled.
You will still need to provide a link to this menu item somewhere
appropriate (ie: an admin landing page).
function mymodule_menu () {
$items = array();
//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;
}
Call this function directly to disable a view
The example shows enabling your own default view when your module is
enabled. This might be useful if you disable your view when your module is
disabled. function mymodule_enable() {
$view_name = '<VIEW-MACHINE-NAME>';
tripal_enable_view($view_name);
}
tripal_enable_view
tripal_enable_view($view_name, $redirect_link=FALSE)
Definition: tripal_chado_views.api.inc:68
Parameters
$view_nameThe machine-name of the view to be enabled
$redirect_linkThe path to redirect to. FALSE if no redirect needed

◆ tripal_export_views_integration()

tripal_export_views_integration (   $setup_id)

Export Views integration records.

This is a great way to create your own integration since it returns an already defined integration in array form that you can modify. After modifications simply set the priority to something lighter (but still below 0) than any existing integrations and use tripal_add_views_integration() to add it to the list of integrations.

Parameters
$setup_idThe unique setup id of the tripal views integration
Returns
A views integration definition array as used by tripal_add_views_integration()

◆ tripal_get_lightest_views_integration_priority()

tripal_get_lightest_views_integration_priority (   $table_name)

Retrieve the priority of the lightest priority for a given table.

NOTE: Uses lightest priority (drupal-style) where the range is from -10 to 10 and -10 is of highest priority.

Parameters
$table_nameThe name of the table to retrieve the setup ID for. This can be either a materialized view or a chado table
Returns
returns the lowest priority. If the table has not been integrated, a priority of 10 is returned.

◆ tripal_get_lightest_views_integration_setup()

tripal_get_lightest_views_integration_setup (   $table_name)

Retrieve the views integration setup_id with the lightest priority for a given table

NOTE: Uses lightest priority (drupal-style) where the range is from -10 to 10 and -10 is of highest priority.

Parameters
$table_nameThe name of the table to retrieve the setup ID for. This can be either a materialized view or a chado table
Returns
On success, the setup_id to use for integration of this table; otherwise FALSE

◆ tripal_get_views_integration_setup_id()

tripal_get_views_integration_setup_id (   $table_name,
  $priority 
)

Retrieve the views integration setup_id with the given priority/table combination.

Parameters
$table_nameThe name of the table to retrieve the setup ID for. This can be either a materialized view or a chado table
$priorityThe priority of the integration to retrieve the setup_id for
Returns
On success, the setup_id to use for integration of this table; otherwise FALSE

◆ tripal_is_lightest_priority_setup()

tripal_is_lightest_priority_setup (   $setup_id,
  $table_name 
)

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.

Parameters
$setup_idThe ID of the setup to check (is this setup the lightest one?)
$table_nameThe name of the table associated with this setup
Returns
TRUE is this is the lightest priority; FALSE otherwise

◆ tripal_is_table_integrated()

tripal_is_table_integrated (   $table_name,
  $priority = NULL 
)

Check to see if this table already has an integration record with the given priority.

Parameters
$table_nameThe name of the table to check for integration
$priority(optional) The priority of record to check for
Returns
If the table is already integrated, the setup_id of the existing integration record is returned (If priority is not specified this will be the lightest record); Otherwise the table is not already integrated and FALSE is returned.

◆ tripal_make_view_compatible_with_external()

tripal_make_view_compatible_with_external (   $view)

Remove any drupal fields from a chado-based default view definition if chado is external. This ensures compatibility with an external chado database.

You should be calling this function in your hook_views_default_views(). This function will only remove drupal tables if chado is external; thus you do not need to worry about checking yourself. For example, the following is a good hook_views_default_views():

function mymodule_views_default_views() {
$views = array();
// NOTE: <VIEW-TYPE> describes the type of view:
// - 'admin' for views used for administration of your module
// - 'search' for views used to search data
// - 'list' for views used primarily as data listings
//
//<VIEW-HUMAN-READABLE-NAME>
$view = mymodule_defaultview_<VIEW-TYPE>_<VIEW-MACHINE-NAME>();
$view = tripal_make_view_compatible_with_external($view);
$views[$view->name] = $view;
//<VIEW-HUMAN-READABLE-NAME>
$view = mymodule_defaultview_<VIEW-TYPE>_<VIEW-MACHINE-NAME>();
$view = tripal_make_view_compatible_with_external($view);
$views[$view->name] = $view;
return $views;
}
function mymodule_defaultview_<VIEW-TYPE>_<VIEW-MACHINE-NAME>() {
//PASTE VIEWS EXPORT CODE HERE
return $view;
}
function mymodule_defaultview_<VIEW-TYPE>_<VIEW-MACHINE-NAME>() {
//PASTE VIEWS EXPORT CODE HERE
return $view;
}
tripal_make_view_compatible_with_external
tripal_make_view_compatible_with_external($view)
Definition: tripal_chado_views.api.inc:204

Notice that the actual views export code is in a separate function. This makes your hook_views_default_views() more readable.

NOTE: Currently assumes all tables not in the tripal views integration tables are Drupal tables.

Parameters
$viewThe default view definition object
Returns
The default view with all relationships, fields, filters, sorts, arguments for Drupal tables removed.

◆ tripal_rebuild_views_integrations()

tripal_rebuild_views_integrations (   $delete_first = FALSE)

Rebuilds all the default integrations.

This essentially clears the cache in case you mess up the integrations in your site. This should not be used during module development since it really only rebuilds the integrations described by all enabled modules in the site and if $delete_first is TRUE it can delete custom integrations created by site administrators which will not make your module popular.

Parameters
$delete_firstIf TRUE then all integrations are first deleted.

◆ tripal_remove_join_from_views_integration()

tripal_remove_join_from_views_integration (   $setup_id,
  $base_table,
  $base_field,
  $left_table,
  $left_field 
)

Remove a join from an integration. This is usually done after cloning an existing integration using tripal_clone_views_integration().

Parameters
$setup_idThe setup_id of the integration to delete the join from.
$base_tableThe name of the base table involved the join.
$base_fieldThe field from the base table involved in the join.
$left_tableThe name of the other table involved in the join
$left_fieldThe name of the field from the other table involved in the join.

◆ tripal_remove_views_integration()

tripal_remove_views_integration (   $identifiers,
  $options = [] 
)

Removes a View Integration Entry when you only know the table the integration was created for and the priority.

This should only be used to remove integrations created by your own module (possibly on uninstall of your module). To override existing integrations simply create your own integration with a lighter priority using tripal_clone_views_integration() or tripal_export_views_integration() to create a template.

Parameters
$identifiesAn array of identifiers where the keys indicate what the identifier is. One of the following compinations must be present: 1) table_name & priority: the name of the table & the priority to remove a views integration entry for. 2) setup_id: the setup_id of the entry to remove.
$optionsAn array of options, currently none are supported.
Returns
TRUE on Success; FALSE otherwise.

◆ tripal_update_views_integration()

tripal_update_views_integration (   $setup_id,
  $defn_array 
)

Update an existing Views Intregration Entry. This essentially removes and then re-adds the integration.

Parameters
$setup_idThe setup ID of the views integration entry to update
$defn_arrayAn array describing the structure and fields of the table as is used in tripal_add_views_integration().
Generated by doxygen 1.9.1