Document supported component modeling approaches

I believe @lauriii is aware of this issue, but he hasn't yet commented on this.

My understanding of the Experience Builder product requirements is that we essentially need to support all of the above.

Only when the precise UX is defined (no detailed wireframes exist yet) will we be able to potentially eliminate some of these.

👉 All work I'm doing (including the comments at ✨ JSON-based data storage proposal for component-based page building Active and the work happening for 🌱 [META] Configuration management: define needed config entity types Active is being done under the assumption that all of the above must be supported.

I discussed this in person with @ctrlADel at DrupalCon but looks like I never commented on this issue. The diagram in the issue summary describes the all of ways that I'm aware components could be composed. Something that isn't reflected here yet is that it should be possible to restrict the components that are available to placed within a slot. For example, component author may want to declare that a content author should only be able to insert a heading or a paragraph within a slot. This helps the component author to reduce complexity both from component authors as well as content creators perspective, because the component author can declare which combinations of components are supported. This is a key paradigm from Paragraphs which is heavily used by it's users.

I never knew that this was de facto authoritative documentation that @lauriii was working on, I thought this was an open question 😅

Let's get that cleared up.

In fact, let's even link to this from the project page, because it's really fundamental.

Redid the diagrams and updated the issue description to include @laurii's feedback and other feedback from Drupalcon discussions. Also with talk of this being referenced from the project page I changed the color scheme to be more accessible.

Changes

• Added the concept of an open, restricted, and closed slot. Restricted slots can be restricted by types of components that can be placed or the total number of components that can be placed within the slot. Closed slots help to clarify the functionality of embedded slots. When using a two column component for layout the side by side component may want to populate one column slot with known components through the side by side form(closing the slot) while leaving the other column free for any component to be placed in(open slot)
• Added a few more variations of how the side by side component could be built with slots.
• Added more descriptive text around the models and what "flexibility" means in the context of the diagram.
• Split the diagram into two images one for models and another for forms.
• Removed the different types of form approaches since the direction for XB appears to be using a sidebar. These were replaced with my ideas of what forms would be needed based on how a component is modeled.

I think the conclusion to this fundamental question should be captured in an ADR: 📌 Record Architecture Decisions — to scale to many people + many timezones Fixed .

P.S.: question that relates to how we will implement the above in 📌 Clarify "components" vs "elements" vs "patterns" Active .

Thank you @ctrlADel! I updated the issue summary to be a bit more authoritative because the current drawing would serve at least as a really good starting point. We may consider adding more cases if we discover more later, but we could already use this as the basis of validating decisions we're making. Ultimately, it's likely that we'd like all of these ways to combine components to exist in Experience Builder at least eventually. We may not have all of them in the beginning, but we should at least keep them in mind.

Updating the title to make documentation the ultimate goal.

That's a great step forward, but we need more precision:

• for now, for the sake of simplicity/deciding one thing at a time, we can assume that we only need to support SDCs, even though we know that won't be enough: 🌱 [META] Support component types other than SDC Needs work .
• I don't understand why e.g. the first authoring form in the diagram → has a yellow "Add Component to Slot 1" on the right-hand side: shouldn't that be on the left-hand side of "the forms"? Or what is the meaning of the layout of the different boxes in each "Forms" box?
• I see 5 different approaches, but I don't see specified who defines them, nor where. For example, the second example component (labeled "Components for layout and content"): who defined at what time that there is an "Image component" in the yellow drop zone/slot? Is it the SDC author? Is it the Site Builder? Where is that information stored?

Today, SDCs do not support this information, so I conclude: it MUST be the Site Builder ("who?") in a config entity ("where?").

But given @lauriii's answer at #3455036-4: Clarify "components" vs "elements" vs "patterns" → , where he says no config entity should exist for components … hence "more precision needed" :)

I don't understand why e.g. the first authoring form in the diagram has a yellow "Add Component to Slot 1" on the right-hand side: shouldn't that be on the left-hand side of "the forms"? Or what is the meaning of the layout of the different boxes in each "Forms" box?

The form's aren't laid out in any specific order, it's just a collection of forms(based on my opinion) that show how different modeling approaches change the amount of options an author could have and how many forms they'd have to interact with to create a component.

I see 5 different approaches, but I don't see specified who defines them, nor where. For example, the second example component (labeled "Components for layout and content"): who defined at what time that there is an "Image component" in the yellow drop zone/slot? Is it the SDC author? Is it the Site Builder? Where is that information stored?

In this case the components shown beside the Authoring Forms show a fully authored component. So a user with authoring permissions authored a side by side component with those values using the forms associated to that model. How forms are composed, where they are composed, and how an SDC definition can change from SDC definition -> embedded in a component -> field mapping -> being displayed to an author is probably worthy of it's own diagram.

Looking at this I think there's a way we can make it capable to have a wide range of flexibility without having to have added complexity in how we model components.

In an atomic sense, the component being modeled is an "organism" made up of smaller atomic pieces. This would mean we have atoms for header, text, button, and image which would allow for uniformity in how they're handled across the site. The component, or organism, would be a sum of all the parts and be able to be placed on the page as such, but then from there each atomic piece individually editable according to the parameters it has available to it.

This would support the most flexible option and in my opinion should be how the experience builder defaults. Components are the sum of the parts, able to be placed on the page but then fully flexible from there.

Should a component creator want to create more rigidity into the component they would in essence be creating a "large atom" that encompasses the parts they want to group together. This may be desired but I think trying to make a data/process model that allows for each iteration in the diagram would make it overly complex.

One possibility would be able to declare what type of layout/container/section a component is able to be placed in. This would allow for the "large atom" scenarios to exist while giving the component creator the ability to ensure that the larger component isn't placed into a layout that it won't fit or look good in.

This would also solve for the forms as the form would be dictated by what's in the atom, no matter how large it may be.

Hope this makes sense, happy to draw up a diagram to explain my thoughts!

Got a chance to diagram my thoughts here and put together the following to clarify my thoughts.

These are both modeled in the excalidraw in some fashion but I think it boils down in my head to a simplified way to look at it: Templates and Atoms. (Patterns and elements from the conversation above)

A Template is a pre-baked collection of atomic pieces which are laid out inside an html structure (section and columns). However, once placed onto the page each atom is independent. This template can capture any number of atoms and allow for quick reusability without having to worry about what each atom represents. The storage model of this would only be the collection of atoms and their html structure.

Using this a designer/developer could create a very flexible layout made of independent atomic pieces. This would allow for the most amount of flexibility as the content editor can edit each one independently, delete any one atom, or add more as they want to. This gives content editors quick ways to put content onto the page but the most flexibility once on there. Each atom would have its own defined fields of information and each would be edited independently.

If a designer/developer wanted to have stricter control over how each item is laid out in relation to the next, and require them all to remain intact they could create a large atom. This would give the content editor the least amount of flexibility, but at the gain of strict uniformity to design patterns for their site. If the developer chose to go this route the single large atom would be edited through a single form with fields for each item in it, as defined by the SDC. This large atom could still be put into a template which would then dictate how many columns it's in and what the html structure around it looks like.

If we went this route, from a systems perspective we only have to worry about placing atoms or templates on a page and let the developers/designers choose how big (and how strict) to make their atomic pieces as defined by the corresponding SDC.

From a data model we then only have to worry about two things: Atoms and templates.

Atoms would be defined by the SDC driving it and contain the fields for data and styling config (if we want to do in-browser theming). This data model we already know and love from Blocks with an entity having fields. But we would likely need more than just fields for data that we define now to hold config for things like padding, margin, etc. that would enable in-browser theming.

Templates would be a much simpler data model holding a serialized array of configuration that would represent the entities etc. but wouldn't hold their specific data (just placeholders). When put onto a page, the template would create the corresponding entities and let the data model for the atoms hold all the data.

I think this route offers the most amount of flexibility to cover any scenario designers/developers would want while at the same time having to define the least amount of data models which can help us ship it faster.

📌 Document the current JSON-based data model, and describe in an ADR Active is now far along, and I just opened 📌 Document the current component discovery + SDC criteria, and describe in an ADR Active . #3468112 is related, but different. #3468112 is about the technical specifics, this is about the component modeling XB to support. Ideally, eventually, we'll have a (test) sample for each of the approaches.

I think this one is less urgent for 🌱 Milestone 0.1.0: Experience Builder Demo Active , it's more important for 📌 Document the current component discovery + SDC criteria, and describe in an ADR Active to be done by then. But … I'd be very glad to have this properly documented for sure 🤓🙏

I think that'd be better if done by @lauriii, @jessebaker, @bnjmnm or @ctrlADel though.