Drupal
min read
February 7, 2024

What is SDC (Single Directory Components) in Drupal 10?

What is SDC (Single Directory Components) in Drupal 10?
Table of contents

What is SDC (Single Directory Components) in Drupal 10?

SDC is a fresh way of theming in Drupal 10. It organizes all files needed to render a web component (like a button, carousel, menu) into a single directory. An SDC component’s directory includes YAML metadata, Twig templates, CSS stylesheets, and JavaScript scripts. Optionally, it can have a screenshot, PHP file, or media files related to the component.

What are we fixing and what benefits are we going to get?

As a frontend developer, navigating through a codebase can be a daunting task. Finding the right files, templates, and understanding variable changes in Twig files can sometimes feel like delving into a maze. Issues like deciphering how CSS and JS are loading, tracking down assets like files, Twig templates, and images can add to the complexity.

One of the challenges we often encounter is losing track of our location in the codebase. Jumping from one Twig template to another can be disorienting, and it's easy to get confused about where we were when writing a particular piece of code.

Understanding the data we're working with is crucial, and it can be a struggle to identify available variables in templates. Additionally, if modifications are needed, pinpointing the relevant variables for content changes becomes a puzzle. Locating the template itself poses another challenge – whether it resides in a module, the base theme, or buried deep within numerous directories.

To address these complexities, the Single Directory Components module in Drupal proves to be a valuable solution. It streamlines the organization of files, templates, and assets, offering a more intuitive and structured approach to frontend development. With this module, issues related to codebase navigation, variable identification, and template location become more manageable, providing a smoother and more efficient development experience.

Goals of SDC:

  • Creating components that are reusable UI elements. Like twig templates are reusable, you can import, embed or extend them. Just like that we have a goal of SDC, to have reusable components so that we can import them in other components,
  • Another goal is that we don’t replace everything or redo everything. We want to use components where they make sense which is largely with your site theme.  
  • The primary aim of Single Directory Components (SDC) is to facilitate the creation of reusable UI elements, much like Twig templates. Similar to the reusability of Twig templates through import, embed, or extend, SDC focuses on creating components that can be easily imported into other components.
  • Another key objective is to avoid unnecessary replacements or redundant efforts. SDC emphasizes the strategic use of components, particularly within the context of your site theme.

Our central goal is to streamline the front-end development process, enhancing the manageability of custom, Core, and contrib themes. Simply put, we aim to simplify the lives of Drupal front-end developers and make it more accessible for those new to Drupal.

To achieve this, we will:

  1. Simplify the steps involved in generating HTML, CSS, and JS for a Drupal page.
  1. Clearly define component APIs, providing a mechanism to replace a component supplied by a module or theme.

Advantages:

AdvantageDescription
Organizational EfficiencyGrouping all relevant code into a single directory simplifies the process of locating and navigating between files.
Automatic Library GenerationSDC streamlines library creation by automatically identifying and adding my-component.css and my-component.js files to a generated library. Additional assets and dependencies can be specified in the component’s YML file if needed.
Enhanced Re-usabilityDesigned with modularity in mind, components are easily reusable, allowing seamless integration across various pages or applications.
Consistent User ExperienceThrough the utilization of components, developers can maintain a consistent look and feel across web pages or applications, ensuring a unified user experience.
Scalability AdvantageComponents contribute to scalability by providing the flexibility to add or remove elements easily as the project evolves.
Effective TestingComponents often allow isolated testing, simplifying the identification and resolution of bugs or issues.
Facilitating CollaborationThe use of components fosters collaboration among development teams, enabling the sharing and reuse of components across diverse projects.

How to work with Single Directory Components in Drupal?

To develop SDC:

  • If you’re using Drupal 9 you have to install the module using this command composer require 'drupal/sdc:^1.0’.
  • For Drupal 10 and later core versions, the Single Directory Component (SDC) module is included in the core.
  • Enable the Single Directory Components module.
  • Disable CSS and JS aggregation in the Drupal admin UI for development purpose.
  • Enable Twig development mode and disable caching.

1. How to create a component:

  • Create a directory called components/ at the root of your theme or module’s directory.
  • Create a directory within the components/ directory with the name of your new component (e.g my-component).
  • In the component directory, create a Twig file and a YAML file (These files are required). Optionally, add CSS and JS files.
  • To load additional styles, scripts, and dependencies, use the libraryOverrides key in your YAML file.
loading additional styles code

A Single Directory Component is often referred to as a "component directory" due to its characteristic of consolidating all relevant information within a singular directory. This includes details about the component, its styling, structure, and the rendering process.

component details in SDC

For e.g. in the above screenshot we can see that there is directory which is a component called hero-banner. It has .css file which contains all the styling, hero-banner.component.yml file which contains the details of the hero-banner component and a twig template.

The most significant advantage of SDC is its ease of discovery and deletion since everything is located in a single directory. Additionally, the Twig file and rendering process are specifically designed to exclude Drupal’s preprocessing and hook systems, ensuring that these components remain unaffected by external impacts.

METADATA:

The presence of the .component.yml file is important; in its absence, Drupal remains uninformed about the existence of your component. It is imperative that this file be created within the component's directory.

Lets go through the definition of .component.yml file.

KEYDEFINITION
nameName of the component.
descriptionDetail explanation of the component.
schema propsAre the properties like mail, image, headline, etc.
schema slotsA container to put data that does not have a template or data structure.
libraryOverridesTo add extra js or css libraries apart from libraries which are inside component’s fdirectory.
metadata file

MORE ABOUT SCHEMA PROPS AND SCHEMA SLOTS:

Within the Drupal Single Directory Component (SDC) framework, data can be transmitted to a component using two methods: "props" (short for "properties") and "slots." These concepts originate from JavaScript frameworks like Vue and React, embodying the notion of providing or feeding data into a component.

  • Props adhere to a specified structure for transmitting data to the component, utilizing the JavaScript Object Notation (JSON) format with key-value pairs.

Example of Props:

example of props
  • Slots serve the purpose of handling unstructured data, encompassing scenarios like nested components, Twig blocks, or HTML markup. Unlike props, slots do not require a JSON schema with key-value pairs and are not confined by JSON data types.

Example of Slots:

example of slots

2. How to Render a Component:

To use a component in an *.html.twig template use Twig’s built in embed or include functions.

  • Use include():

Use the Twig include() function if there are no slots or arbitrary HTML properties and the

data all follows a defined structure.

Example of how to use the sdc_custom:hero-banner component in a Twig template:

how to use sdc_custom component

You’ll need to provide the component ID ([module/theme name]:[component]) of the

Component

  • Use {% embed %}:

Use a Twig {% embed %} tag if you need to populate slots.

Example of how to pass in a slot (Twig block) in a card component:

how to pass in a slot

The final result of a component after following the steps mentioned above will look like:

component example

3. How to Override a Component:

Only themes can override components, and there are two important requirements to do so:

  1. Add a replaces key at the top in the .component.yml file you want to override

        2. The component needs to have a defined schema.

It is important to note that modules cannot override components, and only components that have a defined schema can replace and be replaced by others.


Drupal 10's Single Directory Component is like a superhero that organizes your website's code, making it simpler to manage and understand. While there might be a bit of work involved in adopting SDC, the benefits of a tidy and well-organized codebase make it a valuable tool for Drupal developers.

NOTE:

  1. If you want a quick intro to the SDC BLOCK module & its implementation, click here.
  2. If you want to Implement the SDC Component with the Paragraphs module refer to this link.

REFERENCES:

Written by
Artwork by
No art workers.
We'd love to talk about your business objectives