Review Layout Builder UI terminology

Googled a bit and read through some UI libraries.

• Bootstrap
• Semantic UI
• Material UI
• Foundation

For "Layout" or "Layout template" sometimes "Grid" and "Container" are used as synonyms.
For "Component" sometimes "Element" is used, but "Component" seems to be the most popular.

Regarding "Component a.k.a. Block"; isn't it already possible to add Fields?
With a word like "component" in the end I would expect a d7-Panels list with context-related things like "field-a", "node-title" (node context) and "site-header", "breadcrumb" (both global context) as components.
I would not mention the word "block", it's an implementation detail. Not sure if it is helpful when the component provider (block, field, layout) can be shown.

Regarding "The site builder adds one or more sections to the overall as-yet-unnamed-layout-thing".
I imagine you can have endless nested layouts. For example a node can a have an attached view. That view can again list nodes. And so forth. So a "Section/Layout" can be used as "Component". In d7-panels land those were called "mini-panels".
For the top-level "Layout" seems good.

Regarding "Layout" and "Layout template". The distinction is more clear. So +1.

I like "Layout template" as a term, but even if we change the name we're going to end up saying Layout multiple times - i.e. "The page Layout uses Sections which each use a Layout template.". I almost wish Sections were a distinct plugin type similar to Layouts, but were explicitly flagged as being things that are meant to be embedded inside other things. Layouts were not originally designed to be nested within each-other, which is why this is awkward for me. There's value in knowing that some layouts are meant for embedding and others are meant for owning the entire page.

For component vs. block - do we have any future plans or example use cases for non-block components? In Panels IPE we chose to call blocks "Content", but consistently received feedback that we should not abstract the fact that blocks are what's used internally. One problem we ran into was that many Block Plugins had the word "Block" in their label, so you would go to add "Content", but it was obviously that blocks were what's used.

So, I disagree that Layouts were not intended to be nested. We've been nesting them (in some form or fashion) for as long as I've been Drupaling and the Layout Discovery module was built on top of all that knowledge. Maybe you're saying it in the sense that we didn't build a UI for nesting them. That was a conscious decision. UIs for nested layouts are... awkward and difficult. I'm not sure I've ever seen one that I would consider "right".

In terms of the terminology problems here. I am a little hesitant. I don't have a problem with changing terms, I'm just unconvinced that any of the terms we've discussed are demonstrably better than what we have. That being said, I've mentioned before that these things that Layout Builder is building are Entity Layouts. I even suggested a module name change at one point (since if we want to get super pedantic here, Layouts are plugins and we've certainly not built a module which creates new layout plugins so... again terminologically, we have a problem).

I don't really like "template" but if everyone else is on board with it, I certainly won't be blocking any term. But to me, it's kind of like this:

An entity layout is a collection of sections. Sections each specify their own layout plugin and embed individual blocks into the regions of that layout.

That's the whole definition. Adding the word "template" to that doesn't really benefit the definition I don't think. If anything, I think it would make things more confusing because there IS a template involved, and that word means what it always means in Drupal 8... a twig template that drives the layout. I have enough overloaded words in my Drupal vocabulary (Hello Block and Context), and I realize there's a danger of doing that to Layout as well. I'd prefer to not endanger template while we're at it. But that's just my 2 cents.

Eclipse

So, I disagree that Layouts were not intended to be nested. We've been nesting them (in some form or fashion) for as long as I've been Drupaling and the Layout Discovery module was built on top of all that knowledge.

I only meant to point out that the Layout Plugins in contrib were not designed (as in, designed by a frontend developer) to be nested. Not trying to assume anything about the intention of Layout Plugin's architecture.

If I were creating terminology from scratch I would say that inside of Content we have nested the Content Layout, Sections, a Section Layout, then Components.

I don't know that Layout Template helps to clarify things. I think picking a Layout for a Section is the most clear wording for a content editor. For storing the default content layout itself I think something like Content Layout or Content Display makes sense, to separate the concept of laid out content from the library of Layouts.

For this kind of "jargon/terminology" review, it can be helpful to get opinions outside the development team, so tweeted out https://twitter.com/webchick/status/951901240098566144 to use as one possible data point. We'll see if it gets any traction.

Crediting @DyanneNova and @kevincrafts for their help in the #ux channel with this.

Some good replies among the snark:

A: page, B: section, C: row, D: column, E: item
https://twitter.com/kolearyUX/status/952229561512742913

A: page, B: region, C: row, D: cell, E: component/block/module/widget
https://twitter.com/codycraven/status/952034033298321408

A: Body, B: Page, C: Section, D: Card, E: Content
https://twitter.com/melchoyce/status/951964986175311872

A: Page, B: Content Container, C: Section, D: Subsection, E: Element
https://twitter.com/chicagomom/status/951908369098510336

A: Wrapper, B: Page, C: Section, D: Card, E: Content
https://twitter.com/karmatosed/status/951968068590333957

A: page, B: content, C: content sections, D: sub sections, E: content detail/the story
https://twitter.com/cferthorney/status/952099799976808448

A: Body, B: Wrapper, C: Section, D: Element, E: Content
https://twitter.com/_dotrex/status/951981755208265731

A: Page, B: Content, C: Regions, D: Component/Block, E: Content Item
https://twitter.com/ishanmahajan/status/951903069511602179

The actual terminology we're currently using:
A: Page, B: Content, C: Sections, D: Regions, E: Components

Originally E was going to be Element, but gave up on that due to \Drupal\Core\Render\Element\RenderElement

Ok, the Twitter discussion was interesting, in that it showed there's absolutely no consensus for this terminology outside of the over-arching wrapper "thingy" being called a Page. :) Also, that where possible, we should use modifiers (e.g. sub layouts, nested layouts, etc.) in favour of inventing new terminology for things.

However, what I found encouraging out of that discussion was to see that all of our existing terminology did get brought up by various folks, several of whom have extensive experience with content authors and data modeling.

So the summary of that conversation is there was no clear winner on what to call the "overall thing that contains sections," nor that "components" should clearly be called "shazbots" or whatever (and apparently they were already called components dating back to #1852966: Rework entity display settings around EntityDisplay config entity in 2012 (thanks, @tim.plunkett!), before Symfony was even a glimmer in young Dries's eye ;)). There's always a risk (as well as real, tangible work in the form of potential API breaks, documentation becoming outdated, etc.) in introducing or changing terminology, and it's best to only be done when there's a clear pay-off (e.g. "every design agency will understand Drupal 1,000% better if we use the 'shazbot' terminology").

So my recommendation would be to stick with what we've got, and revisit this only if/when either a) we see evidence that the terminology presents a significant enough hurdle to make it so content authors cannot use the UI, or b) a clear standard aimed at our target audience (which to reiterate is content authors, not site builders/designers/developers) comes out and we adopt that.

To me the only missed opportunity would be to adopt Sub sections for D. It's C & D that are most similar to each other (see row/col, row/cell analogies people made) and I think there's value in linking them through naming instead of calling them different things. It would also get rid of "Region" which is not mentioned in any of the responses @tim.plunkett lists above.

Leaving at rtbc though :)

After further discussion, I think we're all agreed that there are no clear changes we should make before beta.

I'd like to repurpose this issue for a review of the terminology used in the UI, and as a stable blocker.

To start things off!
When adding a new section, you are presented with a dialog with the title "Choose a layout".
However, you are already editing "the layout" of the whole thing.
We need to differentiate between the layout of the section and the whole layout itself.

As surfaced by the above tweet thread, it might be better to add a modifier instead of devising a new term.

"Choose a section layout"?? I like that term because it's internally consistent with what we're doing, and has the added bonus of not being mumbo jumbo to end users.

Eclipse

I showed the layout builder to some students with no Drupal knowledge. Here are some observations:

• I could not avoid using the word 'layout' when describing the entire page. I used 'layout template' when I was trying to differentiate the configuration for a content type vs. an individual node.
• When clicking on 'Add Section', they were confused by the relationship between the black panel on the right and the link they had just clicked on.
• The 'Add block' text was also confusing. They were looking for a way to write text.
• The most confusing thing they found was the existing sample content on the page when using the layout builder for a content type.

I looked at the terminology for some other page-builder tools, here's what I found:

• Square Space uses the term 'layout' twice, once for the overall page layout and again for the display of grid/wall 'blocks' within a layout.
• The Elementor plugin for WordPress uses 'page' for the overall arrangement of the page and then 'section' for a row, and then 'column'. The concept of layout is just implicit, the word layout doesn't seem to be used anywhere. They avoid some of the terminology confusion by simply using + symbol for adding a widget to a section.
• The Beaver Builder plugin for WordPress calls the overall arrangement of a page a 'layout' and uses the word 'template' if it's reused for many pages. It also uses the word 'layout' as a category of components you can place on the page.
• Wix uses 'page' for the overall arrangement. You can add a 'strip' to the page that has a layout, but the layout is just one aspect of the strip that you can customize (along with the content and display).

Take-aways:

• It seems to me that 'Page Layout' is a good descriptor for the overall arrangement of a page.
• We should de-emphasize the word 'layout' when you're adding a section, because layout is just one aspect of what you're adding. Removing the text 'Choose a Layout' could help.
• Other tools seem to avoid terminology issues by using a + icon. We would still have to add text labels in the markup to make sure the UI is accessible.

I have screenshots of all the above examples. If this is useful, I can do a more thorough write-up.

Just a comment here in order to think "out of the box".

The "Section" (blue border area) and the "Component" (green border area) in pairs can be described like this in every day life (math, geometry, games, programming etc). In fact some pairs can be combined too.

In my opinion we should stick with the "table/matrix" terminology "layout > row > column". We should strictly avoid including terms like "page" for reasons. The reasons are:

1. As humans we are already used to work in rows and columns. We write on writing books that have lines (row). When using computers in order to separate content visually we change lines (row). When using a spreadsheet we already use rows and columns.
2. Using rows and columns will also allow us to "extend" this terminology. So terms like "layout of 3 rows", "3rd row with 2 equal columns", "Flexible column" do make sense and need no special declaration.
3. Row and column are already used by CSS Grid systems (see Bootstrap, Foundation etc).
4. Rows and columns do no conflict with any other terminology we already have (unfortunately) in Drupal (like Page, Entity Display, View Mode, Component, Module etc).
5. ds module already users columns for layouts templates. For rows is uses "wrappers".
6. Columns and rows are what we call "arrays" so we can use php arrays to create a layout.
7. Terms like Section, Component, Page, Display are overused by JS frameworks out there and there are valid concerns that we will do thing worst for Drupal UX out there if we adopt them.
8. Last, words "layout", "row", "column" are sort, have no space between and have already well known shortcuts that can be used in CSS (eg "column -> col").
9. The terms should be "usage agnostic". The layout core module will be used one day to structure not only HTML Pages but also field forms, paragraph fields, and maybe mobile Views, REST API templates etc.
10. New CSS specs like Flexbox, Grid and Column are using rows and columns in their properties/values with the same meaning.

That's all!

P.S. After writing all these I would prefer to call the term layout a "matrix" or a "grid" but this will cause another Drupalism I think :-P

reroll #21patch for 8.7.x

Some of my thoughts after reviewing the discussion:

• “Add section” and “section” I’m comfortable with that.
• ”Layout template” doesn’t seem necessary to me it would be just adding an extra word to the UI which has no actual context, it might only male sense within the context of actually making a layout Twig template.
• I like “Choose a layout for this section” because it creates a connection between the button the user just clicked and the action they will now perform.
• ”Row” and “column” make sense in the context of a layout, realistically I’m not sure how often we will even need to use these terms maybe only for accessibility and descriptions.
• I’m ok with “Add block” and “Choose a block” as I’m not sure “component” or “cell” would be any clearer (with cell implying a little box you enter a number into). Component or cell could possibly lead to more confusion because many Drupal users are already familiar with the concept of a block and introducing another term could just lead to confusion. To me leaving the term “block” seems the best approach because in the context of Drupal I can’t see there being a better term.

For #26 some of the issues mentioned from the student focus group should be addressed soon: in 8.6 we’ll have the ability to add custom non-reusable blocks directly from the Add Block button, and #2994909: Highlight active element while working with dialogs in Layout Builder may help to address people being confused after clicking Add Section.

Assigning to myself to fix the IS

It's time to resume this discussion as Layout Builder approaches stable + there's been more time for users to work with it as an experimental module.
Upon reviewing the issue + other interactions with community users, it seems like there is largely agreement regarding how to name the top three layout-parts

• Page layout
• Section
• Section Layout

(If I tallied this consensus in error, please speak up!)

I still see some compelling pros/cons for Components vs. Blocks and it doesn't look like a fan favorite has revealed itself. My personal preference is something other than Block, but it doesn't necessarily need to be Component.

This specific preference comes from writing documentation for clients. The same term describing multiple things (particularly when one can contain the other) makes documentation difficult, and I've found it contributes to negative perceptions of Drupal. As far as the (understandable) concerns regarding the addition of new, potentially confusing terminology, I think referring to it as a "Layout Block" (both words capitalized) instead of "Block" would significantly reduce documentation-confusion.

Finally, I see the merits of both "Choose a section layout" and "Choose a layout for this section", but lean towards the former as it's fully visible within the limited space provided by the off canvas dialog.

Below is an attempt to summarize the suggestions thus far to make it easier to resume the discussion and present it to the UX meeting.

Places to consider the impact of the terminology choices

• The usability of the UI.
• The ability to write clear documentation (something that is fine in the UI can still be confusing in documentation).
• Empowering developers to customize Layout Builder for their needs.

Summary of suggested terms

The absence of for/against for a particular term is not necessarily indicative of its popularity.

* = seems pretty close to being the agreed-upon term.

1. Top Level (thing that contains all the sections, currently unnamed)

   	For	Against
   Page Layout*	#26 It seems to me that 'Page Layout' is a good descriptor for the overall arrangement of a page. From the comments here it seems like Page Layout is pretty much the agreed upon term.
   Content Layout
   Layout
   Content

2. Immediate child of #1 (currently called Section)

   	For	Against
   Section*	#30 “Add section” and “section” I’m comfortable with that.	None that I can see.

3. What #2 can contain (Currently called Layout)

   	For	Against
   Layout Template	From IS: Tim and I discussed that the things currently called "layouts" (the layout plugins) might actually be better described as layout templates (since they're just a pattern that gets filled in, not the actual layout as the end user would understand it). Tim also mentioned that there's a loose expectation they'll be rendered via a template From #35 The term "template" is being used in #2988970-36: Layout Builder should make it easier to modify the default layout for an entity type when viewing an entity to help differentiate between the default layout and per-entity layout override. So "Layout template" is not a great choice here.	#10 Adding the word "template" to that doesn't really benefit the definition I don't think. If anything, I think it would make things more confusing because there IS a template involved, and that word means what it always means in Drupal 8... #12 I don't know that Layout Template helps to clarify things. I think picking a Layout for a Section is the most clear wording for a content editor. #30 ”Layout template” doesn’t seem necessary to me it would be just adding an extra word to the UI which has no actual context, it might only male sense within the context of actually making a layout Twig template.
   Section Layout	#23 I like that term because it's internally consistent with what we're doing, and has the added bonus of not being mumbo jumbo to end users.	#33 The one downside with "section layout" though is that those layout template things are also used outside of Layout Builder (e.g. for the Field Layout module which is currently the only way to give forms layouts, and for other things in contrib).
   Layout Section		"Section Layout" concern from #33 probably applies here as well
   Pick/Choose a layout for a section (this was more a suggestion to change to label for choosing one as opposed to a full terminology change	#12 I don't know that Layout Template helps to clarify things. I think picking a Layout for a Section is the most clear wording for a content editor. #24 I also think "Choose a section layout" would be better. "Sub-layout" is ambiguous, but the word "Section" is already used in the UI and clearly illustrated as a concept by the dotted line thingies. #30 I like “Choose a layout for this section” because it creates a connection between the button the user just clicked and the action they will now perform.	This label would not be fully visible in the off-canvas dialog, would be truncated to "Choose a layout for this..."
   Sub-Layout		#24 I also think "Choose a section layout" would be better. "Sub-layout" is ambiguous, but the word "Section" is already used in the UI and clearly illustrated as a concept by the dotted line thingies. #26 We should de-emphasize the word 'layout' when you're adding a section, because layout is just one aspect of what you're adding. Removing the text 'Choose a Layout' could help.

4. What a column in #3 can contain (Currently called Block)

   	For	Against
   Block		Many things already called "Block", additional confusion because Blocks and non-blocks can be added to layouts #5 I would not mention the word "block", it's an implementation detail. Not sure if it is helpful when the component provider (block, field, layout) can be shown. On several occasions there have been people - including FT Drupal contributors - that thought that Layout Builder was only capable of displaying blocks - unaware that it fields and other non-block content could be just as easily used.
   Component	#5 Googled a bit and read through some UI libraries... ...For "Component" sometimes "Element" is used, but "Component" seems to be the most popular. From #35 In code, this is represented by a class SectionComponent, often called "section component" or just "component".	(from issue summary) The word "component" is a bit vague and also used for a few different things already: the \Drupal\Component namespace, the "Component" field on Drupal.org, theme components, and, apparently, parts of entity view and form displays (a field and its display settings, I guess).
   Layout Component
   Layout Block	Doesn't add new vocabulary, but is distinct enough from existing terminology.	"Block" is still used, and "Block" is already quite common in Drupal.
   Element		Too easily confused with render elements

(fully prepared to edit this comment if I missed something)

#34

3) The term "template" is being used in #2988970-36: Layout Builder should make it easier to modify the default layout for an entity type when viewing an entity to help differentiate between the default layout and per-entity layout override.
So "Layout template" is not a great choice here.

4) In code, this is represented by a class SectionComponent, often called "section component" or just "component".

Here's a patch that standardizes the current language to at least agree with itself, and puts the titles in the correct places.

The only meaningful change is from "Choose a layout" to "Choose a layout for this section" as suggested above.

Aside from one small thing, I'm inclined to RTBC this based on the discussion of this issue at the Feb 19, 2019 UX meeting. The largest takeaway from that meeting is that nothing should be changed unless there is compelling evidence to do so. We have not encountered that compelling evidence. In the event that such evidence emerges post-stable, the fact that we would only be able to make UI changes as the terminology between UI and code is not fully in sync at the moment anyway.

My only concern is the visibility of "Choose a layout for this section", which is truncated to "Choose a layout for this...".

Could a followup ticket be created to address issues related to the limited space available in the dialog title bar? (this limited space also hides useful information in the Remove Block and Remove Section dialogs, so it would be nice to have in the queue)

Linking to the existing major bug

Based on the feedback from the UX meeting mentioned in #36 and the existence of #3037124: Off-canvas dialog titles should not be visually truncated, this can move to RTBC.

The in-code naming was kept generic because there was no reason that SectionComponents HAD to be blocks.
In theory, there still isn't.

But because they happen to all be blocks, it is worth calling them that in the UI.

Additionally, we have a lot of code like this:

$component = $section->getComponent($delta);
$plugin = $component->getPlugin();

In that example, $plugin is an instance of BlockPluginInterface.
$component is a SectionComponent.
Renaming that to block would be even more confusing, as we'd have something like Section contains SectionBlock contains BlockPlugin

Crediting UX folks from the meeting where this was discussed: https://www.youtube.com/watch?v=EPM0K4hTo4k

Ok, thanks a lot everyone for all of the great discussion and deep thought on this issue!

The patch looks fine to me, and MUCH less hairy than I was expecting, which is great! I double-checked with @xjm and she's ok with me committing this, despite contributing to the end result which was basically to leave things more-or-less as-is, in absence of a compelling reason (user-driven, competitor-driven, etc.) to change.

I think once this awesome module gets out in front of more non-technical people we will likely find places where things could be improved, but I'd much rather any further terminology refinements be user-feedback-driven rather than "Drupal-contributors-who-are-insider-enough-to-stumble-upon-issue-2929783-and-know-how-to-leave-a-comment-driven." ;) This is a key UI for Drupal, so I suspect it'll get further refined in Drupal 9 and beyond, regardless.

Anyway, GO TEAM! Another stable blocker bites the dust! <3

Committed and pushed to 8.7.x. Thanks!