<!-- @file Documentation for the @BootstrapAlter annotated plugin. -->
<!-- @defgroup -->
<!-- @ingroup -->
# @BootstrapAlter

- [Pre-requisite](#prerequisite)
- [Supported alter hooks](#supported)
- [Form alter hooks](#form)
- [Create a plugin](#create)
- [Rebuild the cache](#rebuild)

---

## Pre-requisite {#prerequisite}

Due to the nature of how Drupal alter hooks work, there is no "catch all" alter
hook (like for forms with hook_form_alter). That means for you to use this
plugin, it must be invoked from inside each and every alter hook that lives in
`THEMENAME.theme`.

Luckily you don't have to worry about invoking the plugin directly. Instead,
all you have to do is call the `Bootstrap::alter` helper method and pass the
alter function name and parameters as arguments:

```php
<?php
use Drupal\bootstrap\Bootstrap;

/**
 * Implements hook_HOOK_alter().
 */
function hook_some_hook_alter(&$data, &$context1 = NULL, &$context2 = NULL) {
  Bootstrap::alter(__FUNCTION__, $data, $context1, $context2);
}

?>
```

## Supported alter hooks {#supported}

This base theme implements several of the most commonly used alter hooks in
themes and are automatically supported out-of-the-box.

Once a base theme has implemented an alter hook, like mentioned above, all
subsequent sub-themes will have the ability to implement a plugin for that
alter hook directly. All you have to do is simply create the plugin file in
`./themes/THEMENAME/src/Plugin/Alter`. No need to implement any code in
`THEMENAME.theme`:

- `hook_bootstrap_colorize_text_alter`
- `hook_bootstrap_iconize_text_alter`
- `hook_element_info_alter`
- `hook_js_settings_alter`
- `hook_library_info_alter`
- `hook_page_attachments_alter`
- `hook_theme_registry_alter`
- `hook_theme_suggestions_alter`

{.alert.alert-info}**Note:** if you do not see an alter hook here that you think
_should_ be here, please
[create an issue](https://www.drupal.org/node/add/project-issue/bootstrap)

## Form alter hooks {#form}

You were probably thinking: "Hey, where's `hook_form_alter`? Didn't you _just_
mention that above?"

As we all know, forms can be a tad more involved than just a simple "alter" and
we figured that we'd give you a little more power behind what you can actually
do with them. So if you're interested in those, please go see:

@link plugins_form @BootstrapForm @endlink

While, yes technically, `hook_form_system_theme_settings_alter` could also fall
under the form plugin, we decided to take those a step further as well, see:


@link plugins_setting @BootstrapSetting @endlink

## Create a plugin {#create}

We'll use `PageAttachments` implemented by this base theme as an example of
how to add a library from your sub-theme to every page request.

Replace all following instances of `THEMENAME` with the actual machine name of
your sub-theme.

Create a file at `./themes/THEMENAME/src/Plugin/Alter/PageAttachments.php` with the
following contents:

```php
<?php
/**
 * @file
 * Contains \Drupal\THEMENAME\Plugin\Alter\PageAttachments.
 */

namespace Drupal\THEMENAME\Plugin\Alter;

use Drupal\bootstrap\Plugin\Alter\PageAttachments as BootstrapPageAttachements;

/**
 * Implements hook_page_attachments_alter().
 *
 * @ingroup plugins_alter
 *
 * @BootstrapAlter("page_attachments")
 */
class PageAttachments extends BootstrapPageAttachements {

  /**
   * {@inheritdoc}
   */
  public function alter(&$attachments, &$context1 = NULL, &$context2 = NULL) {
    // Call the parent method from the base theme, if applicable (which it is
    // in this case because Bootstrap actually implements this alter).
    parent::alter($attachments, $context1, $context2);

    // Add your custom library.
    $attachments['#attached']['library'][] = 'THEMENAME/my_library';
  }

}
?>
```

## Rebuild the cache {#rebuild}

Once you have saved, you must rebuild your cache for this new plugin to be
discovered. This must happen anytime you make a change to the actual file name
or the information inside the `@BootstrapAlter` annotation.

To rebuild your cache, navigate to `admin/config/development/performance` and
click the `Clear all caches` button. Or if you prefer, run `drush cr` from the
command line.

Voilà! After this, you should have a fully functional `@BootstrapAlter` plugin!