Drupal Core now has Layout Builder functionality. We should investigate and figure out if we should cover that in the User Guide, and whether this should replace what we've written about placing blocks, or be an addition.

There is existing documentation to use as a resource:
https://www.drupal.org/docs/8/core/modules/layout-builder

CommentFileSizeAuthor
#7 3073657-no-screnshots.patch12.32 KBjhodgdon
#6 3073657-partial.patch8.42 KBjhodgdon

Comments

jhodgdon created an issue. See original summary.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Version: 8.x-7.x-dev » 8.x-8.x-dev
Issue summary: View changes

This is actually more urgent now. In Drupal 9, the Place Block module (which provided admin/structure/block) is going away completely (it will be available in contrib for older sites). So we will need to replace mentions of that page with Layout Builder. Here is the change notice:
https://www.drupal.org/node/3081957

eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
commented

The Place Block module does not provide admin/structure/block, that's provided by the block module. Place Block was an experimental UI module that provided a sort of AJAXy way to place a block into a region from any page on your site instead of by doing it from admin/structure/block. https://www.drupal.org/docs/8/core/modules/block-place/overview

I'm pretty sure don't mention it in the user guide at all. It was never very widely used.

That said, I still think it would be good to add Layout Builder content to the user guide sometime.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Issue summary: View changes

Ohhhh, my mistake! I guess we'll still have to sort this out then...

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Assigned: Unassigned » jhodgdon

I'm going to work on this shortly... related to #3055055-67: Convert appearance-related modules: breakpoint, color, layout_builder, layout_discovery module hook_help() to topic(s) where I added some notes in comments 67 and 68.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
StatusFileSize
new 3073657-partial.patch8.42 KB

Here's the start of a patch for this... I'm going to have to switch to working on this on my other computer, and probably another time when I have more energy, so I'm uploading what I have for now. Also we'll need some new screenshots.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Active » Needs review
StatusFileSize
new 3073657-no-screnshots.patch12.32 KB

Here's a first nearly-viable patch. It needs some screenshots, but other than that I think it might be OK. Any thoughts? I'll have to work on the screenshots... One note: You can put blocks into layouts, so I moved the block concept topic into this chapter... maybe that isn't necessary but I thought it might be good. ???

dqd’s picture

dqd
Location London | N.Y.C | Paris | Hamburg | Berlin
commented

Awesome work on this, thanks @jhodgdon! +1

+++ b/source/en/structure-view-modes.txt
@@ -1,9 +1,9 @@
+Overview of view modes, layouts, and field formatters.

@@ -12,11 +12,12 @@ Overview of view modes and field formatters.
+How an entity (such as content, a user, or a comment) is displayed depends on

Sorry for nitpicking on a language which is not my native tongue: but shouldn't the comma before the word "and"/"or" rather be left out? http://englishplus.com/grammar/00000092.htm

+++ b/source/en/structure-content-layouts.txt
@@ -0,0 +1,152 @@
+no longer see the table of fields of the classic display manager.

... to phrase it more positive I maybe would consider to use rather something like "if activated the original manage display view will be exchanged by the edit view for Layout Builder" or something similar?

One last question: Since Display Suite already had the ability to change markup and to add HTML attribute classes build in which I haven't seen yet in Layout Builder so far, do we need a mentioning here for users who think of replacing Display Suite by Layout Builder? We did a huge survey on this over the last months and I would like to find a solution to advocate for all the hard work done in Layout Builder. But I wouldn't make users believe that Layout Builder can replace Display Suite in any aspect yet.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Regarding the comma, that is a matter of opinion (look up "Oxford comma" or "serial comma" in your favorite web search engine). The Drupal project standard uses the serial comma, so that was correct actually.
https://www.drupal.org/drupalorg/style-guide/content#english

Regarding the second point, when you choose Layout Builder in that page, everything goes away and you have to click to another page to see any fields... so I wouldn't say we could see something else there? Basically the page used to show all the fields, and now it shows only a button to get to the other page for the layout.

Regarding the third point... Mentioning Display Suite sounds like a good idea ... will have to figure that out. Thanks for the suggestion and for reviewing!

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Regarding Display Suite, probably what we should do is mention that it exists and may have even more features than Layout Builder... ???

dqd’s picture

dqd
Location London | N.Y.C | Paris | Hamburg | Berlin
commented

@jhodgdon: Ah I see! Now I learned something new about English. Great to know that one! Thanks for taking the time to explain. I like this comma exception. :-)

Yeah regarding the second point my quick suggestion wasn't even better. I just somewhat try to think of something more encouraging. "No longer see the table of fields" could scare some users off. :-) Maybe something like: "The editing of the fields are now moved to the Layout Builder editing form, which can be find by activating the view on the EDIT button. Or something like that? Nut sure even if it is an [EDIT] button in the moment.

Regarding Display Suite I would like to raise a finger because it is maybe a little bit wearing topic since both projects put a lot effort in their development and feature sets and do live now side by side with a lot overlapping and users often ask which one to use. In the web many articles say something like "Why we switched from DS to LB" - TBH, i do not like blog posts like this and I still feel a certain "silence" in the room when I start asking about these both. We investigate for it now over half a year and it is pretty complex to explain where the overlaps are and where LB maybe has still some missing parts which are fullfilled by DS. In such cases you maybe are forced to stay with DS even if LB is already working on it or is doing it already but just another way around which is not documented yet so users don' know it works. It's quite tricky. We definitely should collect opinions on this...

I hope you are well! Please take care and stay safe!

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Regarding the line:

. Click _Save_. You will be returned to the _Manage display_ page, but you will
+no longer see the table of fields of the classic display manager.

I think we need to say something here so that people are not alarmed that all of their fields went away. In the next step we are saying to click "Manage layout" to get to the layout manager... I don't think the proposed line in the patch is inaccurate or scary?

Regarding display suite... upon reflection, I am not sure we want to mention this in the User Guide. We are not writing a comprehensive guide to everything you could possibly do with Drupal. We are writing a tutorial that introduces people to one good way of doing the basic tasks that you need to build a Drupal site. So, I think maybe we should not mention Display Suite at all?

dqd’s picture

dqd
Location London | N.Y.C | Paris | Hamburg | Berlin
commented

The line is not "inaccurate" at all :-) and scary was rather literally meant to underline that my thoughts are based on the old joke: Do not use "no" or "not" if you want to encourage people to do something should rather be Use a better word than "no" or "not" if you want to encourage people to do something. :-) :-)

Regarding display suite... upon reflection, I am not sure we want to mention this in the User Guide.

Since Display Suite is contrib and Layout Builder is core I fully agree with your thoughts. My mentioning of it was rather an asking if there is anything left we should do with it to widen the scope regarding what users maybe struggle with. But it would be kindof too much to add here, isn't it? And this is similar to any other contrib module in the scope or with overlaps to Layout Builder. Maybe rather something for the D.O. docs? Let's say, as an additional section below Layout Builder introduction?

eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
commented
Status: Needs review » Needs work

Thanks for working on this @jhodgdona and @diqidoq. It's looking great. Here's my feedback after an initial review:

  1. +++ b/source/en/structure-content-layouts.txt
@@ -0,0 +1,152 @@
+Use layouts to make the content items more readable, accessible, and visibly
+attractive.

    I think this could be more specific. As is it's not clear to me what I'm going to be doing in this tutorial. Maye something like:

    "Display the content of a recipe in a two column layout to make it more readable, accessible, and visibly attractive."

    Or something like that. 

  2. +++ b/source/en/structure-content-layouts.txt
@@ -0,0 +1,152 @@
+==== Expand your understanding
+
+* If you do not see the effect of these changes in your site, you might need
+to clear the cache. See <<prevent-cache-clear>>.

    Another item that might work well here would be something that encourages people to explore the ability to override layouts on a per content item basis. Something like:

    "On the manage display tab for the Recipe content type enable per-item overrides and then modify the layout for a specific recipe." 

  3. +++ b/source/en/structure-view-modes.txt
@@ -25,25 +26,49 @@ mode_. Examples of view modes are:
+If you use layouts, within each column of each section, you can display any
+blocks of your choice in any order. The available blocks include the formatted
+fields from the entity (with your choice of formatter), and for each block you
+can choose the title.

    I think it could be clearer here that the list of blocks includes both the layout builder specific blocks that represent the fields. AND any "normal" Drupal block.