Creating custom Views header handler in Drupal 7

Posted on 01/03/2016

Views is probably one of the most useful Drupal modules for both developers and website builders. Chances are that you will rely on using Views even when you store the data in your custom tables, because of the additional features you get - from user interface, to caching and filtering.

This article will be a short example showing how to create a custom field handler that can be used for generating content for views header.

To start, you can use the blank custom module template if you don't have already your own custom module.

First you need to inform Views that your module wants to integrate with Views. You do that by adding hook_views_api() implementation in your .module file:

  1. /**
  2.  * Implements hook_views_api().
  3.  */
  4. function YOUR_MODULE_views_api() {
  5.   return array(
  6.     'api' => 3,
  7.     'path' => drupal_get_path('module', 'YOUR_MODULE') . '/views',
  8.   );
  9. }

This will tell the Views that:

  • You will be using version 3 of Views API.
  • That Views should try to find the includes in /views folder of your module. Most contrib modules store views-related files there, and it is a good practice to name the directory the same way. If you leave this part out, all code below should be located in the .module file.

The next step is to create the /views/YOUR_MODULE.views.inc file, and add a hook_views_data() implementation there. This file will be automatically loaded by Views, and you do not need to add it in the .info file of your module. This file should also contain all Views hooks you will use.

Here is the code for hook_views_data() implementation:

  1. /**
  2.  * Implements hook_views_data().
  3.  */
  4. function YOUR_MODULE_views_data() {
  5.   $data = array();
  6.   $data['views']['YOUR_MODULE_area_text_custom'] = array(
  7.     'title' => t('Custom field'),
  8.     'help' => t('Just a field created for development purposes.'),
  9.     'area' => array(
  10.       'handler' => 'YOUR_MODULE_views_handler_area_text_custom',
  11.     ),
  12.   );
  13.  
  14.   return $data;
  15. }

Finally, we need to create the class that will prepare the output, and optionally present a configuration form for administrators. When rendering the output, you can get as creative as you want - you can load custom templates you provided in your module with hook_theme() or simply show a dynamic string:

  1. /**
  2.  * Custom views handler.
  3.  */
  4. class sample_views_handler_area_text_custom extends views_handler_area_result {
  5.   function options_form(&$form, &$form_state) { }
  6.   function render($empty = FALSE) {
  7.     global $user;
  8.     return t('Hello, @name', array('@name' => format_username($user)));
  9.   }
  10. }

You can add any kind of logic here, and you can declare your own custom classes that will help rendering the content. Here are a few examples: display different output depending on the user role, load configuration from admin, show a template provided in your custom module, and so on.

Update: James Robertson pointed out below that I forgot to mention two things:

  1. The handler code should be placed in /views/handlers/YOUR_MODULE_area_text_custom.inc
  2. That file needs to be added to the info file of your custom module. Here's the code you need to add there:

    1. files[] = views/handlers/YOUR_MODULE_area_text_custom.inc

Further reading:

  • See the source of default header fields provided by Views. This is the best way to learn. They are located in /views/handlers folder.
  • hook_views_data()