[Drupal 8] - Creating Views Display Plugin

Creating views display style plugin might seem like complex task but it is not. Here are the steps to achieve this with example code.

Before going further, make sure you have basic introduction to Drupal 8 modules. You can check that here.

.info.yml file
Create directory for our module, say my_scroller under /modules/custom. Create a file my_scroller.info.yml with below code:

name: My Style
type: module
description: 'Provides a views display style for listings.'
package: Views
core: '8.x'
dependencies:
  - views

Plugin Class
Create a plugin class file as Scroller.php inside src/Plugin/views/style and add below code.

<?php

/**
 * @file
 * Definition of Drupal\my_scroller\Plugin\views\style\Scroller.
 */

namespace Drupal\my_scroller\Plugin\views\style;

use Drupal\core\form\FormStateInterface;
use Drupal\views\Plugin\views\style\StylePluginBase;

/**
 * Style plugin to render listing.
 *
 * @ingroup views_style_plugins
 *
 * @ViewsStyle(
 *   id = "scroller",
 *   title = @Translation("Scroller"),
 *   help = @Translation("Render a listing of view data."),
 *   theme = "views_view_scroller",
 *   display_types = { "normal" }
 * )
 *
 */
class Scroller extends StylePluginBase {
  /**
   * Set default options
   */
  protected function defineOptions() {
    $options = parent::defineOptions();
    $options['height'] = array('default' => '354');
    return $options;
  }

  /**
   * {@inheritdoc}
   */
  public function buildOptionsForm(&$form, FormStateInterface $form_state) {
    parent::buildOptionsForm($form, $form_state);

    $form['height'] = array(
      '#type' => 'textfield',
      '#title' => $this->t('Height'),
      '#description' => $this->t('Default height of header.'),
      '#size' => '6',
      '#default_value' => $this->options['height'],
      '#required' => TRUE,
      '#field_suffix' => 'px',
    );
  }
}

Let's go through above code.

* @ViewsStyle(
*   id = "scroller",
*   title = @Translation("Scroller"),
*   help = @Translation("Render a listing of view data."),
*   theme = "views_view_scroller",
*   display_types = { "normal" }
* )

These comments are important. The code won't work properly untill you add them.

Basic plugin definition.

protected function defineOptions() {
  $options = parent::defineOptions();
  $options['height'] = array('default' => '354');
  return $options;
}

Here we can define default values for options we want to provide for our style plugin.

public function buildOptionsForm(&$form, FormStateInterface $form_state) {
  parent::buildOptionsForm($form, $form_state);

  $form['height'] = array(
    '#type' => 'textfield',
    '#title' => $this->t('Height'),
    '#description' => $this->t('Default height of header.'),
    '#size' => '6',
    '#default_value' => $this->options['height'],
    '#required' => TRUE,
    '#field_suffix' => 'px',
  );
}

Here we can provide options so our plugin can be customized. Creating options is much like regular config form. For more info, you can refer Form API Reference.

.module file
This is where theming information required for our plugin will go.

<?php

/**
 * @file
 * My Scroller Views module help and theme functions.
 */

// Store Scroller preprocess theme functions in a separate .inc file.
\Drupal::moduleHandler()->loadInclude('my_scroller', 'inc', 'my_scroller.theme');

/**
 * Implements hook_theme().
 */
function my_scroller_theme($existing, $type, $theme, $path) {
  return array(
    'scroller' => array(
      'file' => 'my_scroller.theme.inc',
    ),
  );
}

We are using separate file for preprocess function just to keep things organized.

.theme.inc file
Create a file called my_scroller.theme.inc in our module directory and include the following code

<?php

/**
 * @file
 * Theme for My Scroller views.
 */

/**
 * Prepares variables for views scroller templates.
 *
 * Default template: views-view-scroller.html.twig.
 *
 * @param array $variables
 *   An associative array containing:
 *   - view: A ViewExecutable object.
 *   - rows: The raw row data.
 */
function template_preprocess_views_view_scroller(&$variables) {
  // View options set by user.
  $options = $variables['view']->style_plugin->options;
  $rows = $variables['rows'];
  // Apply required logic and add variables here. We can define variable in
  // our hook_theme and use it here.
}

This code basically used to apply required logic and create variables which are passed on to the template for final rendering, along with the other options defined in the form that remain unchanged.

Twig template
Now for the output of the style, create a file called views-view-scroller.html.twig inside a folder called templates. This name depends on the comments we added while defining our style in Scroller.php as below:

This means the template is to be found at the default location (/templates) with that name, only with dashes instead of underscores and .html.twig at the end.

Now only thing remaining is to use our variables and add required HTML in twig file.

That's it! You should now be able to write your own Views Display Plugin for Drupal 8. Happy coding!