Simplified Drupal Views Styling with Custom Style Plugins

Drupal’s shift to component based styling has been a much welcome change to how we plan out and organize a Drupal theme. While this has gone a long way in helping reduce duplication within our styles, figuring out the best way to apply the component styles to Drupal structures can sometimes be a challenge. Modules like SDC: Display are beginning to bridge this gap, but this doesn’t address every use case. One such scenario is applying component styles to a Views list.

No One Size Fits All

Let’s imagine that we have a simple grid component in our design system. This simple component accepts props for the items and column_count. This simple grid is going to be used all throughout the project and specifically across multiple View displays. There are a couple of common approaches to tackle this.

Apply the Styles Globally

One option is to make the grid styles globally available, then use something like the HTML List plugin provided by Views to add the classes we need through the UI. While it keeps all of the config in Drupal’s UI where other developers might first look to replicate and make changes, we’ve made styles global that we likely don’t need on every page. It also requires detailed knowledge of the design system to know which CSS classes to apply and where to apply them to accomplish the desired styles.

Override View Twig Templates

Another option is to move all of the styling to the Twig templates for those View displays. For example, on a list of blog posts we could create a template like views-view-unformatted–blog-posts.html.twig. Once we have that template, we call our grid component:

{{ include('my_theme:grid', {
 items: rows|map(row => row.content),
 column_count: ‘4’,
}, with_context = false) }}

Now anytime we want to apply this to a new View, all we have to do is copy/paste this into a template for that View and update any needed props. The drawback here is that the Views UI won’t reflect where the styles are coming from, or how to recreate them, and a front-end developer familiar with the theme would have to do the copy/pasting. 

Moving Back into the UI

Creating a custom Views style plugin gives us the best of both worlds. We still can leverage all the benefits of SDC, but expose all the options to site builders to apply to Views keeping the UI intact with the output. Let’s walk through the steps to get it done.

To start, in a custom module, create a new style plugin within \Drupal\my_module\Plugin\views\style. This plugin should extend \Drupal\views\Plugin\views\style\StylePluginBase. At its simplest, all a style plugin needs is:

<?php
 
declare(strict_types=1);
 
namespace Drupal\my_module\Plugin\views\style;
 
use Drupal\views\Plugin\views\style\StylePluginBase;
 
/**
* Style plugin to render results in a grid.
*
* @ingroup views_style_plugins
*
* @ViewsStyle(
*   id = "my_module_grid",
*   title = @Translation("Custom Grid"),
*   help = @Translation("Render results in a grid layout."),
*   theme = "views_view_my_module_grid",
*   display_types = { "normal" }
* )
*/
class MyModuleGrid extends StylePluginBase {
}

This will provide a new option when configuring a View style called “Custom Grid” without extra configuration. It will output the View rows through a new Twig template defined in the theme option within the annotation. In our case: views-view-my-module-grid.html.twig.

Before getting into the markup, we need to align our new template with other View style plugin templates:

/**
* Implements template_preprocess_HOOK().
*/
function my_module_preprocess_views_view_my_module_grid(&$variables) {
template_preprocess_views_view_unformatted($variables);
}

From there you can customize your new template as you would a standard views-view-my-unformatted.html.twig. template.

Adding Configuration to the Plugin

Currently the way our style plugin is set up assumes we want it to work the same everywhere. However most front-end systems like SDC allow components to be modified by passing props into them. For a grid component, allowing for the number of columns to be configured would give this component more flexibility. We can easily choose which props are exposed in Views to site builders.

First, we modify our plugin class:

class MyModuleGrid extends StylePluginBase {
 
/**
 * {@inheritdoc}
 */
protected function defineOptions(): array {
  return parent::defineOptions() + [
    'column_count' => ['default' => '3'],
  ];
}
 
/**
 * {@inheritdoc}
 */
public function buildOptionsForm(&$form, FormStateInterface $form_state) {
  parent::buildOptionsForm($form, $form_state);
 
  $form['column_count'] = [
    '#type' => 'select',
    '#title' => $this->t('Column Count'),
    '#description' => $this->t('The number of columns for the grid to use on desktop.'),
    '#default_value' => $this->options['column_count'],
    '#options' => [
      '3' => $this->t('Three Columns'),
      '4' => $this->t('Four Columns'),
    ],
  ];
}
 
}

The ::defineOptions() method here provides the default settings for what our form will control. In this case, setting the column_count to 3. ::buildOptionsForm() does exactly what it sounds like: it creates the form that site builders will interact with.

Next, we need to make these options available to our Twig file. To do this, we update our preprocess function from earlier:

function my_module_preprocess_views_view_my_module_grid(&$variables) {
$options = $variables['view']->style_plugin->options;
$variables['options'] = $options;
 
template_preprocess_views_view_unformatted($variables);
}

Finally, we update our Twig template to use the new options:

{{ include('my_theme:grid', {
 items: rows|map(row => row.content),
 column_count: options.column_count,
}, with_context = false) }}

Scratching the Surface

With all this in place, we can now update our Views to use this new Style plugin. And anyone with a basic understanding of Drupal views can recreate these styles when setting up new Views. There’s a lot more that can be done with Views style plugins. What other Views style plugins functionality do you want us to demonstrate? Let us know in the comments.