yaffs.net Git - yaffs-website/blob - web/themes/contrib/bootstrap/docs/plugins/Alter.md

   1 <!-- @file Documentation for the @BootstrapAlter annotated discovery plugin. -->
   2 <!-- @defgroup -->
   3 <!-- @ingroup -->
   4 # @BootstrapAlter
   5
   6 - [Pre-requisite](#prerequisite)
   7 - [Supported alter hooks](#supported)
   8 - [Form alter hooks](#form)
   9 - [Create a plugin](#create)
  10 - [Rebuild the cache](#rebuild)
  11
  12 ---
  13
  14 ## Pre-requisite {#prerequisite}
  15
  16 Due to the nature of how Drupal alter hooks work, there is no "catch all" alter
  17 hook (like for forms with hook_form_alter). That means for you to use this
  18 plugin, it must be invoked from inside each and every alter hook that lives in
  19 `THEMENAME.theme`.
  20
  21 Luckily you don't have to worry about invoking the plugin directly. Instead,
  22 all you have to do is call the `Bootstrap::alter` helper method and pass the
  23 alter function name and parameters as arguments:
  24
  25 ```php
  26 use Drupal\bootstrap\Bootstrap;
  27
  28 /**
  29  * Implements hook_some_hook_alter().
  30  */
  31 function THEMENAME_some_hook_alter(&$data, &$context1 = NULL, &$context2 = NULL) {
  32   Bootstrap::alter(__FUNCTION__, $data, $context1, $context2);
  33 }
  34
  35 ```
  36
  37 ## Supported alter hooks {#supported}
  38
  39 This base theme implements several of the most commonly used alter hooks in
  40 themes and are automatically supported out-of-the-box.
  41
  42 Once a base theme has implemented an alter hook, like mentioned above, all
  43 subsequent sub-themes will have the ability to implement a plugin for that
  44 alter hook directly. All you have to do is simply create the plugin file in
  45 `./THEMENAME/src/Plugin/Alter`. No need to implement any code in
  46 `THEMENAME.theme`:
  47
  48 - `hook_bootstrap_colorize_text_alter`
  49 - `hook_bootstrap_iconize_text_alter`
  50 - `hook_element_info_alter`
  51 - `hook_js_settings_alter`
  52 - `hook_library_info_alter`
  53 - `hook_page_attachments_alter`
  54 - `hook_theme_registry_alter`
  55 - `hook_theme_suggestions_alter`
  56
  57 {.alert.alert-info}**Note:** if you do not see an alter hook here that you think
  58 _should_ be here, please
  59 [create an issue](https://www.drupal.org/node/add/project-issue/bootstrap)
  60
  61 ## Form alter hooks {#form}
  62
  63 You were probably thinking: "Hey, where's `hook_form_alter`? Didn't you _just_
  64 mention that above?"
  65
  66 As we all know, forms can be a tad more involved than just a simple "alter" and
  67 we figured that we'd give you a little more power behind what you can actually
  68 do with them. So if you're interested in those, please go see:
  69
  70 @link plugins_form @BootstrapForm @endlink
  71
  72 While, yes technically, `hook_form_system_theme_settings_alter` could also
  73 fall under the form plugin, we decided to take those a step further as well, see:
  74
  75
  76 @link plugins_setting @BootstrapSetting @endlink
  77
  78 ## Create a plugin {#create}
  79
  80 We'll use `PageAttachments` implemented by this base theme as an example of
  81 how to add a library from your sub-theme to every page request.
  82
  83 Replace all following instances of `THEMENAME` with the actual machine name of
  84 your sub-theme.
  85
  86 Create a file at `./THEMENAME/src/Plugin/Alter/PageAttachments.php` with the
  87 following contents:
  88
  89 ```php
  90 /**
  91  * @file
  92  * Contains \Drupal\THEMENAME\Plugin\Alter\PageAttachments.
  93  */
  94
  95 namespace Drupal\THEMENAME\Plugin\Alter;
  96
  97 use Drupal\bootstrap\Annotation\BootstrapAlter;
  98
  99 /**
 100  * Implements hook_page_attachments_alter().
 101  *
 102  * @ingroup plugins_alter
 103  *
 104  * @BootstrapAlter("page_attachments")
 105  */
 106 class PageAttachments extends \Drupal\bootstrap\Plugin\Alter\PageAttachments {
 107
 108   /**
 109    * {@inheritdoc}
 110    */
 111   public function alter(&$attachments, &$context1 = NULL, &$context2 = NULL) {
 112     // Call the parent method from the base theme, if applicable (which it is
 113     // in this case because Bootstrap actually implements this alter).
 114     parent::alter($attachments, $context1, $context2);
 115
 116     // Add your custom library.
 117     $attachments['#attached']['library'][] = 'THEMENAME/my_library';
 118   }
 119
 120 }
 121 ```
 122
 123 ## Rebuild the cache {#rebuild}
 124
 125 Once you have saved, you must rebuild your cache for this new plugin to be
 126 discovered. This must happen anytime you make a change to the actual file name
 127 or the information inside the `@BootstrapAlter` annotation.
 128
 129 To rebuild your cache, navigate to `admin/config/development/performance` and
 130 click the `Clear all caches` button. Or if you prefer, run `drush cr` from the
 131 command line.
 132
 133 Voilà! After this, you should have a fully functional `@BootstrapAlter` plugin!