hook_civicrm_alterBundle

Summary

Specify the content of a resource bundle (JS/CSS/etc)

Description

A bundle is a collection of closely related resources (JS, CSS, settings, etc). Application-pages may load a bundle by calling addBundle($name), e.g.

Civi::resources()->addBundle(`bootstrap3`)

Use hook_civicrm_alterBundle to add, modify, or replace resources in a bundle.

Availability

This hook is available in CiviCRM 5.31 and later.

Third-party bundles may need to fire hook explicitly.

In 5.31, this hook fires via CRM_Core_Resources_Common -- so the hook is well-defined for all common/standard bundles.

If a third-party extension defines a new bundle (without using CRM_Core_Resources_Common), then it may need to explicitly fire the hook via CRM_Utils_Hook::alterBundle(...).

Definition

function hook_civicrm_alterBundle($bundle)

Parameters

• $bundle - \CRM_Core_Resources_Bundle

Example: Provide bootstrap3

By default, the bootstrap3 bundle is empty. It is the responsibility of a theme/extension to provide concrete files (CSS/JS) with actual styling.

For example, the core-extension greenwich defines a theme (look-and-feel). If the user has chosen this look-and-feel, and if the application-page uses bootstrap3, then we should load the CSS/JS provided by greenwich:

function greenwich_civicrm_alterBundle(CRM_Core_Resources_Bundle $bundle) {
  $theme = Civi::service('themes')->getActiveThemeKey();
  switch ($theme . ':' . $bundle->name) {
    case 'greenwich:bootstrap3':
      $bundle->clear();
      $bundle->addStyleFile('greenwich', 'dist/bootstrap3.css');
      $bundle->addScriptFile('greenwich', 'extern/bootstrap3/assets/javascripts/bootstrap.min.js', [
        'translate' => FALSE,
      ]);
      break;
  }
}

Example: Manipulate coreResources

function myextension_civicrm_alterBundle(CRM_Core_Resources_Bundle $bundle) {
  if ($bundle->name !== 'coreResources') {
    return;
  }

  // Prevent navigation.css from loading
  $bundle->filter(function($r) {
    return !preg_match(';css/navigation.css;', $r['name'])
  });

  // Add some css of our own to the page.
  $bundle->addStyleFile('org.example.myextension', 'css/my_style.css');

  // Add a setting - in this example we override the CKEditor config file location
  $myCKEConfFile = Civi::resources()->getUrl('org.example.myextension', 'js/my-ckeditor-config.js');
  $bundle->addSetting(['config' => ['CKEditorCustomConfig' => ['default' => $myCKEConfFile]]]);
}

List of standard bundles

For a list of common/standard bundles, see Bundle Reference.