[D8] Add ability to create configurable layout templates

[docwilmot]

We should have flexible layouts in core.

Currently to create a new layout, you have to choose a template. Templates are provided in code, in a package with an info file and a tpl file, similar to modules or themes. So to create a new template requires some coding.

This PR allows creating a new template in the UI, by adding an unlimited number of rows, with each row optionally divided into preset columns. Each column a layout region.

There is another issue somewhere, but I cannot find it.

MVP (BLOCKER) TODOs:

• Rename Columns to Regions everywhere (for consistent terminology)
• Change Configure link in drop button to Configure regions
• Change Edit from drop-button; use Configure name instead (edit means db storage is used)
• Hide & automate row names (b/c they should not appear in the UI anywhere else)
• Region names should start from 1 and not zero (Numbers should not reset per row.)
• Region names should default to "Region 1" (region_1), "Region 2" (region_2), "Region 3" (region_3)
• Make rows draggable to re-order
• Add a unique icon to use for flexible layouts (can we change the color, maybe?)
• Basic automated testing

ACTIONABLE TODOs:

• Add ability to re-order rows
• A single 'Add new row' button at the bottom
• Dialog title for adding a row should be Add new row or similar
• Move region names out of fieldset or open by default (b/c they do appear in the manage blocks UI)
• Field label Change column style should be Number of regions (no style setting here)
• Remove the Select number of regions option from the Number of regions select list; set the default to 1, and also select the first available option from the region widths.
• Change text Column style to Column widths (no style setting here)
• Change ratios to approximate percents in column width options
• Change text Selected column style to Selected column widths (no style setting here)
• Default drop-button action for flexible layout should be Configure regions
• Use more intuitive text for Row width behavior options
• After creating a new flexible layout (admin/structure/layouts/settings/flexible-template/add) redirect user to flexible layout configuration page.
• Add a #type = help element to the top of the flexible layout configuration form.

NICE-TO-HAVE TODOs:

• Style human & machine names like we do on the content types page admin/structure/types
• Hide the Row width behavior field via #ajax
• Change order of Row width behavior so fluid (most common) comes first, and is default.
• Put the % widths inside the rendered row examples, remove text below.
• Page title for Configure regions should use the template name
• Add Back buttons and Cancel links to multi-step dialogs
• Style region width selection to remove radios entirely (like we did with layout template selector on Layout settings UI)
• Make the Number of regions select a set of radios instead, and have them be horizontally aligned next to each other (see mockups)
• Rename the Region titles fieldset to simply Regions
• Consider moving the Selected region widths setting into the Regions fieldset, as a description.
• Move the Row classes, Wrapper tagm and Row width behavior elements into a Style fieldset to match the block confgiration UI.
• Move the Style fieldset below the Regions section (since it will be used less frequently)
• Merge icon and name columns on layout template list
• HOLD: Style bulk operations on layout template list to match admin/content

NEEDS FEEDBACK TODOs:

• Add a search filter to the layout template list (does this work with VBO filters?)
• Move layout template list to new admin page admin/structure/layouts/templates & leave the more general "settings" page admin/structure/layouts/settings for general layout settings (like permissions)
• Decide on language for more intuitive text for Row width behavior options
  • Maximum width for each screen size (adds the 'container-fluid' class)
  • Fixed width for each screen size (adds the 'container' class)
  • Full width of page (no row classes added)
• Think about how contrib might be able to use this with other grid systems (e.g. https://getuikit.com).

FOLLOW-UP TODOs:

• Automatically build a matching icon for each flexible layout template

---

Advocate for this issue: @klonos

---

PR by @docwilmot: backdrop/backdrop#2646

[ghost]

@docwilmot For the benefit of those not wanting/able to read through over 1,000 lines of PR code, could you please describe the feature request in more detail...? :-)

[docwilmot]

Reasonable, updated parent issue. (edited)

The current PRs UI is probably not terribly intuitive though. To create a new template, you go to the settings page for layouts module (not the configuration page for an individual layout), click add new template, give it a unique name, then you'll be directed to an interface similar to the layout drag and drop page (it's based on this, extending the editor renderer). Once you've finished adding all the rows, save, then this new template will be available in the configure page of all layouts. Use as normal.

[herbdool]

I like where it's going.

[jenlampton]

I am so excited about this!!! Feedback follows :)

Layout settings page:

• We'll need an icon for the flexible layouts (maybe in a different color?)
• There is a link Edit and a link Configure, but both of these save to config. Both should use the text Configure. Can we merge the two into the same form? If not, how about Configure regions vs Configure name.
• These links should be in a drop-button.

Layout builder page:

• Status message should read "Layout template saved."
• Button should read "Save layout template"
• We should either change the Top region to Content, or start with the same regions as are in all the other core layout templates (header/content/footer).

Add row dialog:

• Dialog title should be Add Row instead of Add flexible layout template
• I would prefer Select row style become two separate questions: Number of columns and Column widths
• Use percentages for widths, instead of # columns, for the people who don't understand that our layout is a 12 column grid.
• Change HTML element for row wrapper into Row wrapper tag to match block UI terminology
• Change Container style label to Row width behavior
• Change Container-fluid to Maximum width enforced for each screen size
• Change Container to Fixed width for each screen size
• Change No container to Always full width of page
• Change order so fluid (most common) comes first, and is default.

Row / Region naming confusion

• The row name is displaying for regions
• No way to define / change region names yet.
• What if we added region name fields to the form, and showed a # of them equal to the # of columns selected (in the same way we can show the percentage options for that number of columns). These could be optional, but if left blank then we'd show the row name instead of region name (same behavior as now).

Configure Layout:

• Icons missing for selection area (mentioned above already)

Manage blocks:

• Nice, here the region names are row name + number. This is a better default than on the Add row page.

Other:

• Layout description not used, unless I'm missing it?

[docwilmot]

Thanks for the comprehensive review @jenlampton. I agree with all your comments. A couple of replies though:

These links should be in a drop-button.

TBH I'm not sure about the entire administrative UI for this PR, but I'm assuming you dont mind the "links within an icon" motif? But I think dropbuttons might look awful from within the icon.

Use percentages for widths, instead of # columns, for the people who don't understand that our layout is a 12 column grid.

I considered this, but some of the fractions arent integers if you do, like 10:2 = 83.333:16.666. Would we round to 83:17? Is that any more intuitive than 10:2 though?

No way to define / change region names yet.

I considered that, and it can be done, but wondered if it would be necessary, considering the region names arent exposed to the end-user.

Layout description not used, unless I'm missing it?

😄 there is a list at admin/structure/layouts/settings/flexible-templates. I did say the UI needs work. I don't know where to put a link to that.

[jenlampton]

TBH I'm not sure about the entire administrative UI for this PR

Yeah, I saw your comment about that on the main issue, but I don't have any better ideas about where to put this.

But I think dropbuttons might look awful from within the icon.

Oh yeah, I hadn't thought of that...

some of the fractions aren't integers ... Would we round? Is that any more intuitive than 10:2 though?

Rounding is fine, even to the nearest whole number. It is more intuitive than 10:2, but only because 10:2 only has meaning if you know it's an abbreviation of 10/12 : 2/12. Which brings us back to the percentages :)

I ... wondered if it would be necessary, considering the region names arent exposed to the end-user.

I noted that as a problem as well. But if we make the region names visible (and hide the row names) to match all the other layout templates, then people will want to change the region names.

We could even kill the row names entirely, and use a random hash or something instead. Nobody will care what those are since they don't appear in the UI anywhere.

there is a list at admin/structure/layouts/settings/flexible-templates

Ooh! I missed that. Checking it out...

[herbdool]

What if in addition to the ratio we have a visual showing the column widths? Regardless I agree it should be two dependent dropdowns: number of columns and column widths.

[jenlampton]

Maybe we could have a tiny example row? I was thinking about automatic thumbnails of the layouts - but that seems complicated...

[klonos]

Thanks for doing the first round @jenlampton ...you beat me to it 🙂 ...very thorough 👍 ...here I go now 😅

• We should either change the Top region to Content, or start with the same regions as are in all the other core layout templates (header/top/content/bottom/footer).

Renaming it to Content seems reasonable. Lets please keep things simple; 3 rows are enough to start with; people will be able add as many as they please now 🙂

• Change Container style label to Row width behavior
• Change Container-fluid to Maximum width enforced for each screen size
• Change Container to Fixed width for each screen size
• Change No container to Always full width of page
• Change order so fluid (most common) comes first, and is default.

I say yes to this, but perhaps include the more "technical" versions of these things in brackets:

• Maximum width enforced for each screen size (container-fluid)
• Fixed width for each screen size (container)
• Always full width of page (no container)
• Row width behavior (container style)

• These links should be in a drop-button.

TBH I'm not sure about the entire administrative UI for this PR, but I'm assuming you dont mind the "links within an icon" motif? But I think dropbuttons might look awful from within the icon.

Yeah, I saw your comment about that on the main issue, but I don't have any better ideas about where to put this.

I think that it's high time we switched from the tile listing to a table here. This would allow us to place the links in dropdown menus, within an "Operations" column (which is a common UI pattern we use elsewhere). It would also allow for a search/filter section at the top, which people could use to search the list of templates; and we could have filters like a select for 1/2/3 column layouts etc (I think that the D8 Layout Builder allows that too ...or maybe I am thinking Panelizer?).

...we can leave the template selection when editing/creating layouts still be a tile listing; that's fine.

Layout description not used, unless I'm missing it?

😄 there is a list at admin/structure/layouts/settings/flexible-templates. I did say the UI needs work. I don't know where to put a link to that.

See my comment above. Having a table would allow showing the description there (as well as allow for a column with a list of which layout each template is being used in).

• There is a link Edit and a link Configure, but both of these save to config. Both should use the text Configure. Can we merge the two into the same form? If not, how about Configure regions vs Configure name.

Yes, lets please just merge the edit and configure forms into one, with the name/description fields being at the top of the region management UI (a-la #475). No need to have people jump into another form to simply rename a layout template.

Some other suggestions:

• Move the "Only templates that are selected here will be available when configuring layouts." message at the top of the page in /admin/structure/layouts/settings. As it is now, as more layouts get added, this text gets pushed down, outside the viewport.

• We shouldn't call them "flexible"; I'd prefer "custom" instead. Later on, perhaps we can allow core layout templates to be edited too; they would have an "overridden" state, and a "revert" action.

• "Deleting the template will affect any layouts using this template." this confirmation dialog could use a list of layouts using it. If not used anywhere, is there any point in having a confirmation dialog? ...we could say "This tamplate was not used in any layout" in the confirmation message.

• (follow-up to the previous point) What happens to layouts that were using a custom template when that template gets deleted? Do we switch them to another template? ...if so, perhaps have the user choose another template as part of the deletion workflow? Either that, or disallow deleting custom templates while they are being used.

• Canceling a custom layout template deletion redirects to /admin/structure/layouts/settings instead of /admin/structure/layouts/settings/flexible-templates ...which is not a bad thing at all, if we decide to turn that into a table and include the operations drop-downs there.

• When clicking the "Add row above" action, the drop-down is hidden behind the row (happens momentarily):

  

• Nothing happens visually when you remove a row (either existing, or newly-added). You see the effect of the deletion only after saving the layout template.

• The name of the layout template used for each layout in /admin/structure/layouts is a link. It currently leads to the configure layout form for each layout. Now I think that perhaps it makes sense to make it point to the edit page of that template.

That's it for now. Loving this ❤️ ...so much so, that I am tempted to set the milestone to 1.14 😄

[docwilmot]

Lets please keep things simple; 3 rows are enough to start with; people will be able add as many as they please now

Agreed, plus, once you've added new rows, they wont be necessarily at the "top" or "bottom" any more!

Maximum width enforced for each screen size (container-fluid)
Fixed width for each screen size (container)
Always full width of page (no container)
Row width behavior (container style)

I think these are too verbose, and still unclear; how about:

• Fixed width (container)
• Full width with margin (container-fluid)
• Full width without margin (no container)
• Row width behavior (container style)

I think that it's high time we switched from the tile listing to a table here

That would work nicely, especially if it mimics the layout list in appearance, but it would be a big change, would like to hear thoughts on that!

Yes, lets please just merge the edit and configure forms into one

I dont like this though, this UI borrows from the Editor renderer which builds the drag and drop block page for layouts: an initial page to create the layout and a separate page to configure it. And yes it matches other areas in core where you define a thing with its machine name, then you go somewhere else to configure it (menus, Views, etc). Plus, did I mention I dont like it? I think it would look awkward.

We shouldn't call them "flexible"; I'd prefer "custom" instead

I considered that, and I also dont really like "flexible" but "custom" is taken: thats what you'd call templates you make and store in /layouts, like custom themes or modules.

What happens to layouts that were using a custom template when that template gets deleted?

Good point; could swap them to whatever "Default layout" is using, or Moscone.

Nothing happens visually when you remove a row (either existing, or newly-added). You see the effect of the deletion only after saving the layout template.

Missed that. Fixable.

[olafgrabienski]

Wow, I also like the PR!

(My test page: http://2646.backdrop.backdrop.qa.backdropcms.org/test-page)

I've only one question at the moment: While adding rows to a test layout, I was wondering if I can reorder them, and it doesn't seem to be possible. Is that by design?

[jenlampton]

Lets please keep things simple; 3 rows are enough to start with ... Agreed, plus, once you've added new rows, they wont be necessarily at the "top" or "bottom" any more!

👍

I think these are too verbose, and still unclear; how about:
Full width with margin (container-fluid)
Full width without margin (no container)

These options are less clear; a margin can be anything! I'd much rather have an accurate but verbose description that people will understand, than something that's too short and ends up cryptic.

• Maximum width for each screen size (adds the 'container-fluid' class)
• Fixed width for each screen size (adds the 'container' class)
• Full width of page (no row classes added)

it's high time we switched from the tile listing to a table ... This would allow us to place the links in dropdown menus, within an "Operations" column

But we already have a table. and making "Which templates are allowed?" question into a giant table makes it hard to tell that it's even a question anymore.

we can leave the template selection when editing/creating layouts still be a tile listing

We can leave the template selection for enabling/disabling layout-templates too.

The tiles on the settings page are intended for one purpose: to enable/disable the layouts allowed, and to give people a visual cue (the tile) as to which is which. I think we should leave this interface as-is, and move all the other layout-template related things to the layout-template listing page, the one that's a table.

(That includes moving the action link Add flexible layout template -- or whatever we decide to call it -- to that page too)

lets please just merge the edit and configure forms into one

I have the same hesitation about this as I do with #475. It would only be an improvement with a simple layout. The same way that is only an improvement when you menu is less than 50 links long. When you have a complex layout, or a very long menu, you don't want those other settings on the same page, or in the same form.

Move the "Only templates that are selected here will be available when configuring layouts." message at the top of the page in /admin/structure/layouts/settings

This change isn't necessary if we use the existing layout-template table UI for everything this form element wasn't intended to do.

We shouldn't call them "flexible"; I'd prefer "custom" instead. ... I considered that, and I also dont really like "flexible" but "custom" is taken: thats what you'd call templates you make and store in /layouts, like custom themes or modules.

I agree with @docwilmot, having another namespace conflict for layouts would be a bad idea. * For WordPress these are called Divi Layouts. Can we steal that name?

• This issue title calls them configurable layout templates. Would that work?

Now I think that perhaps it makes sense to make it point to the edit page of that template.

I disagree. I don't think we should take a tool people might have already been using and change it to do something else. It would be better to add another link.

What happens to layouts that were using a custom template when that template gets deleted?

Can we check and see if a layout-template is in use, and throw an error instead? I expect that this would be a mistake or an oversight 99% of the time. I'd prefer that we make people actively change their layout-template before they are allowed delete one that's in use.

I was wondering if I can reorder them, and it doesn't seem to be possible. Is that by design?

I expect this can be added, but it's probably not easy!

---

There's a bunch of great feedback in this issue already, but I want to stop us from having too many more good ideas until we get a round 2 of the PR. Otherwise, there will be too much to keep track of in these comments. (Maybe we can create a todo-list of changes in the parent issue?)

[klonos]

But we already have a table. and making "Which templates are allowed?" question into a giant table makes it hard to tell that it's even a question anymore.

No it won't; we'll gray the disabled ones out, and move them to the bottom of the table; same as we do with the views listing for example 😉

These options are less clear; a margin can be anything! I'd much rather have an accurate but verbose description that people will understand, than something that's too short and ends up cryptic.

• Maximum width for each screen size (adds the 'container-fluid' class)
• Fixed width for each screen size (adds the 'container' class)
• Full width of page (no row classes added)

There's a bunch of great feedback in this issue already, but I want to stop us from having too many more good ideas until we get a round 2 of the PR. Otherwise, there will be too much to keep track of in these comments. (Maybe we can create a todo-list of changes in the parent issue?)

Yes, I will go through all comments and make a tasks/ideas list in the issue summary. For the ones that we don't have consensus, I'll add a "Decide if ..." prefix 😉

[jenlampton]

I will go through all comments and make a tasks/ideas list in the issue summary

Perfect, thank you!

For the ones that we don't have consensus, I'll add a "Decide if ..." prefix 😉

"needs more feedback" maybe? :)

we'll gray the disabled ones out, and move them to the bottom of the table; same as we do with the views listing for example

I think my resistance to this idea is that right now we only have one layout setting: "Which layout templates?" ...but the current page is a layout settings page (and not a layout template list) because we were anticipating having more settings for layouts. Especially as we start to expand layouts to match more of what panels provided.

Where do the other setting questions go, if we remove the layout settings form and replace it with a layout template list? Or do we remove the form now, but add it back later, when we have more layout settings?

[docwilmot]

The layout templates settings page admin/structure/layouts/settings, with a table instead of icons.
Still WIP, and havent sorted out default checked checkboxes for enabled templates:

[klonos]

Looking good @docwilmot 👍 ...as always ❤️ you work!

Thoughts/ideas following...

[klonos]

• the page title could use the template name, so I know what I'm editing.

• we could get rid of the 2 "add row above/below" actions from each dropbutton, and instead add "+ Add row" buttons; something like this perhaps:

  

  ...this would also make the "Configure" operation the default. So win.

[klonos]

...back to the layout settings page (layout template table):

• we have removed the container/border from the bulk operations in the rest of the UI, we should do the same here

• we could use a search filter

• "Configure" should be the default operation for user-created templates

• I don't see the point in having the layout icon be a separate column. Merge with "Name"

• Make human names bold, and add machine names in a separate row. Like we do in the Views listing page

[docwilmot]

Thanks for the feedback. Not sure I like the 2nd screenshot in #3755 (comment), will see what everyone thinks, but it seems a bit more complicated than I'd like.

[docwilmot]

But I've just realised a serious weakness of my current UI: you cant edit column names in a row! 😮

[klonos]

@docwilmot during todays' dev meeting, we have all agreed that "flexible" is the name to go with, so all good on that front 👍 🙂 ...now all that's left is to pick an icon and go with it!

[quicksketch]

The icon is also a low impact change we can swap out at any time in a bugfix point release.

[quicksketch]

I re-reviewed backdrop/backdrop#2646 and pushed a commit to that PR that fixed code style in several places and fixed an issue with selecting the first radio button always when changing between region (column) counts in a row.

However, the current pull request has issues when saving values.

• The "Save configuration" button when changing a row's settings does not save or close the dialog. This happens on editing existing rows or when adding a new one.
• Clicking "Configure row", then "Change region widths", select a different option, then click "Cancel". The new selected region style should be ignored, but instead it's saved, in the same way as though the "Save region widths" button was clicked.

[quicksketch]

Ah, I caused the first problem, and now fixed it.

The second problem where the "Cancel" button saves the layout regions when it shouldn't is still an issue, but not a complete show stopper. I'll see if I can work out that last issue.

[quicksketch]

Okay I think this is ready for another set of eyes again. Overall I made the following changes:

• I fixed the "Cancel" button problem described above.
• There was some code to "lock" and "break lock" layout templates as they were being edited. However, this code did not seem to actively be used and the break-lock callback had several undefined variables. As editing layout templates seems less prone to conflicts than layout configurations, I didn't think this was a big loss, so instead of attempting to fix it I just removed it.
• Enabling and disabling non-flexible layouts via the Enable/Disable button did not work. I moved this code into layout.admin.inc and made it work for for flexible and non-flexible layouts.
• Small function naming changes. I tried to increase consistency but naming is sort of all over the place.
• I made this icon for now based on @klonos's suggestion above. Not at all attached to it if we want to change it later:

[quicksketch]

One more set of changes based on @herbdool's review is up.

I was also bothered by the direct writing of config files in form submit handlers: when we have data structures, we should have official APIs for writing config. So I converted the $flexible_template variable everywhere from an array to an new LayoutFlexibleTemplate object. Now just like the Layout class, if you want to save or delete a template you can use $flexible_template->save() or $flexible_template->delete().

I also change the pseudo-constructor to be a real one, now that we have an object.

Before
$flexible_template = layout_flexible_template_template_default() // Creates an array.

After
$flexible_template = new LayoutFlexibleTemplate() // Creates an object.

[quicksketch]

Merged backdrop/backdrop#2646 into 1.x for 1.14.0. Thanks @BWPanda, @herbdool, @jenlampton, @klonos, @olafgrabienski, @stpaultim!! And a HUGE thanks to @docwilmot for spearheading this one!

[quicksketch]

@docwilmot Found a bug in our token checking for deleting rows. Follow-up PR at backdrop/backdrop#2842

[quicksketch]

I got a spot check from @docwilmot in Gitter. Merged backdrop/backdrop#2842 in with his feedback.