[UX] Create a consistent and responsive step wizard for update.php and install.php

[klonos]

The problem

I've been working on issues like #2858, #512, #3960, #2873 etc. and in many cases it seems that we are "squeezing" the rest of the page for the sake of the sidebar that holds the various steps of the wizard.

After some breakpoint, we are switching to a very simple "Step x of 5" indication at the top-right of the page:

The above works well space-wise, and it solves the problem of not having enough horizontal space to fit all content of the page and style it in a nice/readable way, but we are sacrificing the indications of which step is the current and what are the previous/next steps.

While working on those other issues, this is the best responsive solution for the table added to these pages that I could come up with...

Here's the page as rendered in a wide screen, with as much horizontal real estate as possible (OK 👍🏼 ):

Then, as the screen gets narrower, the main content area gets progressively squeezed till just before the breakpoint that hides the sidebar kicks in (horrible! 👎🏼 ...notice all the wasted whitespace bellow the sidebar):

Then once the sidebar is hidden and replaced by the page indicator at the top-right, we have this (we're back to OK again 👍🏼 ):

Proposed solution

Considering the following:

• It seems to be more sensible UX-wise to always keep the steps indicator in a specific place rather than have it jump around.
• Having the steps at the top of the page frees up all the horizontal space to be available for the main content of the page.
• Indicating the name of each step and denoting the current/previous/next steps is preferred than only indicating the step number.

How about we implement a responsive step wizard that we consistently keep at the top of the page, which looks like a breadcrumb of sorts? There's various examples we can consider. Here are some I found around the internet:

https://codepen.io/kaiv/pen/jKajvB (colors tweaked in the screenshot below to match ours)

https://bootsnipp.com/snippets/4Knm

https://bootsnipp.com/snippets/eN4qy

https://bootsnipp.com/snippets/R5jo5

https://javascript.plainenglish.io/creating-a-responsive-wizard-component-with-only-html-and-css-5a4d95376698

https://stackoverflow.com/questions/41326299/horizontal-css-wizard-navigation

https://www.sitepoint.com/building-step-wizard-bem-sass

https://metroui.org.ua/wizard.html

There's many more here too: https://www.cssscript.com/tag/wizard

[klonos]

The function that generates that list is theme_task_list(), and I see the following things that seem wrong/problematic:

• That function lives in core/includes/theme.maintenance.inc. I understand that that must be because it might have been added to initially hold the list of tasks in update.php, where there's an option to put the site in maintenance mode, but we are using that to add such task lists in other places (like during installation in install.php, and in the project installer pages to name a few that come to mind). I believe that it should be moved to core/includes/theme.inc instead.
• The <h2> class that gets added to the output of that function is hardcoded to "Installation tasks", but in the context of update.php should be something like "Database update tasks" (or "Database and configuration update tasks" - see #1986 why). We should add another variable that allows modifying this text when calling the function.
• The HTML for the list (the <ol> and its nested <li>s) is generated manually, instead of taking advantage of theme_item_list().

So unless the above are done for very specific reasons that are still applicable today, I think that we should fix them here.

[klonos]

OK, here's what I have on my local:

I tried to keep the style as close to what we had previously, and although it seems to work nicely with a few items/steps, it doesn't scale as I'd expect as more steps are added:

Perhaps if we could make the text in each individual step wrap on a second line, then it'd look better. When I try that though, the various <li> elements start wrapping at different breakpoints 😞

I think I'll push what I have in a PR, and leave it to others with better CSS skills than me to see if they can drive this to end. I will then try a different approach (still same idea, just different style).

[klonos]

OK, I've pushed a PR with what I have on my local: https://github.com/backdrop/backdrop/pull/4566

The CSS and overall styling of the steps needs lots of work, but this is to demonstrate where I'm going with this. So here's what the various steps in update.php would look like:

And for context: over in #2858 I'm trying to add a responsive table to hold the contents of the report of the "Review updates" step in update.php. That table would work brilliantly if it wasn't for that sidebar taking up all the horizontal real estate it does. Here's a before/after screenshot that shows how things could be:

So yes, the steps wizard at the top is nowhere near being nice-looking (because my CSS skills obviously suck 😅 ), but the above screenshot should be enough to make the point that we're much better off with a horizontal steps indicator running across the top of the page rather than using a vertical one in a sidebar.

[klonos]

...and here's another idea to explore in order to solve the styling problems when having too many steps: a (horizontally) "scrolling" set of breadcrumb-like steps, which can be either of these options:

• this (plain horizontal scrollbar)
• this (mouse/finger scroll without any visible scrollbar)
• this (allow scroll using left/right previous/next buttons)
• this (clicking an item scrolls the list to center it)

[olafgrabienski]

we're much better off with a horizontal steps indicator running across the top of the page rather than using a vertical one in a sidebar

I like the position (at top of the page), but I'm not sure about the horizontal approach. Yes, it looks nice, but the styling is a challenge. And more important: it doesn't feel robust enough to display more steps (on smaller screens). The horizontal scrolling approaches may work somehow, but don't look really convincing.

How about a combination of the top position and vertical steps? Not so shiny, but does the job. Quick mockup:

[klonos]

What about something more simple like this @olafgrabienski ?:

[klonos]

...I am trying to make this a generic component that can also be used outside the confines of "maintenance" pages (update.php and install.php) - so moving things out of theme.maintenance.inc and putting them in theme.inc, and also moving most of the more generic things into system.admin.css and only leaving things specific to the Seven theme in its style.css file.

The default output of theme_task_list() should be usable in any theme, with enough classes to allow customization, and then I'm planning to make it look nice with the default core themes.

With regards to the "responsiveness", I believe that what I have currently works very well with 5-6 steps or less, which is the most common use case. I'm accounting for the widths of up to 10 steps in the default css, however I believe that it is unrealistic to have more than 5 to 6 steps and expect things to look nice in narrow screens. The "problems" (I wouldn't even call them that - they are more like compromises) in the styling start only when there are too many steps in combination with narrow horizontal real estate, such as in update.php and install.php where we are limiting the max width of the content.

In any way, as I said earlier, the horizontal layout of the steps works much better than the vertical one, since with that we are wasting page space that should be dedicated to the main content section, and causing pages to be unnecessarily long and require a lot of scrolling.

I will tweak a few more things, and I will then push what I have in a PR for people to test and provide feedback. Perhaps those of us with better CSS skills than me can figure out better ways to do this too.

[olafgrabienski]

What about something more simple like this

Looks promising!

[stpaultim]

I like it!

[klonos]

I've closed the earlier PR and filed a draft PR that people can start testing/reviewing if they want to provide some feedback: https://github.com/backdrop/backdrop/pull/4579 ...the new PR still has some cruft in it, but should otherwise be functional. Looking for feedback/suggestions re the technical approach, the design, CSS styles etc.

This is what it currently looks like in the Project Installer (with a couple of dummy steps added in order to demonstrate the style for all complete/current/pending tasks):

I'm thinking to make it so that when errors/warnings come up in the current step, then we should be styling it accordingly (using the usual .error and .warning classes we are using for messages, and the red x or yellow notice respectively)...

[klonos]

I'd love to get back to this sometime soon. Perhaps aim to get it in for 1.29.0 in September.

[stpaultim]

We are talking about this today in the Design/UX meeting (sorry, not recorded). @klonos is hoping to update the PR and revive the sandbox.

@klonos is interested in some specific feedback on design.