The Guide to Single Directory Components (SDC) in Drupal 10
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:
- Simplify the steps involved in generating HTML, CSS, and JS for a Drupal page.
- Clearly define component APIs, providing a mechanism to replace a component supplied by a module or theme.
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:¹.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.
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.
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.
KEYDEFINITIONnameName 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.
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:
- 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:
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:
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:
The final result of a component after following the steps mentioned above will look like:
3. How to Override a Component:
Only themes can override components, and there are two important requirements to do so:
- 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:
- If you want a quick intro to the SDC BLOCK module & its implementation, click here.
- If you want to Implement the SDC Component with the Paragraphs module refer to this link.
REFERENCES:
Written by
Libbna Mathew — Full Stack Engineer
Deepanshu Varshney — Frontend Engineer
This post was originally published on qed42.com
