138 lines
4.2 KiB
Markdown
138 lines
4.2 KiB
Markdown
<!-- @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!
|