file @BootstrapAlter

<!-- @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

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:

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

- `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](

## 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:

 * @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!