Skip to main content

BUX with Drupal

Tips for using BUX in a Drupal 9 theme.

These tips work best when building your Drupal theme from scratch using Drupal's stable as your base theme.

Initial setup#

1. Add the composer package to your theme as a dev dependency#

Add the following item to the "repositories" section of your project's composer.json file.

"code.osu.edu/6209": {
  "type": "composer",
  "url": "https://code.osu.edu/api/v4/group/6209/-/packages/composer/packages.json"
}

Require the Composer Installers Extender package.

composer require oomphinc/composer-installers-extender

Add the following to the "extra" section of your project's composer.json file.

"installer-types": [
  "design-system"
],
"installer-paths": {
  "design-system/{$name}": [
    "type:design-system"
  ]
}

Then require the package from your terminal at the root of the project.

composer require --dev osu/bux-composer

NOTE: It is important that BUX is a dev dependency. We will be compiling it in with your other theme files.

2. Install Drupal contrib modules#

3. Incorporate the bux-js library#

Within your themename.libraries.yml, file define the bux-js library.

bux-js:
  js:
    design-system/bux-composer/dist/js/bux.js: {}

4. Make your theme aware of the bux-composer directory#

a. Edit your theme's .info file#

Add the following code to the themename.info.yml file. The Components! module uses this info to assign the @bux namespace to the twig files in the bux-composer package.

component-libraries:
  bux:
    paths:
      - design-system/bux-composer/dist/twig

b. Edit your theme's .theme file#

Create a preprocess function in themename.theme to define the base_path and bux variables.

  $variables['base_path'] = base_path();
  $variables['bux'] = '/design-system/bux-composer/dist/';

5. Incorporate BUX Sass#

See How to use in conjunction with site-specific Sass and Settings File.

6. Use a task runner to compile your Sass files into a single css stylesheet#

Utilizing BUX Components#

You can either choose to directly reference BUX's Twig files or recreate them within Drupal's Twig Templates.

Referencing BUX Twig templates#

The Components! module was designed to be able to reference Twig files from outside of your theme's templates directory. In our case we are referencing from elsewhere in the theme.

The Breadcrumb component is a good example of a simple application of this approach. Because BUX's Breadcrumb variables match exactly with Drupal's, all we need to do is include BUX's breadcumb.twig within Drupal's breadcrumb.html.twig like this:

{% include "@bux/breadcrumb.twig" %}

However, in most cases the variable names in BUX components will not match up directly with Drupal variable names. They will need to be preprocessed on the Drupal end to match what is in BUX.

If a certain variable is going to be used in mutilple places such as a site name, you would probably want to use a preprocess function within your themename.theme file. But for variables with a limited scope it would be best to handle it directly in the particular Drupal Twig template. This can be done one of two ways.

It can be passed into the component as it's being included like this:

{% include '@bux/card.twig' with {
  card_heading: label,
  card_body: content.field_wcm_block_card_body,
} %}

Or preprocessed within the Twig file before the include statement like this:

{% set card_heading = label %}
{% set card_body = content.field_wcm_block_card_body %}

{% include '@bux/card.twig' %}

The second method is nice when you have more complex values and want to keep a tidy template file when working with views or are looking to grab certain attributes of a field.

Building your own Twig templates#

Sometimes the platform-agnostic BUX Twig templates may not line up with how Drupal does things. If this goes beyond simple variable preprocessing, it is often easier to build the template from scratch by using Drupal's default template and customizing to use BUX markup and classes.

We will provide code examples for the most common use cases on the corresponding component documentation pages.