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

   1 <!-- @file Documentation for the @BootstrapPreprocess annotated plugin. -->
   2 <!-- @defgroup -->
   3 <!-- @ingroup -->
   4 # @BootstrapPreprocess
   5
   6 - [Create a plugin](#create)
   7 - [Rebuild the cache](#rebuild)
   8
   9 ---
  10
  11 ## Create a plugin {#create}
  12
  13 We'll use `Page` implemented by this base theme as an example of how to add
  14 custom classes for the `page.html.twig` template that should only be added
  15 under certain conditions.
  16
  17 Replace all following instances of `THEMENAME` with the actual machine name of
  18 your sub-theme.
  19
  20 Create a file at `./THEMENAME/src/Plugin/Preprocess/Page.php` with the
  21 following contents:
  22
  23 ```php
  24 <?php
  25
  26 namespace Drupal\THEMENAME\Plugin\Preprocess;
  27
  28 use Drupal\bootstrap\Plugin\Preprocess\Page as BootstrapPage;
  29 use Drupal\bootstrap\Utility\Element;
  30 use Drupal\bootstrap\Utility\Variables;
  31
  32 /**
  33  * Pre-processes variables for the "page" theme hook.
  34  *
  35  * @ingroup plugins_preprocess
  36  *
  37  * @BootstrapPreprocess("page")
  38  */
  39 class Page extends BootstrapPage {
  40   /*
  41    * It should be noted that you do not need all three methods here.
  42    * This is to just show you the different examples of how this plugin
  43    * works and how they can be tailored to your needs.
  44    */
  45
  46   /**
  47    * {@inheritdoc}
  48    */
  49   public function preprocess(array &$variables, $hook, array $info) {
  50     $value = isset($variables['element']['child']['#value']) ? $variables['element']['child']['#value'] : FALSE;
  51     if (_some_module_condition($value)) {
  52       $variables['attributes']['class'][] = 'my-theme-class';
  53       $variables['attributes']['class'][] = 'another-theme-class';
  54       $key = array_search('page', $variables['attributes']['class']);
  55       if ($key !== FALSE) {
  56         unset($variables['attributes']['class'][$key]);
  57       }
  58     }
  59
  60     // If you are extending and overriding a preprocess method from the base
  61     // theme, it is imperative that you also call the parent (base theme) method
  62     // at some point in the process, typically after you have finished with your
  63     // preprocessing.
  64     parent::preprocess($variables, $hook, $info);
  65   }
  66
  67   /**
  68    * {@inheritdoc}
  69    */
  70   public function preprocessVariables(Variables $variables) {
  71     // This method is almost identical to the one above, but it introduces the
  72     // Variables utility class in the base theme. This class has a plethora of
  73     // helpful methods to quickly modify common tasks when you're in a
  74     // preprocess function. It also acts like the normal $variables array when
  75     // you need it to in instances of accessing nested content or in loop
  76     // structures like foreach.
  77     $value = isset($variables['element']['child']['#value']) ? $variables['element']['child']['#value'] : FALSE;
  78     if (_some_module_condition($value)) {
  79       $variables->addClass(['my-theme-class', 'another-theme-class'])->removeClass('page');
  80     }
  81     parent::preprocessVariables($variables);
  82   }
  83
  84   /**
  85    * {@inheritdoc}
  86    */
  87   protected function preprocessElement(Element $element, Variables $variables) {
  88     // This method is only ever invoked if either $variables['element'] or
  89     // $variables['elements'] exists. These keys are usually only found in forms
  90     // or render arrays when there is a #type being used. This introduces the
  91     // Element utility class in the base theme. It too has a bucket-load of
  92     // features, specific to the unique characteristics of render arrays with
  93     // their "properties" (keys starting with #). This will quickly allow you to
  94     // access some of the nested element data and reduce the overhead required
  95     // for commonly used logic.
  96     $value = $element->child->getProperty('value', FALSE);
  97     if (_some_module_condition($value)) {
  98       $variables->addClass(['my-theme-class', 'another-theme-class'])->removeClass('page');
  99     }
 100     parent::preprocessElement($element, $variables);
 101   }
 102
 103 }
 104 ?>
 105 ```
 106
 107 ## Rebuild the cache {#rebuild}
 108
 109 Once you have saved, you must rebuild your cache for this new plugin to be
 110 discovered. This must happen anytime you make a change to the actual file name
 111 or the information inside the `@BootstrapPreprocess` annotation.
 112
 113 To rebuild your cache, navigate to `admin/config/development/performance` and
 114 click the `Clear all caches` button. Or if you prefer, run `drush cr` from the
 115 command line.
 116
 117 Voilà! After this, you should have a fully functional `@BootstrapPreprocess`
 118 plugin!