sub-topic @BootstrapAlter


Pre-requisite

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:

use Drupal\bootstrap\Bootstrap;

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

Supported alter hooks

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 ./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

Note: if you do not see an alter hook here that you think should be here, please create an issue

Form alter hooks

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:

@BootstrapForm

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:

@BootstrapSetting

Create a plugin

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 ./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\Annotation\BootstrapAlter;

/**
 * Implements hook_page_attachments_alter().
 *
 * @ingroup plugins_alter
 *
 * @BootstrapAlter("page_attachments")
 */
class PageAttachments extends \Drupal\bootstrap\Plugin\Alter\PageAttachments {

  /**
   * {@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

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!

Parent topics

Source docs/plugins/Alter.md (line 4)

Functions

Namesort descending Description
hook_bootstrap_colorize_text_alter Allows sub-themes to alter the array used for colorizing text.
hook_bootstrap_iconize_text_alter Allows sub-themes to alter the array used for associating an icon with text.

Classes

Namesort descending Description
AlterManager Manages discovery and instantiation of Bootstrap hook alters.
BootstrapAlter Defines a BootstrapAlter annotation object.
ElementInfo Implements hook_element_info_alter().
LibraryInfo Implements hook_library_info_alter().
PageAttachments Implements hook_page_attachments_alter().
ThemeRegistry Extends the theme registry to override and use protected functions.
ThemeSuggestions Implements hook_theme_suggestions_alter().

Interfaces

Namesort descending Description
AlterInterface Defines the interface for an object oriented alter.