Clarify "components" vs "elements" vs "patterns"

Ideally, @lauriii's answer would reference the diagram in 📌 Document supported component modeling approaches Active .

I've always viewed elements as a type of component. The reason they must be separate from components is because most of the time, you'd want your content creators using components instead of elements. When that's the case, it needs to be possible to disable elements from the page builder.

I created a Figma design to show case the different concepts and their relationship:

→

these are “opted in” from the list of installed SDCs using a config entity

Especially for elements, it seems that this is something you'd probably control in code instead of UI. It doesn't seem necessary to be able to control the available elements on a site level. It could be that elements is just one category.

THIS is where “locking” starts to become relevant, not in “elements”

I'm not sure what are you referring to by locking in this context? The internals of the component should not be editable when the component is being used. When the component is being used, it's only possible to modify props of the component, and insert components to the slots of the component. There could be a way to set up a component with a slot that has a default value, which allows editing the contents of the slot.

these MUST have a default value for each prop to ensure they always have a visual representation

This is the current hypothesis for ideal UX. This is something we need to work to confirm with UX.

1 pattern = 1 or more elements, similar to 1 component, but then in the Page Builder territory, and each time a pattern is used, it’s “copy by value” instead of “copy by reference” — meaning changing the pattern won’t update it everywhere.

This is somewhat correct. They are indeed “copy by value” instead of “copy by reference” . However, patterns would be created using the same building blocks that are available for the content creator. This means that if elements are not available for content creator, then patterns that may only use components too. These are usually created to define pre-configured configurations of the components that look good. For example, you could have a pattern that adds 3 card components side by side, because having one card component on its own doesn't look great.

I actually cannot find anything in the Requirents spreadsheet nor past discussions about “component variants”

I'll craft a user story to the requirements spreadsheet. I could also file an issue with some more information.

In our past discussions, we said that field formatters must be available early. If so, we must be able to express them. If so, exposing them as field blocks probably makes sense? It’d make the upgrade path easy too. OTOH, doesn’t that inherit all scalability problems? We could also make field formatters a distinct “component type” or “renderable”

The discussion so far has been that we'd expose fields through a single field block. This avoids the problem of creating a ton of derivatives. It's probably possible to convert the existing uses to something like that without too much disruption. I did a PoC on that last fall: #3365551-18: Add the notion of a 'configured layout builder block' to solve a number of content-editor and performance pain points → .

Can you confirm the misnaming of the already-committed config entity?

To me, it still seems like we shouldn't have a config entity per component. I personally think that the ideal DX would allow exposing components directly from code, without requiring a step in the UI. There was some concerns around components automatically appearing in the UI and becoming available for content creators. I'm wondering if we should approach that with tagging or categories? This way builder could select either specific components, tags or categories that they want to expose for the content creators. This way you could get rid of the additional step without having arbitrary SDC appearing in the UI.

I've always viewed elements as a type of component. The reason they must be separate from components is because most of the time, you'd want your content creators using components instead of elements. When that's the case, it needs to be possible to disable elements from the page builder.

👍

I created a Figma design to show case the different concepts and their relationship:

Thanks, that's helpful!

Especially for elements, it seems that this is something you'd probably control in code instead of UI. […]

How would you know which SDCs are "elements" vs not?

The need for opting in is something we've said in every discussion 😅

I'm not sure what are you referring to by locking in this context? The internals of the component should not be editable when the component is being used.

What if there's a prop that you don't want content creators to be able to modify?

The discussion so far has been that we'd expose fields through a single field block. […]

WFM — I wasn't part of those discussions.

To me, it still seems like we shouldn't have a config entity per component. […] I'm wondering if we should approach that with tagging or categories?

Please don't repeat that without proposing a solution. You said the same at #3444424-7: [META] Configuration management: define needed config entity types → , and @catch articulated well in #3444424-8: [META] Configuration management: define needed config entity types → why that can't work.

If your proposed solution is tagging/categories, then it's still the same fundamental problem: the site builder must assign a tag/category prior it to becoming available. Unless you're saying that only users with elevated permissions can access the untagged/uncategorized components. For example, when would it make sense to use umami:disclaimer?

Furthermore, it's also a requirement that dragging any component onto the canvas must immediately result in a reasonable visual preview. SDCs may offer examples for props, but aren't required to. Some SDCs would even have nothing visible unless a default value is provided (sure, the UX work may affect this, but we can't keep waiting for that). On top of that, numerous people in the community have raised the need to configure which field type/widget (assuming the data model in ✨ JSON-based data storage proposal for component-based page building Active ) should be used when assigning a value to a prop … which is also information that an SDC does not contain.

So in order to guarantee a good editing experience:

1. 📌 "Developer-created components": mark which SDCs should be exposed in XB Fixed already required opting in SDCs
2. ✨ Allow specifying default props values when opting an SDC in for XB Fixed is being worked on by @f.mazeikis as we speak and once completed, a default value must be configured (which implies selecting a field type + widget too — essentially picking from one of the choices provided by ✨ [MR Only] Edit any component prop, powered by a new FieldForComponentSuggester service, which will power the JS UI Fixed )
3. We'll need tagging/categorizing — future issue

I asked @f.mazeikis to work on that because it's literally in the critical path to being able to use arbitrary SDCs in the XB PoC UI, and is hence in the critical path 🌱 Milestone 0.1.0: Experience Builder Demo Active . As you can see, there's many reasons for this config entity to exist.

If this config entity is something you disagree with, we urgently need more clarity on the product requirements, because I currently don't see any other way to meet the requirements — it seems that there's a conflict then. The only way around it I see is generating such a config entity automatically for every discovered SDC and:

• A) accept that every SDC ends up in an "untagged" bucket by default and hence we can overwhelm content creators, and allow specifying a tag after the fact
• B) accept that some SDCs may fail to generate a reasonable preview and can hence confuse content creators, and allow specifying a default value after the fact
• C) accept the field type + widget suggested by ✨ [MR Only] Edit any component prop, powered by a new FieldForComponentSuggester service, which will power the JS UI Fixed as the default, and allow editing after the fact

(And then we haven't even mentioned 🌱 [META] Support component types other than SDC Needs work !)

What if there's a prop that you don't want content creators to be able to modify?

I would imagine in that scenario you would wrap the component with another component which sets a static value for the prop, and exposes rest of the props for the content creators. Then they would choose to only expose the wrapper component for the content creators.

If this config entity is something you disagree with, we urgently need more clarity on the product requirements, because I currently don't see any other way to meet the requirements — it seems that there's a conflict then.

Should we move the discussion to 🌱 [META] Configuration management: define needed config entity types Active or maybe even open a dedicated issue for this? I'd be happy to open that if you think it's a good idea.

RE: "I would imagine […]" — this implies the creation of a new SDC? This sounds like a complex UX.

RE: separate issue: let's continue in 🌱 [META] Configuration management: define needed config entity types Active 🙏 You shifted the conversation to questioning the config entity here, I just tied the concepts in the requirements to what already exists, to allow me to flesh out child issues for 🌱 [META] Configuration management: define needed config entity types Active 😅

The config entity question also is critical for #3446083-10: Document supported component modeling approaches → .

So, please cite statements from me from both this issue and #3446083 while you respond in #3444424 to ensure that the conversation about "the config entity" is centralized in a single location 🙏

In our past discussions, we said that field formatters must be available early. If so, we must be able to express them. If so, exposing them as field blocks probably makes sense? It’d make the upgrade path easy too. OTOH, doesn’t that inherit all scalability problems? We could also make field formatters a distinct “component type” or “renderable” (name TBD), which seems to make things simpler?

I'd be interested to understand more about the motivation here. Field formatters as we know them in Drupal(ones that output html) go against the concept of components only being passed structured values that they then place in their html.

What if there's a prop that you don't want content creators to be able to modify?

The internals of the component should not be editable when the component is being used. When the component is being used, it's only possible to modify props of the component, and insert components to the slots of the component.

This warrants more discussion. IMO components composed of other components should definitely be able to compose their forms by passing thru props and customizing what props are available on the authoring form otherwise we end up in the same situation various Drupal approaches and Acquia Site Studio have where every usage of a component in another component requires redefining fields on the parent form so they can be mapped from the parent to the child.

Back to the main question for this issue component vs element vs pattern. +1 to @laurii's take that elements are just a type of simple component. Expanding on the similar but different concepts touched on in the issue description for how components will be created/placed on a page. I've seen 3 main types of components that authors want to place:

• : These are the components that will most commonly be placed in XB by authors, you place them on a given page and that's the only place they'll ever need to be rendered.
• : These are components that are globally available, managed by site builders or by privileged authors they exist so that the same content can be placed on many different pages and when the content changes all the pages using the component show the newest content. This concept is implemented in core by blocks where reusable blocks can be placed in layout builder and in paragraphs through the paragraphs_library submodule.
• : These are what are being called patterns in this issue(not a huge fan of the patterns name btw). This is a set of components that have been authored either on an XB page or a separate pattern creation page and saved by a site builder or author to either the site or author's personal library of "patterns". These saved patterns are then available for the author to place when creating a page with XB but unlike reusable components that is a self contained reference to a component pattern components end up on the page as a preconfigured set of standalone components that have no concept of what their parent pattern is. Tossing out alternative names to pattern these could also be called stencils, templates, or blueprints. This is implemented for layout builder by https://www.drupal.org/project/section_library → and not sure if paragraphs has an equivalent.

I'd be interested to understand more about the motivation here. Field formatters as we know them in Drupal(ones that output html) go against the concept of components only being passed structured values that they then place in their html.

I'm on the same page with you – conceptually they don't make a lot of sense in a component based system. The reason we'd be bringing in the field blocks is because it helps us avoid having to move all existing formatters to components. This is critical especially for sites using LB currently.

This warrants more discussion. IMO components composed of other components should definitely be able to compose their forms by passing thru props and customizing what props are available on the authoring form otherwise we end up in the same situation various Drupal approaches and Acquia Site Studio have where every usage of a component in another component requires redefining fields on the parent form so they can be mapped from the parent to the child.

I was referring to something else in my comment. I was mainly trying to explain the key characteristic of a component which is that you can only interact with it through props and slots, unlike with patterns where you can actually start changing the internals of the pattern once you've placed it. I agree we should try to design the system so that we can avoid this problem.

I've seen 3 main types of components that authors want to place

I agree with the 3 main types of components you listed here. I'm referring to the reusable components as "Global blocks" in this content type breakdown. It's definitely not the best term. 😅

not a huge fan of the patterns name btw

Me neither! I think our design team is calling them just "sections" right now since that seems to be a term that is used broadly within the industry. That's a little unfortunate given that Layout Builder is using that term for something slightly different.

#8:

I'd be interested to understand more about the motivation here. Field formatters as we know them in Drupal(ones that output html) go against the concept of components only being passed structured values that they then place in their html.

Agreed. It's not clear to me either, the product requirements do not have sufficient detail on this front.

I see two reasons:

1. XB should be adoptable by existing sites, and existing sites may have invested a lot of effort in having advanced field formatters
2. components do not have logic to transform values; although XB will have adapters for this, some transformations might require multiple adapters chained together, and the UX for that is completely undefined

+1 to @laurii's take that elements are just a type of simple component.

"Simple" is subjective though. Is that sufficient? Are you thinking of an objective measure?

Reusable components

+1, this is essentially the "New Year's Hero" I mentioned in #3440578-61: JSON-based data storage proposal for component-based page building → . In that world, do "Custom Blocks" still make sense? Wouldn't most sites create reusable components instead, because they have more visual flexibility?

Blocks in general are powered by plugins which means they can have logic. So I think in that world:

• Blocks are still relevant because they're plugins, or in end user terms: "renderable units powered by logic"
• Custom Blocks (the block_content plugin) become less relevant — and perhaps for UX reasons XB might want to disable them on new sites
• Reusable components would be the spiritual successors to Custom Blocks — the differences being: visual-centric vs data model-centric

I'm really curious about @lauriii's vision for that aspect, as well as how the UX/wireframes will be handling that.

Blueprint components

Love that name! We could even literally make that UX visually look like blueprints, which I think would not only convey it clearly, but it'd also be a really cool experience!

#9:

• RE: "global block" vs "reusable component" — Why don't we use the term Kyle proposed here? 🤓
• RE: "sections" — please tell them to use a different name — Layout Builder uses that term for something very different, not slightly? (\Drupal\layout_builder\Section appears to confirm this — essentially it's a row of components in the layout.)

@lauriii Can you please bring more clarity to this issue and how it ties into 📌 Allow saving component compositions as sections Postponed ? 🙏

Here's the currently proposed IA which may help get a sense of what the difference is: https://www.figma.com/board/odeJtdvynsTvUIUUpIqO8n/Proposed-component-IA.... How that connects to here is that:

1. Patterns are called "Sections". They are pre-defined compositions of components coming from other groups (elements, components, dynamic components, community components)
2. Blocks are called dynamic components because as @Wim Leers points out in #10, they are "renderable units powered by logic".

Based on that, we can answer that "sections" are essentially the same as what we are calling "patterns" here.

Wow, apparently I already wrote a month ago (July 17 today, June 18 in #10, just before I went on vacation) that "sections" is a very confusing term. I've seen it becoming adopted more and more widely, which is where my question in #11 came from.

I think "section" is being used very differently in the proposed XB IA than what most people expect. For example, see the way that Wikipedia uses it:

1. https://en.wikipedia.org/wiki/Help:Section
2. https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Lead_section

To make it even more confusing, ✨ Create UI scaffolding for the primary panel (left sidebar) Needs work introduced the term "section templates", which AFAICT is what #12 is referring to as "sections". What is the difference? 😅

(The Figma link in #12 does not explain this.)

The goal for this issue should not be to keep it open and keep it going, but to add a docs/end user concepts.md file so we can then close this issue.

It is not conceptually that different from Layout Builder; sections are parts of a page. However, what's different from Layout Builder is how users create sections. In Experience Builder, sections can be created out of components, or they can be created using section templates. Section templates are just pre-configured components that constitute a section on a page.

FWIW, the current terminology is our hypothesis on what we believe makes sense based on competitive analysis. Acquia UX is in progress of researching if the proposed terminology and categorization makes sense for our target user: 📌 Define built-in components and categorization for components Postponed .

(This came up yesterday because @hooroomoo is working on 📌 Implement add button for top level item (section) Fixed , linking that too.)

I think #15 is saying that we cannot/should not document this yet until that UX research is complete. Conveying that.

#15:

1. In #12 you wrote "sections == patterns" → that's clear, even though my caveats/concerns backed by Wikipedia terminology links in #14 still remain
2. But then in #15 you wrote — which makes it very confusing again. Because suddenly it's not just "components" vs "elements" vs "patterns/sections", but there's now a 4th concept: "section templates". It appears that if a "pattern/section" sits at the root level, that it is labeled a "section template", but really, it's exactly the same as a "section"?

✨ Implement the concept of sections within the client Fixed seems to be confirmed by @lauriii to be the way to interpret "patterns".

What's still missing then, is documentation. Is 📌 Introduce a `Pattern` config entity Active sufficiently precise for us to capture that as documentation in docs/*.md, @lauriii?

@laurii Is this a part of the work that I am focused on?