Clarify SDC documentation by toning down Twig blocks promotion

Also, le'ts remove this misleading section: Does SDC handle contextual links, attributes, title suffix, etc? →

Using a PHP Namespace as a prop type is not JSON schema valid and trigger a weird behaviour, so it must be avoided.

An empty array or an empty object is JSON Schema valid, but a bad practice. Let's not promote it.

Other idea for documentation update: help people to differentiate props and slots in presenter templates:

In node.html.twig:

• node variable has the data to send to props
• content has the data to send to slots

In user.html.twig:

1. user variable has the data to send to props
2. content has the data to send to slots

...

I'm very much in favor of these updates! Your help on Drupal Slack a while back related to using node/user/paragraph rather than content for props was super helpful but that isn't anywhere in the docs IIRC.

Would you also say that doing this:

attributes:
      type: Drupal\Core\Template\Attribute
      title: 'Attributes'
      description: 'HTML attributes to apply to the component.'

in the component.yml is incorrect? Because I see that being done in Umami components, and in Experience Builder components. In my own components, I am noticing some bleeding in from the parent template when then doing adding the attributes prop and doing something like:

<msu-header{{ attributes }}>....</msu-header>

Where if I include that component in my region--header.html.twig, it inherits the attributes from the parent div. If I try to use the 'only' keyword, like this:

{% embed 'msuext:msu-header' only %}
... content here ...
{% endembed %}

then I cannot include slots/blocks that aren't explicitly included in the Twig template.

Hi @dalemoore,

Would you also say that doing this:

attributes:
      type: Drupal\Core\Template\Attribute
      title: 'Attributes'
      description: 'HTML attributes to apply to the component.'

in the component.yml is incorrect?

It is not incorrect in a SDC POV but:

• useless because the attributes variable is automatically injected to the component anyway, so no need to add it to the component definition
• ugly because using PHP namespaces (like Drupal\Core\Template\Attribute) as types is not compliant with JSON Schema and SDC has implemented a quirk to mange them. So let's avoid this

If I try to use the 'only' keyword, like this then I cannot include slots/blocks that aren't explicitly included in the Twig template as blocks.

I ddin't know this about embed, that's one more reason to promote Twig include() function (function, not tag !) (with with_context = false !) instead of the messy embed tag.

If the attributes prop isn't right, then I would ask: how do we add a class, ID, or other attribute to our components from presenter templates? Having to manually add a class prop (or other attribute) onto every SDC seem to be the only way, but and is burdensome.

I would not recommend adding a class prop. attributes props is perfect for this and it is not what is causing issue here. attributes also allows to attach other attributes, and is expected by any mechanism adding semantic annotation, SEO tags, styles utilities from design systems, accessibility attributes... It is very valuable.

If including an attributes prop, I wonder if it would be better to name it component_attributes instead of just attributes to prevent the leaking of attributes from the presenter template. We already have title_attributes, content_attributes, etc. for other things.

Radix theme did this mistake: 🐛 Inconsistent `attributes` handling Active Now the have have both COMPONENT_attributes and attributes in some templates, which is confusing and may lead to other issues.

Using the standard attributes prop must be enough and work well.

Excellent, thank you @pdureau! I know you have extensive experience working on components, SDC, and design systems. Thanks for sharing your insights on here, hopefully we can get these into the docs so others like me won't be confused and we can move towards some best practices.

I'll remove the attributes prop from my components. Also, do you have examples of how you're using SDCs? I downloaded UI Patterns, but there are no SDCs in there as examples. Or if you can direct me toward how you mean with using include rather than embed? I don't get how I can do slots with include and again, the docs only say use embed with slots.

I downloaded UI Patterns, but there are no SDCs in there as examples

We don't ship SDC component in UI Patterns 2 by design. UI Patterns 2 is only a "bridge" between SDC and other Drupal API.

However, we are currently adding an extensive documentation to UI Patterns 2, expected before Christmas, and I hope it will give you the information you need.

Also, do you have examples of how you're using SDCs?

UI Suite team (the team doing UI Patterns, which I am part of) are also maintaining SDC themes:

• https://git.drupalcode.org/project/ui_suite_bootstrap/-/tree/5.1.x/compo...
• https://git.drupalcode.org/project/ui_suite_daisyui/-/tree/4.0.x/components
• https://git.drupalcode.org/project/ui_suite_dsfr/-/tree/1.1.x/components
• ...

Beware, there are 2 additions from UI Patterns 2 in those components compared to regular SDC components:

• ✨ Introduce component variants to SDC Active has been already implemented
• we use the native JSON schema's $def/$ref mechanism to avoid repeating complex prop schemas

Beside that, you can get inspiration from them.

Also, the tool we are using to check our SDC good practices, https://www.drupal.org/project/sdc_devel → , is already usable, but the rules set needs some tweaking (wording, scope, levels...) which will happen around Christmas.

I don't get how I can do slots with include and again, the docs only say use embed with slots.

That's why the doc needs to be updated. The issue description has some examples of using include with slots.

Thanks @pdureau! Very helpful info. Hopefully we can get some more eyes on this issue to get some more feedback from others who have been/are interested in starting to use SDCs.

While continuing my quest to slowly implement SDCs, I think it would also be beneficial in the docs to include actual real-world examples of using SDCs as @pdureau has done above. On Using your new single-directory component → , all but one ( the embed example → ) use hard-coded values in the props and slots. I think most of us are going to be wanting examples of how to get data from fields into those, and folks that are more frontend (🙋🏻‍♂️) are going to be struggling to figure out how to do that. Nowhere on the page does it mention how to do that (the only ways I know of are to install Devel/Kint, and just recently learned of Xdebug and have been trying to get it working in VScode).

So far, the only ways I know of to get data out of Drupal and into these SDCs are:

• code the variable in an .html.twig file (e.g., content['#block_content'].field_name.0.value in a block.html.twig to get a prop value w/o the render bits)
• some kind of render array magic, I guess through preprocess functions in your .theme? How else would you use this method → ?
• utilize a contrib module that handles displaying the SDCS, such as SDC Display → , UI Patterns → , and the upcoming Experience Builder →

Are there other ways I'm not aware of? If so, they should be documented. If someone can help me answer these questions, I will try my first time at editing docs on here over the Christmas break. :)

some kind of render array magic, I guess through preprocess functions in your .theme? How else would you use this method?

Most of the time, as the return value of configurable plugins related to display building:

• BlockPluginInterface::build()
• FormatterInterface::viewElements()
• LayoutInterface::build()
• StylePluginBase::render()
• ...

Do we add this information to the SDc documentation too?

@pdureau Yes I think that would be helpful to indicate for newcomers or non-backend folks how they meant to use for Using your component through a render array → , if that isn't meant to be done in a theme. AFAIK everything that was supposed to go with an SDC is supposed to go in the theme in the same folder as the component, or at least done in the theme. But I don't think it's best practice to do any of that in a theme?

Step by step, we are gathering information to update this doc. That's nice

AFAIK everything that was supposed to go with an SDC is supposed to go in the theme in the same folder as the component, or at least done in the theme. But I don't think it's best practice to do any of that in a theme?

The component are stored in a theme (or a module), but can be used outside of this theme (or module). Most of the time, component usage is stored in config entities related to display (block.block, entity view displays, views...). Sometimes in content (fields using ckeditor5 data or layout builder data...). Sometimes in code (custom plugins...)

+1 to this. I also fell on the misleading slots===blocks (or "blocks is the recommended and only implementation for slots") comparison, and other colleagues as well.

It will be much useful to emphasize that you can implement slots by using includes and embeds, and the tradeoffs and benefits of each approach.

We may do a documentation session with @mherchel during DrupalCon Atlanta

I am very excited about that. There are many sides of SDC documentation which need to be clarified or completed after 2 years of practice.

Data primitives mapping between the 3 formats we are manipulating:

Maybe adding such a table will be useful in the SDC documentation.

Suggestion from @mlncn about replaces property:

looking to improve the documentation slightly, the general advice should be to copy the entire component subdirectory into your themes components directory and add the replaces line. It's not like it can inherit anything it's a true replacement, yes?

Indeed, the replacement component is still a full component with its Twig template and its YAML definition.

@pdureau, please go ahead with updating the documentation per specified in the issue summary, we can always refine later

updating credits

From Enrique Lacoma:

Overriding components in a module, in the doc https://www.drupal.org/docs/develop/theming-drupal/using-single-director... → says you can't override a component in a module, but I was able to do it, is the documentation correct or doing the override inside a module can create any issue? thanks

So we are good. I am currently editing the documentation.

Update Quickstart →

Add an example without block and with include() as the primary example.

Waiting 📌 Review and improve SDC documentation Active to be done to not override their current work.

Keep the example with block and embed, but add the print node:

{% block chip_content %}
  {{ chip_content }}
{% endblock %}

Waiting 📌 Review and improve SDC documentation Active to be done to not override their current work.

Update Using your new single-directory component →

Keep the mentions of block and embed but move it to the page bottom and update any parts which can make readers believing that "slots == Twig blocks".

DONE. IN REVIEW.

Also, don't promote the use of include tag at the same level of include function:

DONE. IN REVIEW.

Render element is already explained in this page, but it can be promoted a bit.

DONE. IN REVIEW.

It is a good opportunity to explain the difference between presenter templates:

• unavoidable because of the lack of display building: breadcrumbs.html.twig, status-message.html.twig, menu.html.twig, pager.html.twig..
• the ones conflicting with the display building: node.html.twig, field.html.twig, views.html.twig, block.html.twig...

NOT DONE YET

Also, "Component data validation" section can be moved in "Creating a single-directory component" page.

DONE. IN REVIEW.

Update Creating a single-directory component →

The replacement component is still a full component with its Twig template and its YAML definition.

TODO

Data primitives mapping between the 3 formats we are manipulating:

TODO

Tell something about custom & contrib Twig extensions.

TOOD

Update What are Props and Slots in Drupal SDC Theming? →

Remove any mention of block and embed. The goal of this page is to teach about slots and props, not to list all ways of calling components from templates.

TODO

A bit of rewording and an annotated component screenshot like this can also help the reader:

TODO

Update API for Single-Directory Components →

Replace the example with block and embed by one with include. Or simply remove the example.

TODO

Also, a schema can be a good way to show how the different parts of the API are interacting.

TODO

Update Frequently Asked Questions →

says you can't override a component in a module, but I was able to do it,

TODO

pdureau → credited enriquelacoma → .

pdureau → credited mlncn → .

Wow - this is all super-helpful. Huge kudos to @pdureau for taking this on.

As someone new to SDC, this discussion has been especially helpful in filling in some knowledge gaps for me.

-mike

Per @pdureau at #3493070-8: Enum values do not have translatable labels → , this will also document meta:enum to provide human-readable labels that also are translatable.

For example:

    "string_pattern": {
      "type": "string",
      "description": "A string following a regular expression",
      "pattern": "^ba.$",
      "examples": ["bar", "baz", "bat"],
      "meta:enum": {
        "baa": "the sounds of sheeps",
        "bad": "German bathroom",
        "bag": "holding device",
        "bah": "humbug!",
        "bam": "a loud sound",
        "ban": "don't do this",
        "bap": "a British soft bread roll",
        "bas": "from ancient Egyptian religion, an aspect of the soul",
        "bat": "…out of hell",
        "bay": ", sitting by the dock of the"
      },

— https://github.com/adobe/jsonschema2md/blob/f3b5773eb610130891503c1cf71b...