UX Unification - header component with variations

[thibaudcolas]

Overview

There are too many variations of our header component, with and without breadcrumbs, which don’t always work well in Wagtail 3.0. They’re copy-pasted with little consistency across too many places. We need to revisit this, in particular:

• There should be fewer variations to support
• Supported variants should work more consistently across different viewports
• The markup and styles should be reworked to no longer rely on a float layout, wrapping better, working better in right-to-left languages
• All headers should be compatible with our mobile menu toggle (moving the toggle inside the header rather than using a lot of absolute positioning)
• Adopt suitable parts of the proposed designs https://www.figma.com/file/3SZAkXYKTo52047weXDvb9/Wagtail-3-UI-Inventory?node-id=6613%3A40905

Issues

• Migrate header usage to shared header include
• Update classes to w- prefix & style against the classes no the bare header
• w-bg-grey-50 or similar on containers that have the breadcrumbs in page listing index - wagtail/admin/templates/wagtailadmin/pages/index.html
• Fix an approach for the 'component' {% header %}...{% endheader %} template tag so we can work through the headers that have a more complex sets of actions
• xs wagtail/admin/templates/wagtailadmin/home.html adopt shared header template on the dashboard view #8781
• sm wagtail/admin/templates/wagtailadmin/reports/base_report.htmlAdopted shared header in reports view #8839
• sm wagtail/contrib/redirects/templates/wagtailredirects/index.html adopted shared header for redirect page #8849
• sm wagtail/admin/templates/wagtailadmin/workflows/index.html adopted shared header template in workflows #8850
• sm wagtail/admin/templates/wagtailadmin/workflows/task_index.html adopted shared header template in workflows #8850
• sm wagtail/contrib/settings/templates/wagtailsettings/edit.html Adopted shared header for menu settings editing view #8854
• md (slim header) wagtail/admin/templates/wagtailadmin/pages/index.html Adopted slim header in page listing views #8792
• md wagtail/contrib/forms/templates/wagtailforms/index_submissions.html Adopt shared header in Form submissions listing #8862
  • Could move the dates to under the header
  • Review UX issues on form submission page #3236 in the context of this change
• sm (might be done) wagtail/snippets/templates/wagtailsnippets/snippets/type_index.html
• Fix the issue found where the root page is showing an expanded breadcrumb when technically it does not need to be expanded (as it only has one item) - this is on the page listing view. https://github.com/wagtail/wagtail/pull/8904/files

De-scoped

• Solve for the issue of the sidebar on small breakpoints + Review layout for multiple items on small devices / all responsive breakpoints and long titles Header & sidebar toggle on mobile - styling cleanup #8906
• Solve for the use case of a 'singleton' breadcrumb (either a new template tag or similar)
• lg wagtail/contrib/modeladmin/templates/modeladmin/index.html Adopt core shared header for ModelAdmin headers #8907
• N/A - not work doing right now or maybe ever - Review templates that extend shared header and see if they can use the template/end tag approach instead

Proposed solution

I think this could be a good addition to the Apply new page editor UX to all of Wagtail GSoC project if it goes ahead. We would need:

• @benenright to review the different variants ahead of time and determine which ones should stay.
• @wagtail/ui to help review what third-party plugins do, and what we would want to officially support
• The GSoC contributor to make an implementation / testing plan, implement the new header, and then switch existing views to it

Component architecture

A {% header %} template tag, potentially with a way to pass arbitrary HTML for actions, and support for a breadcrumb. Something like:

{% header icon="calendar" title="View submissions" breadcrumb_items=my_list %}
{% button label="My action" %} {% endheader %}

This component could have blocks so it can be overridden and used with {% include %}, however I think this should be reserved for really special cases (for example the homepage’s avatar) rather than be the default means of reuse. This is similar to why frameworks like React encourage composition over inheritance.

Related

• UI component API for tabs: Feature request: UI component API for tabs #8408
• Dialog component API: New dialog component #8513
• Previous issues: Visual regressions in 3.0rc3 #8471
• Form submission listing issues The page with form submissions is ugly on screens with >=1280px #3759
• The banner landmark should be outside of main (Rework the admin UI’s landmark based on established best practices #5411)

Variants

Here are the variants I have identified so far. I believe there are more for projects that support translations.

Home

Looks a lot like other templates but has the current user’s avatar rather than an icon.

Pages listing

Legacy Wagtail 2 header style with a lot of metadata and actions

Move page

Strange combination of the Wagtail 3 header reskin with the Wagtail 2 breadcrumb

Modeladmin inspect

Similar to the above but with slightly different styles for some reason

Simple header

One of the simplest – icon + heading

Simple header w/ action

The above + action

Simple header multiple actions

I believe some instances have 3 actions.

Simple header with search

A common pattern, often including one or two actions

Header with search, actions, count

I believe this has everything we could put in the header: icon, title, count, search, actions

Header with filtering & export action

Form submission listing

ing

Breakpoints

**Important: ** Must remember that on small devices the side bar shinks down to a small corner square.

• Might be able to find a nicer way to ensure that the header content wraps around this (maybe a sibling selector?)
• Easy to miss when working on header size variants

[lb-]

Also related.
#8368
An attempt to get some kind of consistency for classes on the header component - not sure if we should be doing BEM or not though.

[lb-]

we need subtitle also (different to count) and already used in class based views in many locations.

And we need a description (or maybe info) that could be used for the count content in the abstract sense. (e.g. the dashboard username). Content that is not part of the title but provides useful header info for the page.

And remember that the dashboard has an icon (ish) but it is the avatar. So the icon content should be able to house any Content maybe. Or we use template overrides as a secondary way to control content.

[laymonage]

Snippets edit view

When editing Snippets, the spacing for the "Last updated" row in the header seems too large:

(If it doesn't show up for you, try editing the Snippet and edit it again so that it has a log entry.)

ModelAdmin edit view

This also happens in ModelAdmin:

[lb-]

See also #7190

[lb-]

Added another variant (form submission - has date search) and also added a few breakpoint size examples.

[thibaudcolas]

Here is a Figma file with the Wagtail 3 screenshots from above, and the WIP designs for Wagtail 4: https://www.figma.com/file/3SZAkXYKTo52047weXDvb9/Wagtail-3-UI-Inventory?node-id=6613%3A40905.

[lb-]

@PaarthAgarwal a few code snippets from today's discussion, some potential improvements to the shared header include.

wagtail/admin/templates/wagtailadmin/shared/header.html

• Accept a classname value <header class="header {% if merged %}merged{% endif %} {% if search_form %}hasform{% endif %} {{ classname }}"> so that it is easy to add additional classes (note: existing convention is unclear, it is basically a 5 way split between class classes classname and classnames but classname, class_name is used slightly more.
• Allow breadcrumbs to be passed in more easily AND maybe sets us up for a future enhancement for the singleton breadcrumb use case {% block breadcrumb %}{% if breadcrumbs %}{{ breadcrumbs }}{% elseif breadcrumb_link %}{% breadcrumbs_singleton breadcrumb_link %}{% endif %}{% endblock %}
• Allow for a generic image (aka avatar) URL to be passed into the shared template {% if icon %}{% icon class_name="w-header__icon" name=icon %}{% elseif avatar %}<img class="w-header__avatar" src="{{ avatar }}" alt="" />{% endif %} (note: I have added the w- prefix to the classes here)
• If all of the above are applied in some form it means we can rework the header in the page listing view to use the shared include as follows (roughly)

{% block content %}
    {% trans "Explorer" as title %}
    {% breadcrumbs page=parent_page url_name='wagtailadmin_explore' url_root_name='wagtailadmin_explore_root' use_next_template=True as header_breadcrumbs %}
    {% include "wagtailadmin/shared/header.html" with title=title merged=True breadcrumbs=header_breadcrumbs %}

    <form id="page-reorder-form">
     ...

[laymonage]

Just wondering, would it be possible to make the breadcrumbs tag more generic, i.e. not dependent on the page tree? I imagine instead of working with Page objects, it could accept e.g. a list of dicts with "url" and "label". That would make it easier to reuse the breadcrumbs in other places, e.g. #8623.

[lb-]

@laymonage - we discussed this today and I agree that we will need to support a more generic version of the breadcrumbs template tag. I might raise this as a separate issue though.

The UI team agreed with the proposed approach of using breadcrumbs outside of just showing a page tree.

My thinking

• we create a template tag breadcrumbs_admin or maybe breadcrumbs_singleton / breadcrumbs_simple
• it accepts a single url_name (or maybe just url) and a label
• it always renders the root as the admin home and then the provided
• trailing breadcrumb would still be made available for anything extra
• it would not use the word 'Root' but maybe 'Admin' for the base page
• it would not be collapsible/ just always be expanded
• usage; snippets redesign, ModelAdmin inspect and edit views, form submission listing, maybe users/groups edit
• it would add an extra modifier class (not sure though as this is using tailwind classes)

[lb-]

@PaarthAgarwal as per chat today, one idea could be to move the 'search' stuff (dates/search form etc) into a row under the main row.

We would need to solve for small devices so that the action buttons still show after the search form content - we can either keep the existing DOM structure and move things around with CSS grid on larger devices or go the other way (keep DOM roughly as is but move content for larger devices). Probably best to go mobile first.

[lb-]

@laymonage #8767 created to solve for the generic case of a simple breadcrumb

[PaarthAgarwal]

Pages with are not using shared header:

Pages which can use shared header with little work:

1. wagtail/admin/templates/wagtailadmin/home.html
2. wagtail/admin/templates/wagtailadmin/workflows/index.html
3. wagtail/admin/templates/wagtailadmin/workflows/task_index.html
4. wagtail/contrib/redirects/templates/wagtailredirects/index.html
5. wagtail/contrib/settings/templates/wagtailsettings/edit.html
6. wagtail/admin/templates/wagtailadmin/reports/base_report.html

Pages which can use slim header:

1. wagtail/admin/templates/wagtailadmin/pages/index.html
2. wagtail/snippets/templates/wagtailsnippets/snippets/type_index.html

Pages that'll take more work to use shared header:

1. wagtail/contrib/forms/templates/wagtailforms/index_submissions.html
2. wagtail/contrib/modeladmin/templates/modeladmin/index.html

[lb-]

@PaarthAgarwal I have transposed that list to the main issue description (see 'issues') with just a xs/sm/md/lg framing.

A few bits of feedback

• Slim header - not sure on the snippets index one - we will wait for feedback from Thibaud, but also that area of code is being worked on by Sage as part of the Snippets enhancements so it is likely you will not need to do this.
• Forms index header - I think that may not be a huge amount work, as discussed we can probably move the date filtering part to outside of the header and just at the top of the content.

[thibaudcolas]

Quick update to note we now have designs for all headers – in particular the dashboard, and page listings.

Page listings

Figma link

Dashboard

Figma link

I have created a separate ticket for the summary metrics component underneath the header: #8818.

[lb-]

@PaarthAgarwal - I think we should add a w-header__description div that sits 'under' the main h1

It can be used for the username on the dashboard page and be smaller text.

I think that content will come in handy for other shared header adoption

[lb-]

Note: we will need to ensure we fix the issue found where the root page is showing an expanded breadcrumb when technically it does not need to be expanded (only one item).

[lb-]

Most of this is now done - will look at what needs to be split out so that this issue can be closed.

[lb-]

Closing as completed - left over items that are great to have but ended up being quite large have been split out:

• Header & sidebar toggle on mobile - styling cleanup #8906
• Adopt core shared header for ModelAdmin headers #8907

Great work here @PaarthAgarwal !
And thanks again @thibaudcolas for preparing this and having a clear goal to work towards.