Add a field to an Existing Default View

Tripal Version: 
Requirements: 
Tripal Views
Short Description: 

This tutorial will show to how to alter the generic default views that come with Tripal by adding fields using two steps:

  1. Alter the view through the Views UI.
  2. Store the changes in code in a custom module (optional).

Introduction

Tripal ships with a number of very generic default views. This allows users to immediately see their data "out-of-the-box". However, in the effort to make these views suit as many people as possible, they may not be ideal for you depending upon your requirements and data. This tutorial will show to how to alter those default views by adding fields.

Alter the view through the Views UI

The interface for creating and altering views is provided by the Drupal Views module and can be found at Structure → Views (admin/structure/views) in the Administration toolbar. This will bring you to a long list of all the views currently available on your Drupal website. Since this list is very long due to Tripal providing you with a large number of views, I always recommend you change the settings (click the settings tab near the top right) to "Show filters on the list of views" as this will allow you to filter the list of views and hopefully make it easier to find the view you are interested in.

For this tutorial we are going to modify the "Feature User Search" view which provides the Feature search under the Navigation → Search Data → Features link. This view has the "tripal search" tag to indicate that it's one of the views providing Tripal search capabilities to your users and is of type "chado feature" to indicate that it displays primarily data from the chado feature table. Furthermore, it will say "In code" under the view name to indicate that it is an unaltered, default view. Once we make the changes through the UI this label will change to "Overriding code". Go ahead and click on "Edit" beside this view.

Screenshot showing the Feature User Search view in the Views UI.

This will bring you to the Views Edit UI which you may or may not already be familar with. In this tutorial we are going to add a field. To do this you click on the "Add" button beside the field header (see 1st figure below). This will overlay a list of fields to add including all those available for the chado feature table and also fields from related tables (ie: cvterm [feature type], organism and dbxref [database references]). We're going to add the organism Genus & Species fields to the current view. Just select "Organism" from the filter drop-down, then check the "Chado Organism: Genus" & "Chado Organism: Species" fields and finally click "Apply (all displays)" to add the fields (see 2nd figure below).

Once you click "Apply (all displays)", the next two screens provide options to configure each field you would like to display (see the figure below). For this tutorial just leave the defaults and click "Apply (all displays)" on each configuration screen until you are brought back to the main Views Edit UI.

Now you should be able to see the two fields you just added at the bottom of the "Fields list (see figure below). To edit these fields, just click on their name and to re-order them, click on "Rearrange" which can be accessed by clicking on the yellow circle indicated in the figure below. Once you are happy with the felds you've added, click "Save" (See green circle in figure below) to make the changes live!

That's it, you've modified a default view! These changes are unique to your current Tripal website. If you want to make them available on another website, you will need to follow the next step which creates a module storing these changes that can then be installed on any Drupal/Tripal website.

Store the changes in code in a custom module

This part assumes you aready have a custom module. If you don't have a custom module yet, take a look at this tutorial: CREATING YOUR FIRST MODULE IN DRUPAL 7 [PACKT] (you don't need to buy the book just scroll down to the text).

Now, before we can do anything with views in our custom module we have to implement hook_views_api() in our .module file. This essentially tells views to include the files views expects to be in our module including [yourmodule].views.inc (create a blank file with this name in the base directory of your module). In all the code samples, replace [yourmodule] with the machine name of your module.


/**
 * Implements hook_views_api().
 *
 * Registers your module with Views so that it knows to look for & include a [yourmodule].views.inc file. 
 */ 
function [yourmodule]_views_api() { 
  return array(
    'api' => 3,
    'path' => drupal_get_path('module', '[yourmodule]') . '/includes/views',
    'template path' => drupal_get_path('module', '[yourmodule]') . '/themes',
  );
} 

Next you want to implement hook_views_default_views_alter() in your [yourmodule].views.inc file (don't forget to inlcude an opening php tag at the top of the file). Since the $views variable passed into this hook contains all default views, we need to use $views['machinenameofview'] to access the particular view we are interested in (in our case $views['tripal_feature_user_feature'] The machine name of your view is in the path when you are editing it).

Background: When views are stored in code they are defined in a views object. A views is made up of displays which contain fields, filters and sort criteria. However, we can't access each display directly using the object but instead need to instantiate a "handler" to modify a display using the "new_display" method.

Any modifications we make to this views object will be made to the default view and while you can just print it to the screen and try to modify it directly, I highly suggest making the changes you want through the  Views UI and then examining the export of the view for the changes. For example, following the example we created above, go back to the views UI (admin/structure/views) and find the "Feature User Search" view that we editing previously (see the 1st figure in this tutorial for a reminder). Now, instead of clicking edit, click on the arrow on the right-hard side of the edit button and then on "Export". This will give you the code needed to move your entire view to a new Drupal site and is actually just a definition of the views object mentioned above.  All of the code we need is in this export, we just need to know where to look!

First, look to the second paragraph of your export. It should begin with a method call to instantiate a handler for modifying the main display (see figure below).

We need to use this method to get a handler object which can be used to modify the default view we are interested in. Simply copy/paste this line into your hook_views_default_views_alter() as is shown below:


/**
 * Implements hook_views_default_views_alter().
 *
 * Modify a default view.
 */ 
function [yourmodule]_views_default_views_alter(&$views) {

  // Check that the "Feature User Search" Default Views is defined.
  // We do this because it's only defined when the Tripal Feature module is enabled.
  if (isset($views['tripal_feature_user_feature'])) {
    
    // We copied most of this line from the views export
    // and just changed $view to $views['tripal_feature_user_feature']
    // to ensure we are working with only the default view we are interested in.
    $handler = $views['tripal_feature_user_feature']->new_display('default', 'features_all', 'default');
  
  }
} 

Next we need to use this handler to add our fields. Luckily the views export does that same thing so again we can just copy/paste it. To find the fields you are interested in (in our case Organism Genus & Species) just scroll through the views export until you see a comment saying /* Field: Chado Organism: Genus */ as seen in the following figure.

Copy the entire field definition (until the next section denoted by a comment) and paste it into the hook definition we already started as shown below:


/**
 * Implements hook_views_default_views_alter().
 *
 * Modify a default view.
 */ 
function [yourmodule]_views_default_views_alter(&$views) {

  // Check that the "Feature User Search" Default Views is defined.
  // We do this because it's only defined when the Tripal Feature module is enabled.
  if (isset($views['tripal_feature_user_feature'])) {
    
    // We copied most of this line from the views export
    // and just changed $view to $views['tripal_feature_user_feature']
    // to ensure we are working with only the default view we are interested in.
    $handler = $views['tripal_feature_user_feature']->new_display('default', 'features_all', 'default');
 
    // Now add the fields to the handler.
    // This code is copy/pasted from the views export.
    /* Field: Chado Organism: Genus */
    $handler->display->display_options['fields']['genus']['id'] = 'genus';
    $handler->display->display_options['fields']['genus']['table'] = 'organism';
    $handler->display->display_options['fields']['genus']['field'] = 'genus';
    /* Field: Chado Organism: Species */
    $handler->display->display_options['fields']['species']['id'] = 'species';
    $handler->display->display_options['fields']['species']['table'] = 'organism';
    $handler->display->display_options['fields']['species']['field'] = 'species';

  }
} 

Now just enable your module and clear the cache (drush cc all from the command-line) to get Views to see your changes and update the default View. Then go into the Views UI and Revert the "Feature User Search" view using the "Revert option under the edit dropdown when export was. And that's it!

Category: