[UX] Add help text on the Layout listing page to explain order and grouping.

[klonos]

This is related to #4841 and was brought up during the Dec. 31, 2020 weekly UX meeting, https://youtu.be/Fc-oQ55LQi0?t=2190 (~37min into the call)

@philsward (referring to the layout listing page) explained:

...just coming and looking at it, I feel that everything is jumbled together ...I don't know what I'm looking at. Nothing is organized, and that was kinda my big beaf with it.

@jenlampton said:

...everything is organized, but it's not clear to anyone looking at the page that it is. ...it's confusing.

Then @stpaultim asked a question about the organization of things:

...I've always understood that the higher up a layout is on the list, the more priority it has.

...then @jenlampton went on, to explain how the grouping and priority works on the layout listing page.

@cellear:

I just learned 30sec ago that the order in this page matters. I had no idea.

@stpaultim:

It doesn't say that anywhere. ...the only reason I think I know that is I think I've heard @jenlampton say it, but I might have misunderstood.

@jenlampton

...and if you have 2 things that can be ordered, a button shows up that says "Reorder". But if you don't ever have them, you would never know that. ...if you never create anything that needs an order, you'll never even know that there are things that can have an order.

This is what @jenlampton was referring to:

---

Proposed solution:

---

Translation update

New strings:

• How layouts work
• As a page is rendered, a <em>Layout</em> is selected as follows.
• The <em>Path</em> for the page is compared to those in the alphabetical list here, and <em>Visibility conditions</em> are evaluated.
• Each path may have one or more layouts available. These are listed beneath the path.
• 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 <em>Default layouts</em> shown at the bottom of this page.
• Note: Paths used by the layout system are <em>menu router paths</em>, not normal paths or !link. For the default About page, <code>node/%</code> is the menu router path, <code>node/2</code> is the normal path, and <code>about</code> is the URL alias.
• For more information and details, see the <a href="https://docs.backdropcms.org/documentation/layouts-and-templates" target="_blank">online documentation</a>

[stpaultim]

I think that we're all getting a bit tired and have looked at this for too long. I think we've missed a couple of grammatical errors.

1) "The Path for the page is compared those in the alphabetical list here ..." should be "The Path for the page is compared to those in the alphabetical list here ..."

2) "The top available layout is is evaluated ..." should be "The top available layout for each path is evaluated ..."

[bugfolder]

Agreed. Made.

[olafgrabienski]

Sorry for being late here. I've not followed the whole discussion but mainly skimmed the discussion about Layout system paths, and I have a question: Should the help text also be valid for paths of core layouts? These don't look like menu router paths to me.

• Dashboard: admin/dashboard
• Home page: home

[bugfolder]

These don't look like menu router paths to me.

They are indeed menu router paths, which are created by the layouts themselves. Put differently, they are layout-created pages, versus overridden pages. (The changes to the layout listing page in https://github.com/backdrop/backdrop-issues/issues/5077 are attempting to make that distinction clearer.)

[olafgrabienski]

They are indeed menu router paths, which are created by the layouts themselves.

Thanks for the clarification! They look more like URL aliases, but I guess it's difficult to cover these cases here.

[jenlampton]

this conversation is making me realize how confusing everything is. I'm so impressed that all of you managed to figure out layouts, and grateful that you are all here to help others ❤️

[jenlampton]

This PR does not need a thorough code review because it's mostly adding interface text, but I can't do it anyway because I was heavily involved in updates to the PR myself. If I could, I'd mark it RTBC :D Is there anyone else available to do so?

[stpaultim]

@jenlampton - As simple as this is, I'm not quite comfortable marking it RTBC. However, I did leave one note/question.

[indigoxela]

This issue proves, how hard wording can be. :wink:

Great result! RTBC :+1:

[irinaz]

Looks good, I think there might be more feedback from users after this help text goes live :)

[quicksketch]

Out of habit I merged this into 1.x and 1.20.x, as it doesn't contain any new features. So I'm moving this to the 1.20.4 milestone.

I think we can work on the presentation and overall approach to extended help text in a follow-up issue. I wouldn't want all the effort to write this text go to waste or wait, and this gives us a good example to work from in the future. Thanks everyone!