Hoe we in Drupal met herbruikbare componenten werken (SDC)

Herbruikbare componenten zijn de bouwstenen van een consistente website. Bijvoorbeeld hetzelfde kaartje op de homepage, in een overzicht en in een gerelateerde content blok, zonder dat je drie keer hetzelfde bouwt. Minder onderhoud, minder inconsistentie met als doel sneller nieuwe pagina's opzetten.

In een klassiek Drupal-theme liggen de bestanden van zo'n component vaak verspreid. De Twig-template in templates/, de CSS in css/, de JS in js/. En dan knoop je het nog handmatig aan elkaar in libraries.yml. Dat werkt. Tot je een card wilt aanpassen en je drie mappen verderop moet zoeken.

Single Directory Components (SDC) draait dat om: alles van hetzelfde component in één map. In dit artikel leg ik uit hoe dat werkt en hoe we het bij Immer inzetten in onze Drupal-themes.

Welk probleem lost het op?

Klassiek Drupal-theming ziet er vaak zo uit: de template voor een article teaser staat in templates/content/, de styling in css/components/, het script in js/ en de koppeling tussen die bestanden in my_theme.libraries.yml. Functioneel klopt dat. Maar de logische eenheid "de card" bestaat nergens als één geheel.

Gevolg: je moet weten waar alles ligt voordat je iets kunt aanpassen. Onderhoud kost meer tijd en de kans op inconsistentie tussen pagina's groeit mee. Als je een component wilt hergebruiken in een ander theme of een module, sleep je losse bestanden mee en hoop je dat je niets vergeet.

SDC lost dat op door per component één map te maken met alles erin.

Wat is SDC?

SDC staat voor Single Directory Components. De naam zegt het al: één directory per component, met alle bestanden die daarbij horen. 

Je plaatst die components/-map in je theme (of module). Drupal herkent de componenten automatisch. Geen aparte library-definitie meer nodig om CSS en JS te laden. Dat gebeurt op het moment dat je het component gebruikt.

Wat levert het op in de praktijk?

• Consistente UI: dezelfde card, button of alert overal op de site hetzelfde

• Sneller aanpassen: alles van één component op één plek, geen speurtocht door mappen

• Herbruikbaar: in je theme én in modules, zonder bestanden te kopiëren

Wat zit er in een component?

Elk SDC heeft minimaal twee bestanden:

• card.component.yml: beschrijft het component en zijn inputs (properties en slots)

• card.twig: bevat de markup

Daarnaast kun je optioneel card.css en card.js toevoegen. Die worden automatisch ingeladen op plekken waar het component gebruikt wordt. Je hoeft ze niet meer handmatig te registreren in libraries.yml.

Extra bestanden (documentatie, preview-afbeeldingen, tests) mogen ook in dezelfde map. Alles wat bij het component hoort, hoort daar.

card.component.yml

Het YAML-bestand is het "contract" van je component. Hier definieer je welke properties gebruikt kunnen worden.

Belangrijkste onderdelen:

• $schema: link naar Drupal's schema voor component.yml. Handig: je editor kan hier suggesties op geven.

• status (optioneel): experimental, stable, deprecated of obsolete.

• props: gestructureerde data met een type. Bijvoorbeeld title (string) en variant (enum: default of featured).

• slots: vaste plekken voor dynamische inhoud. Bijvoorbeeld card_top, card_content en card_bottom.

Je hoeft het hele bestand niet uit je hoofd te kennen. Begin met $schema, name, props en slots. De rest komt vanzelf.

Props vs slots

Dit is het verschil dat je het vaakst nodig hebt.

Props zijn gestructureerde data met een vast type. Denk aan een titel (string) of een variant (default / featured). Props worden gevalideerd via JSON Schema. Je weet vooraf wat erin mag.

Slots zijn plekken voor dynamische inhoud waarvan de structuur vooraf onbekend is. Het component bepaalt waar de slots staan (card_top, card_content, card_bottom). De gebruiker van het component bepaalt wat erin komt: een afbeelding, tekst, een knop, een render array of een ander component.

Zo blijft de structuur van je card consistent, terwijl de inhoud per gebruik kan verschillen. Voor redacteuren betekent dat: vaste opbouw, flexibele invulling, zonder dat iemand in de markup hoeft te duiken.

Elk component heeft een ID

Om een component aan te roepen heb je een ID nodig. Drupal combineert de provider (theme of module) met de componentnaam:

Voorbeelden:

• my_theme:card: component card uit theme my_theme

• my_module:alert: component alert uit module my_module

Met die ID roep je het component aan in Twig of PHP.

UI Patterns 2: dezelfde componenten in Drupal-beheer

SDC is developer-first. Maar met de module UI Patterns 2 maak je dezelfde componenten bruikbaar voor redacteuren en site builders, zonder extra markup te schrijven.

Developers bouwen het component één keer. Redacteuren gebruiken het daarna in Block layout, Layout Builder, field formatters en Views. Geen losse block-templates of dubbele markup. Het is hetzelfde component, alleen via het beheer in plaats van in code.

Via submodules worden je SDC's beschikbaar als:

• Blocks → Block layout

• Layouts → Layout Builder

• Field formatters → Manage display

• View styles/rows → Views

Gebruiken in Twig: include()

De snelste manier om een SDC te gebruiken is met include().

Wat je meegeeft:

• ID: my_theme:card

• Props: title en variant

• Slots: card_top, card_content, card_bottom

• with_context = false: geef geen verborgen parent-variabelen mee. Alleen wat je expliciet doorgeeft telt. Dit zorgt voor een betere performance.

Die laatste regel is belangrijk. Zonder with_context = false stuurt de hele Twig-context mee naar je component. Dan weet je niet meer precies waar je data vandaan komt.

Gebruiken in Twig: embed

Soms wil je in een slot zelf markup bouwen: extra wrappers, nested components, conditionele logica. Dan gebruik je {% embed %}

Het only-keyword doet hetzelfde als with_context = false: alleen de variabelen die je expliciet meegeeft zijn beschikbaar in de blocks.

Wanneer wat? include() als de inhoud al klaar is. embed als je in de slots nog markup of nested components wilt toevoegen.

Gebruiken in PHP

Je hoeft SDC niet alleen in Twig te gebruiken. In PHP bouw je een render array met #type => 'component', #component, #props en #slots:

Zelfde component, andere plek. Handig in custom blocks, controllers of preprocess-functies.

Tot slot

Met SDC staat alles van een component op één plek. Dat maakt je theme makkelijker te onderhouden en je UI consistenter.

Vragen over Drupal-theming? We denken graag mee.