From 71ef9849d3ef250fdf895cc6fd0e36c788152185 Mon Sep 17 00:00:00 2001 From: Dave Smith Date: Mon, 24 May 2021 10:11:16 +0100 Subject: [PATCH] Augment and improve Nav Editor (and block) documentation (#31891) * Document different editor save and render modes * Add code references and correct grammar * Tidy unrequired sentances * Document menu item to block attribute mapping * Bring mappings adjacent to each other. Improve documenting inconsistencies. * Add helpful links * Quick ref to the block * Seperate out the colophon --- packages/edit-navigation/README.md | 104 +++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) diff --git a/packages/edit-navigation/README.md b/packages/edit-navigation/README.md index 08afd5dae7a81..1ee150967f869 100644 --- a/packages/edit-navigation/README.md +++ b/packages/edit-navigation/README.md @@ -20,6 +20,103 @@ import blockEditorSettings from './block-editor-settings'; initialize( '#navigation-editor-root', blockEditorSettings ); ``` +## Purpose + +By default, the Navigation Editor screen allows users to create and edit complex navigations using a block-based UI. The aim is to supercede [the current Menus screen](https://codex.wordpress.org/WordPress_Menu_User_Guide) by providing a superior experience whilst retaining backwards compatibility. + +The editing experience is provided as a block editor wrapper around the core functionality of the **Navigation _block_**. Features of the block are disabled/enhanced as necessary to provide an experience appropriate to editing a navigation outside of a Full Site Editing context. + +## Modes + +The Navigation Editor has two "modes" for _persistence_ ("saving" navigations) and _rendering_: + +1. **Default** - navigations are saved to the _existing_ (post type powered) Menus system and rendered using standard Walker classes. +2. **Block-based** (opt _in_) - navigations continue to be _saved_ using the existing post type system, but non-link blocks are saved (see technical implementation) and _rendered_ as blocks to provide access to the full power of the Navigation block (with some tradeoffs in terms of backwards compatibility). + +### Default Mode + +In this mode, navigations created in the Navigation Editor are stored using the _existing Menu post type_ (`nav_menu_item`) system. As this method matches that used in the _existing_ Menus screen, there is a smooth upgrade path to using new Navigation Editor screen to edit navigations. + +Moreover, when the navigation is rendered on the front of the site the system continues to use [the classic Navigation "Walker" class](https://developer.wordpress.org/reference/classes/walker_nav_menu/), thereby ensuring the HTML markup remains the same when using a classic Theme. + +### Block-based Mode + +If desired, themes are able to opt into _rendering_ complete block-based menus using the Navigation Editor. This allows for arbitrarily complex navigation block structures to be used in an existing theme whilst still ensuring the navigation data is still _saved_ to the existing (post type powered) Menus system. + +Themes can opt into this behaviour by declaring: + +```php +add_theme_support( 'block-nav-menus' ); +``` + +This unlocks significant additional capabilities in the Navigation Editor. For example, by default, [the Navigation Editor screen only allows _link_ (`core/navigation-link`) blocks to be inserted into a navigation](https://github.com/WordPress/gutenberg/blob/7fcd57c9a62c232899e287f6d96416477d810d5e/packages/edit-navigation/src/filters/disable-inserting-non-navigation-blocks.js). When a theme opts into `block-nav-menus` however, users are able to add non-link blocks to a navigation using the Navigation Editor screen, including: + +- `core/navigation-link`. +- `core/social`. +- `core/search`. + +#### Technical Implementation details + +By default, `core/navigation-link` items are serialized and persisted as `nav_menu_item` posts. No serialized block HTML is stored for these standard link blocks. + +_Non_-link navigation items however, are [persisted as `nav_menu_items` with a special `type` of `block`](https://github.com/WordPress/gutenberg/blob/7fcd57c9a62c232899e287f6d96416477d810d5e/packages/edit-navigation/src/store/utils.js#L159-L166). These items have an [_additional_ `content` field which is used to store the serialized block markup](https://github.com/WordPress/gutenberg/blob/7fcd57c9a62c232899e287f6d96416477d810d5e/lib/navigation.php#L71-L101). + +When rendered on the front-end, the blocks are [`parse`d from the `content` field](https://github.com/WordPress/gutenberg/blob/7fcd57c9a62c232899e287f6d96416477d810d5e/lib/navigation.php#L191-L203) and [rendered as blocks](https://github.com/WordPress/gutenberg/blob/7fcd57c9a62c232899e287f6d96416477d810d5e/lib/navigation.php#L103-L135). + +If the user switches to a theme that does not support block menus, or disables this functionality, non-link blocks are no longer rendered on the frontend. Care is taken, however, to ensure that users can still see their data on the existing Menus screen. + +## Block to Menu Item mapping + +The Navigation Editor needs to be able to map navigation items in two directions: + +1. `nav_menu_item`s to Blocks - when displaying an existing navigation. +2. Blocks to `nav_menu_item`s - when _saving_ an navigation being editing in the Navigation screen. + +The Navigation Editor has two dedicated methods for handling mapping between these two expressions of the data: + +- [`menuItemToBlockAttributes()`](https://github.com/WordPress/gutenberg/blob/7fcd57c9a62c232899e287f6d96416477d810d5e/packages/edit-navigation/src/store/utils.js#L261-L313). +- [`blockAttributestoMenuItem()`](https://github.com/WordPress/gutenberg/blob/7fcd57c9a62c232899e287f6d96416477d810d5e/packages/edit-navigation/src/store/utils.js#L184-L253) + +To understand these fully, one must appreciate that WordPress maps raw `nav_menu_item` posts to [Menu item _objects_](https://core.trac.wordpress.org/browser/tags/5.7.1/src/wp-includes/nav-menu.php#L786). These have various properties which map as follows: + +| Menu Item object property | Equivalent Block Attribute | Description | +| :------------------------ | :----------------------------------------------------: | :-------------------------------------------------------------------------------------------------------: | +| `ID` | Not mapped. | The term_id if the menu item represents a taxonomy term. | +| `attr_title` | `title` | The title attribute of the link element for this menu item. | +| `classes` | `classNames` | The array of class attribute values for the link element of this menu item. | +| `db_id` | Not mapped. | The DB ID of this item as a nav_menu_item object, if it exists (0 if it doesn't exist). | +| `description` | `description` | The description of this menu item. | +| `menu_item_parent` | Not mapped.[1](#menu_item_menu_item_parent) | The DB ID of the nav_menu_item that is this item's menu parent, if any. 0 otherwise. | +| `object` | `type` | The type of object originally represented, such as 'category', 'post', or 'attachment'. | +| `object_id` | `id` | The DB ID of the original object this menu item represents, e.g. ID for posts and term_id for categories. | +| `post_parent` | Not mapped. | The DB ID of the original object's parent object, if any (0 otherwise). | +| `post_title` | Not mapped. | A "no title" label if menu item represents a post that lacks a title. | +| `target` | `opensInNewTab`[2](#menu_item_target) | The target attribute of the link element for this menu item. | +| `title` | `label` | The title of this menu item. | +| `type` | `kind` | The family of objects originally represented, such as 'post_type' or 'taxonomy'. | +| `type_label` | Not mapped. | The singular label used to describe this type of menu item. | +| `url` | `url` | The URL to which this menu item points. | +| `xfn` | `rel` | The XFN relationship expressed in the link of this menu item. | +| `\_invalid` | Not mapped. | Whether the menu item represents an object that no longer exists. | + +- [1] - the parent -> child relationship is expressed in block via the `innerBlocks` attribute and is therefore not required as a explicit block attribute. +- [2] - applies only if the value of the `target` field is `_blank`. + +### Inconsistencies + +#### Mapping + +For historical reasons, the following properties display some inconsistency in their mapping from Menu Item Object to Block attribute: + +- `type` -> `kind` - the family of objects is stored as `kind` on the block and so must be mapped accordingly. +- `object` -> `type` - the type of object is stored as `type` on the block and so must be mapped accordingly. +- `object_id` -> `id` - the block stores a reference to the original object's ID as the `id` _attribute_. This should not be confused with the block's `clientId` which is unrelated. +- `attr_title` -> `title` - the HTML `title` attribute is stored as `title` on the block and so must be mapped accordingly. + +#### Object Types + +- Menu Item objects which represent "Tags" are stored in WordPress as `post_tag` but the block expects their `type` attribute to be `tag` (omiting the `post_` suffix). This inconsistency is accounted for in [the mapping utilities methods](https://github.com/WordPress/gutenberg/blob/7fcd57c9a62c232899e287f6d96416477d810d5e/packages/edit-navigation/src/store/utils.js#L279-L281). + ## Hooks `useMenuItems` and `useNavigationBlock` hooks are the central part of this package. They bridge the gap between the API and the block editor interface: @@ -59,6 +156,13 @@ return ( ); ``` +## Glossary + +- **Link block** - the basic `core/navigation-link` block which is the standard block used to add links within navigations. +- **Navigation block** - the root `core/navigation` block which can be used both with the Navigation Editor and outside (eg: Post / Site Editor). +- **Navigation editor / screen** - the new screen provided by Gutenberg to allow the user to edit navigations using a block-based UI. +- **Menus screen** - the current/existing [interface/screen for managing Menus](https://codex.wordpress.org/WordPress_Menu_User_Guide) in WordPress WPAdmin. + _This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for ES2015+ such as IE browsers then using [core-js](https://github.com/zloirock/core-js) will add polyfills for these methods._

Code is Poetry.