Views 3 Styles

Views 3 is an extremely powerful tool for Drupal 7 that allows you to perform complex queries to the database having little to no SQL knowledge. Unfortunately there is little documentation in describing some of the incredible things you can accomplish with it by simply using it as an API. In this post I will show you how to create a new views style, or format. A style manipulates the results of a view allowing you to show them in any way you want. In this example I needed to create a time line. This time line was very simple as it was linear, years as dates, and were no date duplicates. Easy enough right?

The first thing you need to do is turn this into a module. An example of the .info file would look like:

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

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

/**
 * 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 views knows your module wants to use its API. Now lets declare our style. Put this in a *.views.inc file. In this example it will be simple_timeline.views.inc.

/**
 * Implements 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,
      ),
    ),
  );
}

Lets break this code down. The function takes no parameters and returns a large array. In this case we are returning a single style called "Simple Timeline". All styles should be declared in the styles array and the identifier should directly proceed. Our identifier is simply "timeline".

• 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 and should be used in habit, though not 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 is were the options for the styles go.
• The theme key declares our theming file. Notice how .tpl.php is not appended to the name because this is done automatically by views.
• Uses fields lets the view know that the style uses fields. A style that may not use fields are RSS feeds 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 (Not sure the other options).
• Even empty is set to TRUE (Not sure what this does).

Now we can build our back end to the style. Views uses base classes that are extensible for much of its API. In this case I like to extend the class views_plugin_style so that I have a blank canvas. If you need to add functionality to the table or grid styles, just extend those classes and you will have all of their base options. There are two basic function that you want to declare in the class: function options(&$options) and function options_form(&$form, &$form_state).

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 and allow the user to change them
   */
  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'],   
    );
  } 
}

This code is simple. I'm extending the base class and adding a few of my own options. The options function just allows me to declare default values. Think of this as the default constructor. The options_form allows you to use Drupal's form API to make your options form nice and functional with little effort on your part.

Now that we have our class and some variables, lets put them into our template file that we declared in our function simple_timeline_views_plugin(). We told the key 'theme' that its value was 'views_view_timeline' so lets make a template file called views-view-timeline.tpl.php. Note the underscores should be converted to hyphens in the template file. Our template file can be basic at this point, we just want to know it works. You can use your imagination to make it look better. For now lets just print the word "Hello Timeline" just to make sure it works.

<div id="simple-timeline">
<?php print 'Hello Timeline'; ?>
</div>

And presto! It worked. Now lets send our variables that we declared in the options of our style. We want to place these in a template preprocessor to make them cleaner. This helps things look nicer in the file. We can declare the preprocessor in the .module file, or more traditionally place it in a .inc file. The preprocessor basically looks like this:

/**
 * 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;
}

Now we can use our options in the template file by just printing $height, $width, $main_title! Easy huh? Lets take another look at the template file, but add these options!

<div id="simple-timeline" width="<?php print $width; ?>" height="<?php print $height; ?>">
<?php print $main_title; ?>
</div>

You can take the rest from here. Of course with an actual timeline you would need to map titles, dates, and descriptions but as far as styles go that should get you through the door! Below is a quick example of a time line I created this way using views. Every tick mark is a content type I created with nothing but a title, description, and date. My code automatically does the rest!