Navigation Overlay customisation via Template Parts

[jasmussen]

Update

Following discussion in this Issue the aim is now to make it possible to define the overlay as a separate template part.

This will allow users to create a totally custom overlay and associate that with a given Navigation block via the template part's unique identifier.

As template parts are a blank canvas, it will be possible to have a different Navigation block within the template part itself which will solve the requirement whereby some users wish to have a different menu on "mobile".

Styling of this template will be achieved via #40318.

This Issue is an "epic" and will need to be further broken down into it's constituent parts.

User Requirements

These are the high level requirements for the feature.

• As a user...
  • I should be able to customise the visual styling of the overlay that appears for a given Navigation block.
  • I should see the Navigation block within my overlay is – by default – automatically kept in sync with menu used in the parent Navigation block.
  • I should be able to display different items in my overlay Navigation than those shown in the parent Navigation.
  • I should be able to style the Navigation block used in my overlay differently than the parent Navigation block.
  • I should not be able to make my overlay inaccessible to any user.
  • I should not be able to “break” the interactive functionality of the overlay using the editor.
  • I should be able to style my overlay via Global Styles.
• As a theme creator...
  • I should be able to style my overlay via Theme JSON.
  • I should be able to provide a default navigation overlay template that will override the default one supplied by core.

Glossary

• "Parent Navigation" - the navigation block which controls/triggers the overlay.

---

Issue update: Dec 23

To enable full customization of the contents of the Navigation overlay menu, it could become a separate block, with its own possible inner blocks, paddings, and global styles properties. To enable that, we could have the overlay button invoke a "focus mode" editing of the overlay block:

An additional affordance, for example for when the overlay only invokes on mobile, could be to add an Edit button in the Display panel of the inspector:

The Overlay could be surfaced in the List View in the same style as position: sticky; group blocks in #30121:

However it would not be a requirement for this issue, and if helpful to the development effort, there is no need to optimize for more than a single navigation menu with a single overlay that are directly tied together with no ability to replace one overlay with another.

There are technical questions to consider (please see this conversation), it would be good to consider these in light of template parts as well, since ideally the experience of entering and existing focused mode can feel similar.

The overlay block should be stylable in Global Styles (a la "core/navigation-overlay": {), so custom paddings and styles can be applied. This should also address #44182.

Figma.

---

Initial proposal (Issue updated Nov 7.)

As of #43576, it is now easier to position the little navigation overlay menu icon (burger menu) so that the close icon from the overlay will perfectly overlap it. To do that, you:

• Ensure the navigation sits inside a wide container block, which itself is inside a container that inherits layout
• Ensure that the navigation menu sits aligned to the top/right of this container and has no additional padding or margin
• The theme opts into root paddings (Core CSS support for root padding and alignfull blocks #42085), by adding "useRootPaddingAwareAlignments": true in theme.json under settings, and paddings to go with that either in global styles or under styles > spacing.

The result is that the menu icon will sit in the exact place where the close icon will sit:

This is working well. However, it works mainly well for themes that look good with the menu icon in the extreme top right corners. Other designs would benefit from a little vertical padding above the menu item, to optically balance, for example, a site title with the burger icon. Like so:

At the moment, all 4 paddings for the overlay menu are set to be the same as any root padding applied to your site. It would be nice to be able to customize these paddings further, by simply surfacing this padding control for the overlay menu, so for example the top padding could be set just a bit higher, to match any custom header padding, making things line up.

For starters, this could be implemented in theme.json only, and a padding control for the overlay could be added to the block at a later point.

[MaggieCabrera]

yeah, I wonder about that as well, @getdave @scruffian @draganescu is that what's going to happen with the overlay in the future?

[jasmussen]

This issue has been updated to tackle the idea of making the overlay menu a separate block that can be edited in focus mode. If you're subscribed, it could use both technical and design feedback!

[mtias]

I think it should be a template part, not a separate block.

[draganescu]

I agree w/ @mtias because I think it's a good idea:

• we keep how the block works now as a default
• if the theme or the user creates a navigation-overlay template part the block automatically uses that

Whill this template part be able to include the block that references it? 😁

[MaggieCabrera]

The point of it being a separate block is so it has different customization options: the overlay usually doesn't share the same spacing options or typography settings as the desktop navigation does. How can we accomplish that with template parts?

[Retrofitterdk]

A template part seems like a more flexible way to go. I see use cases where the navigation overlay needs to contain other elements than menus. it could be

• a login/logout button
• a search field

Or maybe multiple menus. Maybe the desktop site has more than one menu, and instead creating a third specific mobile menu you want the mobile menu to combine the two desktop menus in order to reduce maintenance burden for editors.

[mtias]

@MaggieCabrera with #40318

[getdave]

With the addition of #40318 the template part route seems like a good choice. The obvious downside would be that we'll need to find a way to making it obvious/easy for the user to know that they need to do this in order to create a different overlay.

[jasmussen]

Let's move this to the dev category! @getdave feel free to update the title to reflect the template part mechanics. 🙏

[getdave]

@jasmussen I've gone ahead and updated the title and the description to reflect the "template part" route.

However, I don't see this as being ready for dev in the sense that we don't have a clear UX for how the interactions for creating and associating template parts with a given Navigation block will work. There are lots of edge cases to be explored and I believe this will be quicker and more effective to explore in Figma than in code.

This project will have a good degree of complexity involved and in order to be as efficient as possible it would be very helpful if we could (collectively) explore this model in more detail before we proceed.

Do you agree?

[jasmussen]

Sure, can you list out a couple of flows that you'd like to see outlined better? The current mockups assume as little UI as possible, as a goal to strive for: you toggle the "Mobile" or "Always" part of the segmented control, and boom: now you have a separately editable overlay with no other action needing to be taken. Do we need user-steps in between?

[richtabor]

Did some digging on this:

The navigation block uses an overlay template part, provided by core—or by a theme. Let’s name it navigation-overlay.html for the sake of this walkthrough. Out of the box, the core navigation-overlay.html template part contains a stack block with a navigation block inside of it.

When I click “Edit” on my first navigation block, it will modify the template part and save those modifications in the database as usual. I see the template part in isolated/focus mode. At this point I can edit the contents of this template part, including adding buttons, social links, or even assigning a different menu within the overlay's navigation block.

However, if I then click “edit” on a second navigaiton block, this is no longer the standard template part modification flow, because we already have a modified version of navigation-overlay.html from the first Nav block.

At this point, the navigation-overlay.html template part (on the filesystem) is used as the source to create a new wp_template_part post in the database, but the connection is severed with the original template part. This is because we need unique slugs and template parts.

This would mean that themes could provide a unique, and customizable, mobile navigation overlay, and you could have different overlays for each navigation.

This method is being explored in #55657.

Props: @scruffian @getdave @MaggieCabrera @draganescu

[draganescu]

Here is a visual representation of what should happen, in my understanding (click to expand for details):

Details:

• the navigation block has a default hardcoded overlay
  • this default is an overlay block with one navigation block inside
  • the overlay block is like a group block in terms of supports, but only exists so that themes can style the overlay colors, fonts and spacing of the navigation overlay
• for every navigation, new or existing, editing the overlay will create a wp_navigation_overlay post based on the default overlay content
• in a navigation block, changing the navigation also changes the overlay
• two navigations cannot share the same overlay
• styling of the overlay can be globally preserved by applying overlay block styles as global
• whenever an overlay is edited for the 1st time the ref of the navigation block in the overlay is set to be the same as the ref of the navigation block whose overlay is edited
  • once the overlay is edited (or simply a custom one is created) the ref of the navigation block can be changed and it will not be changed back

Alternatively:

• we could do without an overlay block
• themes can provide a template part which always has to have the same name parts/navigation_overlay.html
• the navigation block starts either from the theme template part or from its default makrup
• if the theme provides an overlay template part the user always starts from the template part, which can also be independently customized and the customized template part serves as the new base.

[luisherranz]

Happy to see some movement here 🙂

Feel free to ping @WordPress/interactivity-api for anything that needs to be changed in the frontend implementation.

[scruffian]

With respect to styles there are a few challenges we need to consider:

1. Navigation blocks already provide tools to style the colors in the overlay.
2. These styles are tied to the submenu - they are the same.
3. For backwards compatibility we cannot break these colors on existing blocks.

In addition to these challenges, we need to preserve the current overlay behaviour to avoid making changes on users sites. I think therefore that if a navigation block has a custom overlay we should update the labels on the color settings to only apply to submenus and not to the overlay.

[scruffian]

I also think we need to do something to preserve the relationship between a navigation block and the navigation inside the overlay - these two should always be kept in sync unless the navigation inside the overlay is explicitly edited.

[getdave]

I've updated this Issue's description with a proposed set of User Requirements. I expect these to act as a north star for the work on this feature.

I think it's important that we don't loose sight of user goals/expectations.

[richtabor]

Composites of expected flows:

Simple:
User one has a header navigation menu, clicks on "Edit" to edit the overlay, changes the background to black, sets alignment to center and sets the font size to large. Done. The navigation items are the same, as the refs match. When I make changes to one menu, those changes are reflected on the other.

Intermediate:
User two has a header navigation menu, clicks on "Edit" to edit the overlay. This user wants to have different items in the overlay navigation. They choose a different menu in the Inspector; the menus are no longer in sync.

Advanced:
User three has two header navigation menus, used throughout the site on different templates. This user clicks "Edit" to edit the overlay, changes the styles of the overlay and adds additional blocks to the overlay. This user wants to use the same customized overlay consistently throughout the site. This user needs to be able to select an existing overlay template part. (to do later)

Thoughts?

[getdave]

@richtabor These seems to align nicely with the existing user stories although the Advanced part has some elements that are not captured. I wonder if the User Stories can be adapted to incorporate your Simple, Intermediate, Advanced scenarios?

[richtabor]

Hey team,

I summarized much of the conversations, concepts, and feedback into a prototype, and make a video walkthrough.

There are a few rough edges to iron out yet, but I think we're on the right path. Not shown is editing overlays in the site editor > patterns view, and a next iteration where you may potentially change the ref of the menu within the overlay.

Thoughts?

nav-overlay-walkthrough.mp4

[paaljoachim]

@richtabor
Rich. Wow this is awesome! Adding a prototype very much helps give the visual feel of what it might look like!

Clicking Edit to enter the Edit overlay mode -> Shows Navigation overlay in the top which is very helpful.

In relation to editing the menu elements specific to the overlay. Can we add a bigger font or change the text color which will only impact the overlay and not the regular menu?

[MaggieCabrera]

In relation to editing the menu elements specific to the overlay. Can we add a bigger font or change the text color which will only impact the overlay and not the regular menu?

Yes, the goal is that the styles of the nav block within the overlay can be totally different than outside of it, included justification/alignment and any other styling controls that you know have

[paaljoachim]

Thank you for the feedback Maggie!

[getdave]

@richtabor This aligns nicely with the current direction of this PR 👍

[getdave]

Update

Now contributors are back at the start of the new year, I felt now was a good time to revisit this effort and provide an update on status.

We have a PR which implements the proposal to utilise template parts allow for editing the Navigation block's Overlay.

During the course of working on that PR it has become apparent that there are a number of different UX routes that could be taken in regard to determining how the correct template part is chosen and also the various scenarios that arise when making changes to the contents of the Overlay.

In short, it's my view that from a UX perspective this project is much more complex than anyone first appreciated. In addition, this PR is currently only a prototype and is far from being a refined experience. There are a number of edges to the problem that need to be explored and resolved and the amount of effort required to resolve these is unknown.

As a result, I'm feeling ever less confident that we can land this PR for the 6.5 release. Even if we were to settle on a UX and solve all the technical issues in the few weeks left before Beta 1, that leaves very little time for user testing and feedback before it lands in a major WordPress release.

Therefore, I think we ought to consider removing the Navigation Overlay feature from the roadmap for 6.5 and instead target it for a future release. We can however, continue to work on the feature during the 6.5 cycle and aim for its inclusion within the Gutenberg Plugin.

As the feature is opt-in, it should be possible to achieve this.

We will still continue to work on the feature during the 6.5 cycle but without the pressure involved in aiming for it to be included in the release. This will give contributors more breathing room to have the opportunity to receive feedback and refine the implementation.

Do we agree that, given the issues outlined above, it would be premature to target this for 6.5 and we should look to refine the feature prior to inclusion in a major release?

[scruffian]

Do we agree that, given the issues outlined above, it would be premature to target this for 6.5 and we should look to refine the feature prior to inclusion in a major release?

Absolutely

[draganescu]

we should look to refine the feature prior to inclusion in a major release?

Yes!

[annezazu]

Moving this to punted to 6.6 due to the feedback and discussion here. Thanks for the clear communication. Noted in the 6.5 release leads channel for good measure.

[getdave]

Noting here that I think it will be very difficult to merge this PR and target this PR at the Gutenberg Plugin only (i.e. keep the change in the Plugin and not allow it into a release).

Why? Because then we'd be maintaining two versions of the block.

1. Plugin version - different JS, PHP and CSS. Possibly branching.
2. Core version - some standard version without the above changes.

This is branching and is going to introduce more maintenance overhead into an already complex block.

Instead I suggest we investigate whether it's possible to place it behind a flag. That way we can ship the same code to Plugin and Core and it's clear where the branching logic occurs.

[paaljoachim]

Feedback from a client in relation to the hamburger/overlay menu as it is today.
Default overlay menu as seen at: https://www.permakultur.no/ when Justify Items right has been selected for the Nav.

Mobile.menu.2024.mp4

Items are crammed into the right side. Needs padding. Align left - center - right.
Top item and sub levels are not clear. Needs more clarity in relation to top item - sub levels 1 - sub levels 2 etc.
(Changing to justify items center gave a better grouping.)
The client actually suggested to have a drop down of sub level items inside the overlay.

Btw going to the site I changed Justify items right to Justify items center as it looked a lot nicer.

EDIT:
I forgot to mention that I turned off the CSS I had added which added padding on the right side of the menu. The top level with sub levels did not look any nicer, but atleast it added some space on the right side.

EDIT 2: Padding right existed on another Full Site Editing web site using the default theme Twenty Twenty Four.

So the main point goes back into having top level with sub levels items easier to notice.

[MaggieCabrera]

Btw going to the site I changed Justify items right to Justify items center as it looked a lot nicer.

The lack of padding is probably a theme issue. You need to add a global horizontal padding for it (and if it's 0, make sure it's not a unitless zero)

[scruffian]

I've been thinking more about this and I think we should explore what it would take to allow a link/button to open a template part in an overlay, as a first step.

[colorful-tones]

Hi folks,
We are only one week away from the Beta 1 cut-off date for WordPress 6.6. This issue hasn’t seen any movement in a while, so we (the editor triage leads of the 6.6 release) have decided to remove it from the WordPress 6.6 Editor Tasks project board.