UX Unification - adopt breadcrumbs across all of Wagtail

Part of UX Unification - header component with variations #8539

Is your proposal related to a problem?

• Currently there are at least four different variants of breadcrumbs in Wagtail, with three distinct styles used across these variants.
• This creates a problem where the design across Wagtail does not feel unified and also can cause confusion for new editors.

Describe the solution you’d like

• Progressively adopt the new breadcrumbs (aka breadcrumbs next) across all parts of Wagtail.

1 - Existing JS to work in any location

• Breadcrumbs next rely on data-slim-header to be present in DOM #8644
  • Ensure that the new breadcrumbs JS can work even when the breadcrumbs are not present inside the new data-slim-header, see above issue for full details.

2 - page listing index

• Adopt new breadcrumbs in page listing index (keep the light grey background which will sit above the current teal header)
• try {% explorer_breadcrumb parent_page use_next_template=True %} in wagtail/admin/templates/wagtailadmin/pages/index.html
• Fix the odd grey colour that is being added
• Test a bunch of scenarios including root page, deeply nested
• test add a test wagtail/admin/tests/pages/test_explorer_view.py that checks the data-breadcrumb-next is used & the correct template is used
• Test out manually keyboard interaction works ok

3 - page chooser

• Adopt new breadcrumbs in page chooser listing results
  • does not get added inside a header, should be expanded at all times is_collapsible
  • JS behaviour will not be needed for this variant so we want to make sure it works well wagtail/admin/templates/wagtailadmin/shared/chooser_breadcrumb.html
• locale picker needs to be moved out of the breadcrumbs into the element above
• need to ensure that the URLs are the same (admin/choose-page/123/?blah)
• need to solve the issue of the root page showing the URL correctly if needed
• ensure that the page selected is not shown, only its parents and all the way back to root include_self=False?
• look at styling (as per chooser demo screenshots below) but all good if this comes a bit later
• usage to validate
  • page chooser link (e.g. bakerydemo home page edit)
  • page chooser via block
  • page chooser via rich text editor
  • deeply nested page (e.g picking home page)
  • shallow nested page

3a - Add a non-collapsible version of breadcrumbs

• Add ability for breadcrumbs to be non-collapsible & expanded (aka is_collapsible)
• Currently the behaviour is to be collapsed on load and you click to expand, this may not be suitable for some locations.
• There should be a way to pass in is_collapsible=True to explorer_breadcrumb where the default will be false.
• When true the collapse/expand button will be rendered
• When true the data-breadcrumb attribute will be used
• It should add a class (which will make more sense when the CSS is being done) for the modified variant
• explorer_breadcrumb should be the only tag for now that needs this update
• Add a static variant to storybook
• wagtail/admin/templatetags/wagtailadmin_tags.py
• Add test that the right variant of the breadcrumbs is used wagtail/admin/tests/pages/test_create_page.py

TestPageCreation
    # .... other tests
    def test_create_page_breadcrumbs(self):
        response = self.client.get(
            reverse("wagtailadmin_pages:add_subpage", args=(self.root_page.id,))
        )
        self.assertEqual(response.status_code, 200)

        # test that the breadcrumb template was used
        # check that the rendered output contains `data-breadcrumb-next`

4 - use new breadcrumbs in the move page

• Check adoption of new breadcrumbs in move page
• UPDATE - breadcrumbs on move pager are no longer needed due to https://github.com/wagtail/wagtail/pull/8689
  • instead we will just clean up the legacy breadcrumbs template’s & template tag
• wagtail/admin/templates/wagtailadmin/pages/move_choose_destination.html
• uses the different breadcrumb template wagtail/admin/templates/wagtailadmin/shared/move_breadcrumb.html
• See move_breadcrumb in wagtail/admin/templatetags/wagtailadmin_tags.py
• Write a test in each usage test file that data-breadcrumb-next is rendered & the relevant breadcrumbs template gets used

5 - modeladmin page management

• Adopt new breadcrumbs in modeladmin pages (add/edit) - should be done under modeladmin: Breadcrumbs visual bugs #6904
• Reminder - to reproduce these you need to have a page type / pages editable in modeladmin (bakerydemo does not have this set up out of the box) AND use inspect_view_enabled=True

adding to bakerydemo

# bakerydemo/base/wagtail_hooks.py
from bakerydemo.blog.models import BlogPage

# ...

class BlogPageAdmin(ModelAdmin):
    inspect_view_enabled = True
    model = BlogPage

# ...
modeladmin_register(BlogPageAdmin)

Updated actions

• remove the modeladmin breadcrumbs completely (from both the inspect view and choose_parent views)
• to provide a way to go ‘back’ to the listing, copy/paste the same link that exists in the inspect view
• <p class="back"><a href="{{ view.index_url }}" class="icon icon-arrow-left">{% blocktrans trimmed with view.verbose_name as model_name %}Back to {{ model_name }} list{% endblocktrans %}</a></p>
• We will look at this general problem in the buttons work or maybe the header work
• Once done - should be able to close the #6904 as solved a different way (although it actually works fine now, but we don’t want to put screenshots until the breadcrumbs are removed)

6 (DE-SCOPED) - CSS to work in any location

• Update Due to time constraints and this not adding much value right now we will leave the classes as is
• Adopt latest convention for CSS in the new Breadcrumbs
• This may make sense further up in the ordering
• move to BEM classes w-breadcrumb etc
• remove background colour on breadcrumbs so that they can appear on any background w-bg-grey-50
• Add a CSS file and move all styles from Tailwind utility classes to the css file - these can be added to client/scss/components/_breadcrumb.scss for now as we will eventually just remove the existing .breadcrumb class and keep the same file
• Remember to pull out the utility classes from the JS also
• We should be able to remove the {% with breadcrumb_link_classes... section and nest the whole breadcrumbs back in

Phase 2 - clean up

• Misc clean up notes so we do not forget
• 👍 see if we can, or have time to, refactor move_breadcrumb into explorer_breadcrumb so there is only one template tag called breadcrumbs (plural)
• 👍 use_next_template should not be needed anywhere
• 👍 Remove any HTML templates that are now unused, remove non-next storybook, ensure there is no next there is just breadcrumbs
• Remove any CSS for the legacy .breadcrumb
• 👍 Remove storybook for the legacy breadcrumb
• 👍 Update all references to breadcrumb next (pattern library) to just be breadcrumb
• 👍 If not already done, delete the modeladmin breadcrumb template
• 👍 js is called breadcrumbs and html is called breadcrumb (would be good to have one name)
• 👍 breadcrumb-next.html should be renamed to breadcrumb_next.html (or maybe this file will not exist)
• 👍 see if we should remove wagtail/admin/templates/wagtailadmin/shared/chooser_breadcrumb.html and pull the content up to the parent template
• 👎 (not required) rename the breadcrumbs JS file to match preferred convention
• 👎 Still needed by other code remove .page-results a.navigate-pages,

De-scoped - Add new usage

• add any new issues for future enhancements or clean up items

This likely will not happen as breadcrumbs should probably only be used for page path like things, we can review whether something else may be suitable like a back button.

We will need to chat as a team and work out what should happen with the following issues, either close them as not going to implement or think of an alternative way to provide just a ‘parent’/‘back’ breadcrumb (that is not a breadcrumb).

Maybe these can be solved with something in the header?

• Snippets - Add breadcrumb menu to snippet pages #8597
• #8767
• potentially a new type of breadcrumb for ‘single use’ back to listing type thing (snippets, modeladmin etc) and gives us something to put in the slim header

Additional context

• This is part of a wider effort to clean up the header usage UX Unification - header component with variations #8539

[lb-]

Closing as completed - well done @PaarthAgarwal !

[lb-]

Simple breadcrumbs work has been split to https://github.com/wagtail/wagtail/issues/8767