[UX] Add some info about paths to section on "How Layouts Work"

[stpaultim]

Description of the bug

In working on the following issue:
#1929

I found that the relationship between path menu settings and layouts is not obvious and can be a bit confusing.

Issue #1929 helps expose the relationship a bit and makes visibility conditions at the path level a bit more obvious. But, I think that we might be able to make some minor changes to the help text for "How Layouts Work" that would also help folks understand this.

Here is my proposed text (First draft)

There are three kinds of Layouts:

• Layout pages are layouts that create new stand-alone pages on the site. Without the layouts, these pages would not exist.
• Layout overrides are layouts that override existing pages on the site. Without these layout overrides, these pages would use other layouts. Which one is used will depend on the path and visibility conditions. If no other layouts match, one of the default layouts will be used.
• Default layouts are used for paths that have no other matching layouts.

As a page is rendered, a Layout is selected as follows.

• Both Paths and Layouts each have their own visibility conditions.
• The Path for the page is compared to those in the alphabetical list here, and any Visibility conditions specific to the path are evaluated first.
  • Each path may have one or more layouts available. These layouts are listed beneath the path, each layout with their own visibility conditions.
  • The top available layout for each path is is evaluated for matching visibility conditions first, followed by the second, etc.
    • Available layouts can be reordered to adjust priority.
  • The first layout to match all conditions will be selected.
• If no match is found, or if visibility conditions are not met, the page will use one of the Default layouts shown at the bottom of this page.
• Note: Paths used by the layout system are menu router paths, not normal paths or URL aliases. For the default About page, node/% is the menu router path, node/2 is the normal path, and about is the URL alias.

@bugfolder - I'd specifically like your feedback. You put a lot of time and energy into the original draft of this text. I'm not confident my changes are good, but they seem helpful to me.

NOTE: I'm sensitive to translation issues that come up with these kinds of changes in core and welcome feedback on how much to take that into account when making this kind of change.

[stpaultim]

PR:

WAS

SUGGESTED (changes are underlined):

[quicksketch]

Both Paths and Layouts each have their own visibility conditions.

Note this comes with caveats. Paths only have visibility conditions (and menu settings) if it's a path created by the Layout Configuration. If a Layout Configuration is on an existing path (such as node/% or admin), the providing module creates the menu item and sets all access control.

[stpaultim]

Thanks @quicksketch. I'll take another stab at this later, since there is no rush on this issue today.

[stpaultim]

@quicksketch or @bugfolder - What do you think of this revised copy?

[bugfolder]

LGTM

[stpaultim]

We discussed this and some related issues in the Design/UX meeting today.

@jenlampton raised some concerns about using the term "Visibility Conditions" when "Access Conditions" might be more accurate and appropropriate.

In another issue, it was suggested that we add links to documentation pages. I think that makes sense here.

I'm inclined to incorporate at least two links, one to the Layouts Section of the documentation and one directly to this page:
https://docs.backdropcms.org/documentation/visibility-conditions

Any thoughts?

I'll try to update PR to reflect this ASAP.

[stpaultim]

About to push this PR.

3 changes:

1. Refers to "visibility conditions" for layouts and "access conditions" for paths.
2. Add link to: https://docs.backdropcms.org/documentation/visibility-conditions (this page could use some updates).
3. Moves the final line and link to documentation from right to left. (just a thought/idea)

In regards to the last item, I'm not sure if there was a specific reason for aligning that to the right. BUT, I noticed in my own work on this issue, I was not noticing that link. I was about to add a new link to the same page, when I realized it was already there. I think I was just missing it, because it was so far down and to the right. I think sliding it back to the left makes it more easily noticed. Any thoughts or objections? (Atten @bugfolder)

@jenlampton Does this address your concern?

[bugfolder]

Left-aligning the last line does look like the thing to do.

[jenlampton]

Hm :/ To me, this seems quite a bit more confusing than it was before.

The first bullet Both Paths and Layouts each have their own access or visibility conditions. shouldn't be immediately following As a page is rendered, a Layout is selected as follows.It doesn't seem like step 1 of how a layout is selected. The second bullet doesn't seem like step 2 either.

In fact, neither item has anything to do with how layouts are selected, they are both general information about the menu router / access system - which is, in itself, also very confusing. I think maybe we need an entirely separate section for menu router stuff, or maybe we link to a documentation page on the menu system?

It really seems like this change is overly confusing layouts for the 80% of people who just want to know which layout is being used for which page (and won't ever need to know about menu router access conditions).

[jenlampton]

@stpaultim I'm not sure exactly what question you were hoping to answer by making these changes, but I'm hoping we might be able to answer them in another way. Here are some pointers:

Visibility condition
If I add a Visibility condition to the Home page layout and limit it to authenticated visitors only -- that would just switch the layout being used on the home page back to the Default layout - but anonymous viewers would still be able to view the Home page.

1. Menu router delvers home page at /home path
2. Layout system selects layout (for home page)

Access condition
If I add an access condition to the menu router item and limit it to authenticated visitors only, it would make the Home page cease to exist for anonymous viewers -- before it even gets to the layout system.

1. Menu router delvers 404 page at /home path
2. Layout system selects layout (for 404 page)

---

The only reason we have exposed menu router settings in the Layout UI is because creating a Page Layout also creates it's menu router item, and there is no other place for this UI to exist.

---

All the information in the As a page is rendered... section of How layouts work assumes that all of the menu router access conditions have passed, and the layout system is rendering the page that was requested (and not a different page delivered by the router system)

Your recent experience with 403/404 pages might be confusing things, because 403/404 pages are special.

In the case where the Home page (menu router) access condition fails, the 403/404 page will render instead of the Home page. It's not that the access condition causes a different Layout to be selected for the home page (like a visibility condition), instead a completely different page will be delivered by the menu router.

Let me know if your brain just exploded (mine did!) and we can talk about this real-time :)

[stpaultim]

@jenlampton My brain did NOT explode, but only because of how much I've been thinking about this in the last 2 weeks. I think that I'm far enough along, that I'm at about 70-80% understanding this stuff (as of recently).

I was not trying to answer a specific question with the changes as much as I was trying to make changes that I found helpful, without any clear idea of exactly that was or what the best way to do it would be.

NOTE: I suppose that the question I was trying to answer is "What are menu access conditions (in comparison with layout visiblity conditions) and how do they effect layouts and how do they impact which layout renders at a specific path." (I probably could not have asked this question before today).

So far, the changes that have been suggested have been very helpful to me, I very much appreciate the feedback - so that we can make changes that are helpful to everyone (or at least most people) and also be accurate.

Pretty much everything you have suggested has been helpful and I'm willing to keep revising the PR until we get it right (or as close as possible without going too far down any rabbit holes).

At the start of this PR, I was not thinking about links to documentation. I like the idea of using links to documentation, to take the pressure off this "How do Layouts Work" section.

I will make another pass at this PR taking all of the information you have shared AND the idea that we can rely on the documentation page as well and see if I can come up with something better.

In the end, I think I will have to also take a pass at revising the documentation a bit. There are some things there that need updating and some things that could be more clearly stated, based upon this conversation.

[jenlampton]

If you want to keep working on this PR, my recommendation would be to remove everything having to do with access conditions (and menu router settings) other than to say that's they are available here. They do not affect how layouts are selected, or how layots work.

[jenlampton]

NOTE: I suppose that the question I was trying to answer is "What are menu access conditions (in comparison with layout visiblity conditions)

They are not related, but the options you will see inside are the same (because those are the common conditions people tend to use for everything)

and how do they effect layouts

they do not.

and how do they impact which layout renders at a specific path."

they do not.

[stpaultim]

They do not affect how layouts are selected, or how layots work.

That does not sound correct to me, maybe my brain is exploding.

My current understanding is that a menu access condition could very much effect which layout is chosen (default vs custom), in the sense that a layout will not be availble to anyone that does not have access to the path assigned to that layout.

Maybe that's just so obvious that it doesn't seem relevent. But, it was helpful for me to think about and acknowledge that.

[stpaultim]

For me, I think the problem that I'm trying to solve is that menu access conditions are now more visible. I think that's a good thing. But, I don't understand them and having something visible that I don't understand makes things that I thought I understood, more confusing.

I want folks like myself to understand menu access conditions enough, that their newfound visibility is helpful and NOT confusing, even if they are unlikely to actually need them.

NOTE: I think I do understand these things now, but I did not when I first looked at the changes we recently make in core.

[jenlampton]

My current understanding is that a menu access condition could very much effect which layout is chosen (default vs custom)

I think the problem is with this concept of "which layout is chosen". The Layout system is what does the "choosing" of Layouts (as defined in How layouts work). However, by the time the layout system is choosing, the menu routing has already been completed, so it's not possible for the menu access checks to play into the Layout system's choice.

That said, the menu routing system also gets to make a choice - which page's content is delivered at this path. The Routing system is what does the choosing of pages delivered.

If you add both these choices together, then yes! Adding a menu access condition may result in a different layout being used.

But the reason you are seeing a different Layout is because you are actually seeing a completely different page (that happens to use a different layout) at the same path. (The same thing is true for menu items from views, custom menus, anything. The results of any menu access condition anywhere could also result in a different layout being used.)

The access condition is not one of the conditions the Layout system is using when it "chooses" a layout. (So menu routing doesn't really belong in the As a page is rendered, a Layout is selected as follows. section.)

It could be helpful to add a note or a warning somewhere indicating that adding access conditions could have this result, but I also think that makes sense in practice -- when you see the alternative page appear, it feels right that the layout for the page you can see is being used instead of the layout for the page you can't see.

I want folks like myself to understand menu access conditions enough, that their newfound visibility is helpful and NOT confusing, even if they are unlikely to actually need them.

I don't think "how layouts work" is the right place for menu routing documentation. But I am starting to worry that exposing menu access conditions on the layouts overview page could do more harm than good. Both systems are so complicated. Trying to explain how they interact is very hard.

[stpaultim]

I'm going to take a fresh look at this problem and see what I come up with, may take a few days.