www.aleph1.co.uk Git - yaffs-website/blob - web/themes/contrib/bootstrap/docs/plugins/Process.md

   1 <!-- @file Documentation for the @BootstrapProcess annotated plugin. -->
   2 <!-- @defgroup -->
   3 <!-- @ingroup -->
   4 # @BootstrapProcess
   5
   6 - [Create a plugin](#create)
   7 - [Rebuild the cache](#rebuild)
   8
   9 ---
  10
  11 ## Create a plugin {#create}
  12
  13 {.alert.alert-warning}**Note:** This plugin is _not_ a re-implementation of the
  14 D7 `hook_process_HOOK` for theme hooks in anyway. That layer was removed from
  15 the theme system in D8 and for good reason (see:
  16 [Remove the process layer](https://www.drupal.org/node/1843650)). This plugin
  17 is about automatically adding a `#process` callback for a form element `#type`.
  18 This is especially useful when dealing with core elements that have implemented
  19 their own callbacks; either to alter their output or remove entirely.
  20
  21 We'll use `TextFormat` implemented by this base theme as an example of how to
  22 override the class entirely and remove this base theme's over-simplification
  23 for the "format tips" section.
  24
  25 Replace all following instances of `THEMENAME` with the actual machine name of
  26 your sub-theme.
  27
  28 Create a file at `./THEMENAME/src/Plugin/Process/TextFormat.php` with the
  29 following contents:
  30
  31 ```php
  32 <?php
  33
  34 namespace Drupal\THEMENAME\Plugin\Process;
  35
  36 use Drupal\bootstrap\Plugin\Process\TextFormat as BootstrapTextFormat;
  37 use Drupal\bootstrap\Utility\Element;
  38 use Drupal\Core\Form\FormStateInterface;
  39
  40 /**
  41  * Processes the "text_format" element.
  42  *
  43  * @ingroup plugins_process
  44  *
  45  * @BootstrapProcess("text_format")
  46  *
  47  * @see \Drupal\filter\Element\TextFormat::processFormat()
  48  */
  49 class TextFormat extends BootstrapTextFormat {
  50   /*
  51    * It should be noted that you do not need both methods here.
  52    * This is to just show you the different examples of how this plugin
  53    * works and how it can be tailored to your needs.
  54    */
  55
  56   /**
  57    * {@inheritdoc}
  58    */
  59   public static function process(array $element, FormStateInterface $form_state, array &$complete_form) {
  60     // You must return the element immediately if this is TRUE.
  61     if (!empty($element['#bootstrap_ignore_process'])) {
  62       return $element;
  63     }
  64
  65     // Technically this isn't the method that we need to achieve our goal.
  66     // But showing it just for example sake.
  67     //
  68     // You must always return the element in this method, as well as call the
  69     // parent method when sub-classing this method as it is used to invoke
  70     // static::processElement();
  71     return parent::process($element, $form_state, $complete_form);
  72   }
  73
  74   /**
  75    * {@inheritdoc}
  76    */
  77   public static function processElement(Element $element, FormStateInterface $form_state, array &$complete_form) {
  78     // Normally, we'd call the parent method here. But this is actually an
  79     // instance where we know we don't want to use the alterations made by
  80     // the base theme. So we just comment it out and leave the method empty.
  81     // parent::processElement($element, $form_state, $complete_form);.
  82   }
  83
  84 }
  85 ?>
  86 ```
  87
  88 ## Rebuild the cache {#rebuild}
  89
  90 Once you have saved, you must rebuild your cache for this new plugin to be
  91 discovered. This must happen anytime you make a change to the actual file name
  92 or the information inside the `@BootstrapProcess` annotation.
  93
  94 To rebuild your cache, navigate to `admin/config/development/performance` and
  95 click the `Clear all caches` button. Or if you prefer, run `drush cr` from the
  96 command line.
  97
  98 Voilà! After this, you should have a fully functional `@BootstrapProcess`
  99 plugin!