A Views 3 style controls how the output is formatted and allows the user to set predefined values. Using custom styles, programmers can create very unique looking lists such as charts, graphs, and time lines. In the example below, I will explain how to start a Views 3 style using a simple timeline as an example. The timeline above is an example of using Views displaying individual nodes called Timeline Events in an attractive display.

To hack into view (without actually hacking it) you must create a custom module. Your .info file will be very basic, just make sure you add views as a dependency:

name = Simple Timeline description = Allows the user to create a simple time line using views core = 7.x package = Custom version = 7.0 dependencies[] = views

The .info file tells Drupal Views that your module has information will interact with it. In the module itself (called [module].views.inc replacing [module] with your module's name), you indicate that you are interacting with Views three by processing the line 'api' => 3. When using Views 2 you would simply replace this with 'api' => 2. Now we want to tell Views that we will be create a custom style by implementing hook_views_plugin().

/**
 * Implements hook_views_api()
 *
 * Returns what version of views you are using. Ex 7.3x would be 3
 */
function simple_timeline_views_api() {
  return array(
    'api' => 3,  // we are using views 3
  );
}

Now lets hook into views. In your .module file, you want to let views know that you want to interact with it.

/**
 * Implements of hook_views_plugins(). Adds a view style to views UI interface.
 */
function simple_timeline_views_plugins() {
  return array(
    'style' => array(
      'timeline' => array(
        'title' => t('Simple Timeline'),
        'help' => t('Displays content on a timeline'),
        'handler' => 'views_plugin_style_simple_timeline',
        'theme' => 'views_view_timeline',
        'uses fields' => TRUE,
        'uses options' => TRUE,
        'type' => 'normal',
        'even empty' => TRUE,
      ),
    ),
  );
}

Let's break down the code. The function returns an array of options that may be style, row, or display. In this case we are returning a single style called "Simple Timeline". You can add multiple styles this way in a single function. Each style uses a number of keys:

  • The title key declares the name of the style. When choosing a style in the styles list in the Views 3 UI you will see "Simple Timeline". This is wrapped in the t() function for localization, but it is not absolutely required.
  • The help key shows a brief description about the style.
  • The handler key declares the class and fields used to alter the style. This contains the style options.
  • The theme key declares our theming file. Notice how .tpl.php is not appended to the name as this is done automatically by views.
  • Uses fields lets the view know that the style uses fields. As an example, RSS feeds do not use fields, but, for the most part, you want this to be true.
  • Uses options allows the user to manipulate the view so each style may be a little unique. In the case of a time line, this could be background color, height, width, or any text you want to appear.
  • Type is set to normal. (I have not researched other options.)
  • Even empty is set to TRUE. (Again, I have not researched other options.)

Now, Views has a type, name, and knows where to look for a handler and template file. The key 'handler' states that we will be using a file called views_plugin_style_simple_timeline.inc. We will add options in this file allowing the end user to allow style manipulation. After all, that's what a views style is for: manipulating output.

Here is a look at a basic time line class with only a few options;

/**
 * Timeline style plugin that structures the results in the form of a single linear time line.
 *
 * @ingroup views_style_plugins
 */
class views_plugin_style_simple_timeline extends views_plugin_style {
  /**
   * Set default options
   */
  function options(&$options) {
    $options['height'] = array('default' => '300px');
    $options['width'] = array('default' => '100%');
    $options['title_main'] = array('default' => 'My Timeline');
    return $options;  // Not necessary to return or pass by reference? Users call on what they want to do
  }
 
  /**
   * Create forms to hold these values allowing the user to change the values
   */
  function options_form(&$form, &$form_state) {
    $form['height'] = array(
      '#type' => 'textfield',
      '#title' => t('Height'),
      '#size' => '30',
      '#description' => t('This field determines how tall the timeline will be'),
      '#default_value' => $this->options['height'],
    );
    $form['width'] = array(
      '#type' => 'textfield',
      '#title' => t('Width'),
      '#size' => '30',
      '#description' => t('This field determines how wide the timeline will be'),
      '#default_value' => $this->options['width'],   
    );
    $form['title_main'] = array(
      '#type' => 'textfield',
      '#title' => t('Main Title'),
      '#size' => '30',
      '#description' => t('Uses the larger title font on the timeline'),
      '#default_value' => $this->options['title_main'],   
    );
  } 
}

The above code simply extends the style base class of views_plugin_style and adds a few custom options. Views looks exclusively for two functions: options(&$options) and options_form(&$form, &$form_state). The options function just sets the default values for the options_form function. The options_form function allows the user to use Drupal Form API to create forms that the end user can manipulate.

When the end user fills out the forms you declared in the options of the style, new variables will be available. These variables are passed to the theming file that was declared in hook_views_plugins through the theme key. In this specific case, the value of the theme key is views_view_timeline. Views will search for a file called views_view_timeline.tpl.php for the theming information. As a quick test to see if the template file is being found correctly, we are printing a simple message.

If you preview the view or page it should simply say "Hello Timeline". This is a basic step, but just a little fat-fingering will cause you to spend unnecessary research time just to discover your template file is spelled incorrectly. Now, let's pass our options variables to the template file so we can start manipulating the output according to the user's preferences. A template preprocessor is a great way to organize variables before being sent to the template file. Generally, people don't like to have variable manipulation in your template file. If you have to do math or alter a variable, do it in the preprocessor. As a rule, it is best to keep the template file as simple as possible.

/**
 * Implementation of template_process for views-view-simple-timeline.tpl.php.
 */
function template_preprocess_views_view_timeline(&$vars) {
  $vars['height'] = $vars['options']['height'];
  $vars['width'] = $vars['options']['width'];
  $vars['main_title'] = $vars['options']['title_main'];
 
  // Other variables can be obtained. Try doing a dpm() on $vars. If you say what is dpm(), you need the devel module!!!
  $vars['display'] = $vars['view']->current_display;
}
The preprocessor allows us to grab and use variables in the template file much more easily. Instead of printing $vars['options']['height'], $height would just be needed. Themers appreciate this technique as they don't have to deal with arrays and objects. Now, let's put a few of our options into the template file.

Of course, with a traditional time line, you would add date mapping so you have a place to set the tick marks, but for the sake of brevity, I will stop here. Just add options and play around with the template file and you will be amazed at what you can do with a simple custom views style. The time line at the top of this page is just a small example of the many different lists you can create through custom Views styles