Single Directory Components

This chapter explores new additions to Drupal core. The experimental Single Directory Component (SDC) module improves the Drupal theming experience. It’s a new topic, but worth a chapter. You’ll have another valuable tool at your disposal.

The following topics will be covered in this chapter:

• The new kid on the block
• Creating a component with SDC
• Overriding CSS and JavaScript
• Overriding a component
• Component metadata
• Integration with Storybook

Technical requirements

To run the examples in this chapter, make sure to follow the instructions provided in Chapter 1, Setting Up a Local Environment.

You can find the code for this chapter in the GitHub repository: https://github.com/PacktPublishing/Modernizing-Drupal-10-Theme-Development.

The new kid on the block

As we saw in Chapter 4, Mapping the Design to Drupal Components, there are a lot of contributed modules to build and manage a Drupal theme using components. All those solutions use the same theme APIs and structures from Drupal, so, in the end, if you know how Drupal builds its pages, you know how to use any component implementation.

In this book, we’ve purposely avoided using any specific one to stay as agnostic as possible; we’ve concentrated on how Drupal works more than how a specific components library implementation works.

However, things have changed with the release of Drupal 10.1 in June 2023. A specific implementation was elected for inclusion in Drupal core. Initially developed as a contributed module named Component Libraries: Components (https://www.drupal.org/project/cl_components), this functionality has been merged into Drupal core as the new SDC experimental module.

SDC is attracting attention from the community, and...

How to create a component with SDC

SDC is a directory with some files inside. You can create everything you need by hand or leverage a Drush command provided by the Component Libraries: Generator (cl_generator, https://www.drupal.org/project/cl_generator) contributed module.

Note

At the time of writing, there are two versions of the cl_generator module – be sure to install version 2, which is compatible with SDC from Drupal core. There are also plans to move the generator directly inside Drush; look at the project page at drupal.org to check for the latest on this.

Open a terminal and type the following command to start the generation wizard:

ddev drush generate theme:sdc:component

Work through the questions and provide answers to generate a component with these values:

• Location: theme
• Machine name of the theme: alps_trips
• Components directory: components (the default, and with SDC, the only valid value)
• Component machine name: at-button
...

Overriding CSS and JavaScript

Sometimes, you may need more than one CSS or JavaScript file for a single component. Maybe you need to load some external asset. Or maybe you need to name your asset with a different name, or place it in a subfolder of the component (perhaps because you have a build script that converts SCSS to CSS, for example).

Luckily, SDC supports all those use cases.

The libraryOverrides key in the .component.yml file that we’ve used to attach dependencies can also be used to override the automatically generated library:

libraryOverrides:
  dependencies:
    - core/drupal.dialog
  css:
    component:
      another-stylesheet.css: {}
      https://drupal.org/fake-dependency/styles.css: {}
  js:
    another-javascript.js: {}
    https://drupal.org/fake-dependency/index.min.js: {}

...

Overriding a component

A theme can be used to override components provided by other themes or modules.

Suppose that we have defined a component in the alps_weather module, inside a folder named web/modules/custom/alps_weather/components/at-weather. The at-weather.component.yml file looks like the following:

'$schema': 'https://git.drupalcode.org/project/drupal/-/raw/10.1.x/core/modules/sdc/src/metadata.schema.json'
name: "Alps Trips Weather"
status: "stable"
description: "A weather component"
props:
  type: object
  properties:
    city:
      type: string
      title: City
      description: The city for the weather
  required:
    - city

And the Twig file (at-weather.twig) looks as follows:

<div>Weather for {{ city }}</div>

We can include this component...

Component metadata

Assets in a component can be more than CSS and JavaScript files; you may have icons or images too.

To print them in a component’s Twig file, you must know the path where the component folder is. SDC automatically injects into every component the componentMetadata variable, which contains some information about the component itself:

Figure 11.4 – The output of dumping the componentMetadata variable

If you have an assets folder in your component with an icon.png file in it, you can print the icon using code like the following:

<img src="/{{ componentMetadata.path }}/assets/icon.png" />

Now that we have our set of components, we can expose them to Storybook.

Integration with Storybook

Up to now, we have defined our components in Storybook and then incorporated them into Drupal; this involved using Twig.js and some extra work to ensure compatibility with Drupal’s JavaScript behaviors.

This approach has some pros and cons:

Pros

• Build the component library in a (nearly) Drupal-independent way (you can start working on components without having a Drupal website)
• Quickly move the component library to a new project
• Simplify the building of complete pages on Storybook, starting from defined components

Cons

• Twig.js differs from Twig, which may lead to some inconsistencies in components when viewed in Storybook versus Drupal
• Storybook ignores the entire render pipeline of Drupal, which can also lead to inconsistencies
• If a component uses some JavaScript from Drupal, you need to provide a way to include this in Storybook

SDC took the opposite approach: components are instead defined inside...

Conclusions

To stay up to date with the latest concepts and techniques, I recommend monitoring the official documentation page at https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components.

Please remember that the topic we discussed in this chapter is relatively new, so some of the tutorials and documentation you may find online could be outdated as things change quickly. The SDC module, which has been added to Drupal core, is based on the initial work done in the Component Libraries: Components contributed module (https://www.drupal.org/project/cl_components), but the code and features may not be exactly the same, particularly in the version added in Drupal 10.1 (for example, component versions are not available in SDC). Also, remember that the SDC module is experimental, meaning some implementations may change without support for backward compatibility.

The component implementation provided by SDC in Drupal core lays the foundation for a more consistent...

Summary

In this chapter, we’ve explored one of the most exciting new features of Drupal 10, Single Directory Component.

First, you’ve learned how a component is and how to generate one using Drush. Then we’ve seen how to provide custom CSS, JavaScript, and Twig code.

Next, you’ve learned how to include or embed a component into one of the templates provided by Drupal. We’ve discussed props and slots, what they are, and how to use them to define placeholders.

We’ve talked about how to override a component provided by a module or theme.

Finally, we’ve briefly mentioned how to integrate Single Directory Component provided by Drupal Core with Storybook.