The new Navigation block

WordPress 5.9 sees the introduction of a Navigation block which allows users to create, manage, and reuse menus built with various blocks from page links to site logos and more.

For full information on using the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. please see the Navigation block support page.

This guide will dive deeper into some of the more technical aspects of the block’s functionality.

Reusing Navigation Menus and separation of concerns 

A key consideration when creating a block based navigation system has been to decouple the presentation of the Navigation block from its data (i.e. the menu items themselves). 

The primary aim of this effort has been to allow for the easy reuse of menus across different Themes, whilst allowing Theme authors to apply different stylistic treatments to their navigation areas. 

The wp_navigation Post

To facilitate this goal, the Navigation block has been designed to save its “items” (i.e. data) to a new wp_navigation custom post type which has been added to WordPress Core.

Changes made to the menu items within the Navigation block are automatically synchronised to an underlying Navigation Post.

In contrast, all presentational attributes remain local to the block instance itself and are not persisted to the Navigation Post.

By using a centralised data source, this “controlled” Navigation block affords reuse of Menus within the site and/or across Themes whilst still allowing for menus to be styled differently as required.

Reusing an existing Menu

To reuse an existing Menu the user may select a menu from the dropdown that appears when clicking on Select menu in the block interface. 

Once selected the items from that menu will be added to the current Navigation block.

An association is also made between the block and the underlying data source via the ref attribute which references the ID of the Navigation Post.

<!-- wp:navigation {"ref":295} /-->

For more information on this feature please see the Navigation block support documentation on selecting an existing menu.

Facilitating Menu reuse across Themes

As a result of the above mechanic, Theme developers can add Navigation blocks to locations within their Theme and style them to suit the visual design. 

When a user activates the Theme they will then be presented with an option to choose from any existing Navigation Menus that they would like to use in those areas.

This affords simple reuse of menus across Themes.

Reusing and converting Classic Menus to block based Menus

Prior to WordPress 5.9, when using classic Themes, Menus were created using the Appearance Menus screen. 

In light of the advent of block-based Menus (and in line with similar previous nomenclature changes), we now refer to such menus as “Classic Menus”.

Thankfully, transitioning to creating a menu using the block editor doesn’t mean recreating existing Classic Menus from scratch. 

Instead the Navigation block affords the ability to copy these menus and transform them into block based equivalents from within the block interface.

To reuse an existing Classic Menu, the user should first insert a new Navigation block. By choosing the Select menu option from the block placeholder they will reveal a dropdown displaying both existing block based and Classic menus. 

Selecting a Classic menu will copy the Menu’s data, convert it to a block based form and then insert that menu data into the Navigation block.

Note that the original Classic Menu is not modified – there is no link between the original data and the new block based representation. Therefore should the user wish to switch back to a classic Theme, their original Classic Menu data will be preserved. 

Handling highly customised Classic Menu items

Plugins (and some Themes) may create customised Menu items for specialised usage. One such example are dynamic menu items which when added to a Classic Menu render multiple menu items on the front of the website.

The need for PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party developers to hook into the conversion process has been recognised and an API is being worked on for a future WordPress release. 

User Permissions

In Classic Menus, only users with the edit_theme_options capability (by default only users with the Admin role) could access the Appearance Menus screen to edit menus.

Similarly when creating menus using the Navigation block, only users with the edit_theme_options capability can create or update Menus.

This is currently achieved by displaying a warning notice to the user within the editor interface if they have insufficient permissions to perform the desired (inter)action.

Note that currently it is still possible for the user to interact with the Navigation block itself. However, any changes to the underlying Navigation MenuNavigation Menu A theme feature introduced with Version 3.0. WordPress includes an easy to use mechanism for giving various control options to get users to click from one place to another on a site. data will not be persisted. 

In future versions of the block, features may be added to make the block interface fully read only based on user permissions.

Backwards compatibility with the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ Plugin

Users of the Gutenberg Plugin may be aware that the Navigation block has existed for some time within the Plugin in a “BetaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process.” form.

For early adopters who have been making use of previous iterations of the block there are two key considerations.

Handling legacy “uncontrolled” blocks

Users should note that previous implementations of the Navigation block saved the “items” to the block itself. This can be described as an “uncontrolled” version of the block, whereby the menu item data is local to the block (i.e. inner blocks) and thus persisted directly to the Post in which it is contained.

As a result of these changes, any Navigation block which contains “uncontrolled” blocks will be automatically converted to a “controlled” version where the menu item data is persisted to a new `wp_navigation` custom post.

No data will be lost in this process and it should be opaque to the user.

Navigation Areas (deprecated)

In the run up to WordPress 5.9 contributors began exploring the concept of Navigation Areas. Users should note that following consultation and testing this effort was abandoned and reverted.

Theme developers should avoid making use of this feature as Navigation Areas are formally deprecated.

An alternative method for automatically transferring menus between Theme locations will be explored as part of a future WordPress release.

---

Props to @annezazu, @isabel_brison, @bph, @bobbingwide, @javiarce and @spacedmonkey for contributions to this post.

#5-9, #dev-notes, #navigation-block