Implementation

Doing it by example

Firstly we recommend that you take a look at the Modifiers Pack for guidance on how to implement your own Modifiers. You will find a range of Modifiers there covering a number of different techniques, ranging from the simple to the complex.

Reviewing these modules will show you the full range of what is possible with Modifiers. You should be able to find the technique you need.

Doing it from Scratch

You can include your custom Modifiers into your module or theme. We will show how to use every option of Modifiers inside example Modifier called “Kitchen Sink Modifier”.

As a prerequisite you should know how to implement your custom module or theme. If you don’t, you can start with Creating custom modules or Theming Drupal 8 documentation.

Putting Modifier into your module

Step 1:

Create a new Paragraphs bundle called “Kitchen Sink Modifier” with machine name corresponding to Modifier ID “kitchen_sink_modifier”. Inside this paragraph bundle, create these fields:

• Background color (“field_background”) - “Text (plain)” to fill a color or “Color Field” to select.
• JS effect (“field_effect”) - “List (text)” with available JS effects to be applied.
• Extra class (“field_class”) - “Text (plain)” to fill a class or “List (text)” with predefined values.
• Attached stylesheet (“field_stylesheet”) - “Text (plain)” to fill an URL or “File/Media” to upload.

Step 2:

Then you need to enable this paragraph bundle for any “field_modifiers” you need, as described inside step 4 of section “Configuring your site to use the Modifiers”.

Step 3:

Create a new module folder inside “docroot/modules/custom” called “kitchen_sink” and add a module definition YAML file called “kitchen_sink.info.yml” with this content:

name: Kitchen Sink
type: module
description: Provides a Modifier to fill everything into kitchen sink.
core: 8.x
package: Modifiers
dependencies:
  - modifiers:modifiers

Step 4:

Create the module sub-folder structure “kitchen_sink/src/Plugin/modifiers” with a new file named “KitchenSinkModifier.php” inside.

Note: the id in the plugin annotation must match the entity machine name where the plugin will get its values.

Example content with all options included:

<?php

namespace Drupal\kitchen_sink\Plugin\modifiers;

use Drupal\modifiers\Modification;
use Drupal\modifiers\ModifierPluginBase;

/**
 * Provides a Modifier to fill everything into kitchen sink.
 *
 * @Modifier(
 *   id = "kitchen_sink_modifier",
 *   label = @Translation("Kitchen Sink Modifier"),
 *   description = @Translation("Provides a Modifier to fill everything into kitchen sink"),
 * )
 */
class KitchenSinkModifier extends ModifierPluginBase {

  /**
   * {@inheritdoc}
   */
  public static function modification($selector, array $config) {

    $css = [];
    $libraries = [];
    $settings = [];
    $attributes = [];
    $links = [];
    $media = parent::getMediaQuery($config);

    if (!empty($config['background'])) {
      $css[$media][$selector][] = 'background-color:' . $config['background'];
      $attributes[$media][$selector]['class'][] = 'modifiers-has-background';
    }

    if (!empty($config['effect'])) {
      $libraries = [
        'kitchen_sink/effect',
      ];
      $settings = [
        'namespace' => 'KitchenSinkModifier',
        'callback' => 'apply',
        'selector' => $selector,
        'media' => $media,
        'args' => [
          'effect' => $config['effect'],
        ],
      ];
    }

    if (!empty($config['class'])) {
      $attributes[$media][$selector]['class'][] = $config['class'];
    }

    if (!empty($config['stylesheet'])) {
      $links[] = [
        'href' => $config['stylesheet'],
        'rel' => 'stylesheet',
      ];
    }

    if (!empty($css) || !empty($libraries) || !empty($settings) || !empty($attributes) || !empty($links)) {

      return new Modification($css, $libraries, $settings, $attributes, $links);
    }
    return NULL;
  }

}

Step 5:

For a JS library to work, you need to create JS file called “kitchen_sink.effect.js” inside this module “js” sub-folder. Content could be like this:

/**
 * @file
 * Initializes modification based on provided configuration.
 */

(function (KitchenSinkModifier) {

  'use strict';

  KitchenSinkModifier.apply = function (context, selector, media, config) {

    var element = context.querySelector(selector);
    if (!element) {
      return;
    }

    // Process any effect on this element.
    if (window.matchMedia(media).matches) {
      myFunctionToApplyEffectOfSpecifiedType(element, config.effect);
    }

  };

})(window.KitchenSinkModifier = window.KitchenSinkModifier || {});

Step 6:

Last part of JS library is it’s definition using new YAML file called “kitchen_sink.libraries.yml” and placed into module folder. Example content:

effect:
  js:
    js/kitchen_sink.effect.js: {}

Step 7:

That’s it, now you need to enable this new module and your Modifier should be recognized.

Putting Modifier into your theme

Only part that is different from adding Modifier into module is additional YAML file you need to create.

Step 1:

Go into your theme folder and create file named “YOUR_THEME.modifiers.yml”.

Step 2:

Then it needs to contain the definition of all Modifiers you implemented, e.g.:

kitchen_sink_modifier:
  class: Drupal\YOUR_THEME\Plugin\modifiers\KitchenSinkModifier
  label: 'Kitchen Sink Modifier'
  description: 'Provides a Modifier to fill everything into kitchen sink'

Step 3:

That’s it, now you need to clear caches and your Modifier should be recognized.