Views 1 theming

Much of the power of Views cannot be fully realized until an administrator gets accustomed to theming. Views may be themed at various levels, with each level providing either more or less control:

1. Each field printed may be themed individually (valid in table/list views). This requires understanding the name of the field you want to theme.
2. Each view may be themed by type -- meaning a view that provides teasers in page mode and a list in block mode may have each mode themed separately.
3. Each view may be completely themed. This requires understanding a bit about what makes up a complete view.

For all of these functions, the _VIEWNAME is optional; if the viewname is not part of the theme function, you will override theming for all of your views.

The Theming Wizard

Views now comes with a new module, views_theme_wizard.module, which will allow you to generate a theming function and template for your views if you happen to be using a PHPTemplate theme. At the moment it only works for list views, but these are the views that are actually difficult. Using the wizard is quite simple; select a view and run the wizard. It generates code for your template.php and a viewname.tpl.php which you can drop right into your theme directory. You can then make adjustments to this.

Note that if you just want to theme a 'teaser' view, the simplest way to accomplish this is to override the teaser function, and change the node_view() function to something like this:

Then, in your node.tpl.php (or node-type.tpl.php) you can do:

and theme your node as per the normal node theming.

Theme Functions

When using theming functions, you should consult the Drupal theming documentation for detail on what this stuff does and how to deal with it. In particular, read Using Theme Override Functions in order to override Drupal's default theming.

function theme_views_view_TYPE_VIEWNAME($view, $nodes);

This is called after all of the header and before any footer information are displayed. This is likely to be the most commonly used theme function simply due to its relative simplicity. All this function has to do is loop over the $nodes array and display the data based upon the type of the view. By default, the TYPE may be one of:

• list
• table
• teasers
• nodes

but plugins could offer other types that may also be themed (and for these you will need the plugin's theme function name, rather than the plugin type name, ie theme_views_rss_feed_VIEWNAME).

This function themes a particular view for a particular type, thus not interfering with any of your other views.

<?php
/**
* Display the nodes of a view as a list.
*/
function theme_views_view_list($view, $nodes, $type) {
  $fields = _views_get_fields();

  foreach ($nodes as $node) {
    $item = '';
    foreach ($view->field as $field) {
      if (!isset($fields[$field['id']]['visible']) && $fields[$field['id']]['visible'] !== FALSE) {
        if ($field['label']) {
          $item .= "<div class='view-label ". views_css_safe('view-label-'. $field['queryname']) ."'>" . $field['label'] . "</div>";
        }
        $item .= "<div class='view-field ". views_css_safe('view-data-'. $field['queryname']) ."'>" . views_theme_field('views_handle_field', $field['queryname'], $fields, $field, $node, $view) . "</div>";
      }
    }
    $items[] = "<div class='view-item ". views_css_safe('view-item-'. $view->name) ."'>$item</div>\n"; // l($node->title, "node/$node->nid");
  }
  if ($items) {
    return theme('item_list', $items);
  }
}

/**
* Display the nodes of a view as a table.
*/
function theme_views_view_table($view, $nodes, $type) {
  $fields = _views_get_fields();

  foreach ($nodes as $node) {
    $row = array();
    foreach ($view->field as $field) {
      if ($fields[$field['id']]['visible'] !== FALSE) {
        $cell['data'] = views_theme_field('views_handle_field', $field['queryname'], $fields, $field, $node, $view);
        $cell['class'] = "view-field ". views_css_safe('view-field-'. $field['queryname']);
        $row[] = $cell;
      }
    }
    $rows[] = $row;
  }
  return theme('table', $view->table_header, $rows);
}


/**
* Display the nodes of a view as teasers.
*/
function theme_views_view_teasers($view, $nodes, $type) {
  return views_theme('views_view_nodes', $view, $nodes, $type, true);
}

/**
* Display the nodes of a view as plain nodes.
*/
function theme_views_view_nodes($view, $nodes, $type, $teasers = false, $links = true) {
  foreach ($nodes as $n) {
    $node = node_load($n->nid);
    $output .= node_view($node, $teasers, false, $links);
  }
  return $output;
}
?>

function theme_views_view_VIEWNAME($view, $type, $nodes, $level = NULL, $args = NULL);

When Views attempts to display a view, first it attempts to call theme('views_view_VIEWNAME'). If this function does not exist, then it will call theme('views_view'), which is the default method of displaying a view. As a themer, you can override either one, but in general it's better to override the specific one.

The $view argument will be the full definition of the view from the database.

The $type argument will be either 'block', 'page' or 'embed'. (It can actually be other things, but anything else will be user defined. More on this later). This argument is used to control whether page or block specific display is done.

The $nodes argument will be an array with all of the information from the database nicely loaded.

if $level is set to a positive value, this means the view is a summary view, and should be sent to the summary theme instead of the normal type theme.

<?php
/**
* Display a view.
*/
function theme_views_view($view, $type, $nodes, $level = NULL, $args = NULL) {
  $num_nodes = count($nodes);

  if ($type == 'page') {
    drupal_set_title(filter_xss_admin(views_get_title($view, 'page')));
    views_set_breadcrumb($view);
  }

  if ($num_nodes) {
    $output .= views_get_textarea($view, $type, 'header');
  }

  if ($type != 'block' && $view->exposed_filter) {
    $output .= views_theme('views_display_filters', $view);
  }

  $plugins = _views_get_style_plugins();
  $view_type = ($type == 'block') ? $view->block_type : $view->page_type;
  if ($num_nodes || $plugins[$view_type]['even_empty']) {
    if ($level !== NULL) {
      $output .= "<div class='view-summary ". views_css_safe('view-summary-'. $view->name) ."'>". views_theme($plugins[$view_type]['summary_theme'], $view, $type, $level, $nodes, $args) . '</div>';
    }
    else {
      $output .= "<div class='view-content ". views_css_safe('view-content-'. $view->name) ."'>". views_theme($plugins[$view_type]['theme'], $view, $nodes, $type) . '</div>';
    }
    $output .= views_get_textarea($view, $type, 'footer');

    if ($type == 'block' && $view->block_more && $num_nodes >= $view->nodes_per_block) {
      $output .= theme('views_more', $view->real_url);
    }
  }
  else {
    $output .= views_get_textarea($view, $type, 'empty');
  }

  if ($view->use_pager) {
    $output .= theme('pager', '', $view->pager_limit, $view->use_pager - 1);
  }

  if ($output) {
    $output = "<div class='view ". views_css_safe('view-'. $view->name) ."'>$output</div>\n";
  }
  return $output;
}
?>

function theme_views_summary_VIEWNAME($view, $type, $level, $nodes, $args);

If a given view has a summary mode -- in which a listing of possible choices for arguments are given -- theme('views_view_summary_VIEWNAME') will be called instead. This is a very good choice to override, because views doesn't really give the admin many options for how to display this, and there are many different possibilities.

$view contains the database view information.

$type contains the same information as theme_views_view().

$level is a number stating which argument this summary is for, starting from 0. If a view has multiple arguments (for example, view/archive/year/month/day) the summary could be for the year (0), the month (1) or the day (2).

$nodes will be an array of database information for the summary.

$args will be the arguments actually present; in the above example will be an empty array if $level = 0, but will contain the year if $level = 1 and the year and the month if $level = 2.

<?php
/**
* Display a summary version of a view.
*/
function theme_views_summary($view, $type, $level, $nodes, $args) {
  foreach ($nodes as $node) {
    $items[] = views_get_summary_link($view->argument[$level]['type'], $node, $view->real_url)  . " (" . $node->num_nodes . ")";
  }
  if ($items) {
    $output .= theme('item_list', $items);
  }

  return $output;
}
?>

function theme_views_more($name);

This simple theme function formats the 'more' link.

<?php
/**
* Format the 'more' link for a view. Personally I prefer [More] but I've
* been convinced to go with simply 'more'.
*/
function theme_views_more($url) {
  return "<div class='more-link'>" . l(t('more'), $url) . "</div>";
}
?>

function theme_views_handle_field_TABLENAME_FIELDNAME($fields, $field, $data);

You can theme each piece of individual data by overriding this theme function. Do so with care, as using it properly requires understanding what the data you're receiving is.

<?php
/**
* Themeable function to handle displaying a specific field.
*/
function theme_views_handle_field($fields, $field, $data) {
  $info = $fields[$field['fullname']];

  if ($field['handler'] && function_exists($field['handler'])) {
    return $field['handler']($info, $field, $data->$field['queryname'], $data);
  }

  if ($info['handler'] && is_string($info['handler']) && function_exists($info['handler'])) {
    return $info['handler']($info, $field, $data->$field['queryname'], $data);
  }

  return check_plain($data->$field['queryname']);
}
?>

function theme_views_filters_VIEWNAME($form)

For 4.7: This theme function lets you change how the exposed filters are displayed.

<?php
function theme_views_filters($form) {
  $view = $form['view']['#value'];
  foreach ($view->exposed_filter as $count => $expose) {
    $row[] = form_render($form["op$count"]) . form_render($form["filter$count"]);
    $label[] = $expose['label'];
  }
  $row[] = form_render($form['submit']);
  $label[] = ''; // so the column count is the same.
  return theme('table', $label, array($row)) . form_render($form);
}
?>

For 5.x: This theme function lets you change how the exposed filters are displayed.

<?php
function theme_views_filters($form) {
  $view = $form['view']['#value'];

  foreach ($view->exposed_filter as $count => $expose) {
    $row[] = drupal_render($form["op$count"]) . drupal_render($form["filter$count"]);
    $label[] = $expose['label'];
  }
  $row[] = drupal_render($form['submit']);
  $label[] = ''; // so the column count is the same.

  // make the 'q' come first
  return drupal_render($form['q']) . theme('table', $label, array($row)) . drupal_render($form);
}
?>

The savvy reader will note that a large section of this documentation has, in fact, disappeared. Most of it was rendered irrelevant by the compartmentalization of the theming functions. It is the author's hope that the code snippets will be sufficient to guide you into what needs to be done, and that later tutorials can provide more interesting information.