Augment and improve Nav Editor (and block) documentation #31891
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
getdave
added
[Feature] Navigation Screen
[Type] Developer Documentation
getdave
changed the title
|
Size Change: 0 B Total Size: 1.62 MB ℹ️ View Unchanged
|
getdave
requested review from
adamziel,
draganescu,
kevin940726,
noisysocks,
talldan and
tellthemachines
as code owners
|
@Mamaduka Is there any chance you'd be able to help document the If not then should we consider removing this section? Does it provide any value? |
|
@noisysocks I'd really appreciate a review of the part regarding the two "Modes". I noticed you wrote the original functionality that allowed for block based rendering/saving. |
|
@talldan @gwwar @draganescu If you have time I'd really appreciate your experienced 👀 on this one. |
|
I was just looking into that section. 😄 #23033 removed currently documented hooks. I think we can document I will work on the doc update tomorrow. |
gwwar
approved these changes
May 17, 2021
|
|
||
| #### 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). |
There was a problem hiding this comment.
As an aside, I think we can still change this to prefer post_tag before the navigation block is finalized. (We'd still need to account for older data that has tag though).
|
|
||
| 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). |
There was a problem hiding this comment.
Non-blocking note: I think this is useful to walk through, along with the table below, but I also wanted to note that docs here are pretty likely to get out of sync over time. Probably not worth automating, until things are more finalized for navigation but just something to keep in mind 🤔
There was a problem hiding this comment.
One other thing that might help might be some sort of diagram/table of the backing stores, rather than pointing to the conversion code.
getdave
force-pushed
the
update/augment-nav-editor-docs
branch
from
39d74ed to
b7441f4
Compare
@Mamaduka @talldan I've left this a few days to see if you or anyone else had any additional feedback or points you wanted to include. I'll leave it over the weekend and Monday. If not I'll go ahead merge and additional updates can be done in follow ups. |
|
Sounds good. I'll update hook documentation in follow-up PR. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Since the
READMEfor the Navigation Editor was created it has evolved significantly.This an effort to provide high level documentation of its behaviour (and the decisions that have guided us), in the hope that we can transfer the project's domain knowledge into written form (and out of contributors' heads!).
If there is any information missing that you feel ought to be documented here please say and I will investigate and write it.
How has this been tested?
Reading words. Comparing against implementation.
Screenshots
Types of changes
New feature (non-breaking change which adds functionality)
Checklist:
*.native.jsfiles for terms that need renaming or removal).