Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Correct inconsistencies and errors in Nav Editor docs #34682

Merged
merged 10 commits into from
Sep 21, 2021
Merged

Correct inconsistencies and errors in Nav Editor docs #34682

Changes from 4 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
7ffb30a
Explain that the entire navigatoin is rendered as blocks not just the…
getdave Sep 9, 2021
3112ae2
Update to increase clarity of sentance
getdave Sep 9, 2021
ef3694a
Add notes about backwards compatibility
getdave Sep 9, 2021
cad9d12
Improve backwards compat docs
getdave Sep 9, 2021
da01ce8
Correct things to document that block-based links are still rendered …
getdave Sep 9, 2021
bbf91db
Updated glossary with block-based link info
getdave Sep 9, 2021
a56b874
Add technical reference to where Nav block rendering happens
getdave Sep 16, 2021
d6bdb6e
Disambiguate "links"
getdave Sep 21, 2021
d1d5f35
Use "Classic" terminology instead of "Default"
getdave Sep 21, 2021
7201eee
Ditch technical implementation details
getdave Sep 21, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 13 additions & 3 deletions packages/edit-navigation/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,9 @@ The editing experience is provided as a block editor wrapper around the core fun
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).
2. **Block-based** (opt _in_) - navigations continue to be _saved_ using the existing post type system, but:
- non-link blocks (anything that is not `core/navigation-link`) are saved as _blocks_ (see [technical implementation](#technical-implementation-details)).
- the navigation is _rendered_ using the `core/navigation` block (as opposed to Walker) to provide access to the full power of blocks (with some tradeoffs in terms of backwards compatibility).

### Default Mode

Expand All @@ -41,7 +43,7 @@ Moreover, when the navigation is rendered on the front of the site the system co

### Block-based Mode

**Important**: block-based mode has been temporarily ***disabled*** until it becomes stable. So, if a theme declares support for the `block-nav-menus` feature it will not affect the frontend.
**Important**: block-based mode has been temporarily **_disabled_** until it becomes stable. So, if a theme declares support for the `block-nav-menus` feature it will not affect the frontend.

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.

Expand All @@ -59,12 +61,20 @@ This unlocks significant additional capabilities in the Navigation Editor. For e

#### 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.
By default, `core/navigation-link` ("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).

## Backwards compatibility

By design the underlying systems of the Nav Editor screen should be largely backwards compatible with the existing Menus screen. Therefore any navigations created or edited using the new Navigation Editor screen should continue to work in the existing classic Menus screen.

Currently, the only exception to this would be any custom functionality added (by Plugins or otherwise) to the existing Menus screen would not be replicated in the new Navigation Editor screen. In this scenario there might be danger of some data loss.

### Downgrading from block-based to classic Themes

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
Expand Down