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

Add/block breadcrumb component readme #24827

Merged
merged 7 commits into from
Aug 28, 2020
Merged

Add/block breadcrumb component readme #24827

Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
3053de0
Add block breadcrumb component readme
JustinyAhin Aug 26, 2020
2dc1577
Update block breadcrumb component readme
JustinyAhin Aug 26, 2020
41193f4
Update block breadcrumb component readme
JustinyAhin Aug 26, 2020
e59417a
Update block breadcrumb component README
JustinyAhin Aug 27, 2020
bfba081
Add link to BlockEditorProvider README
JustinyAhin Aug 27, 2020
cfa484e
Update JSX example
JustinyAhin Aug 28, 2020
f43c7a9
Update JSX code example
JustinyAhin Aug 28, 2020
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
26 changes: 26 additions & 0 deletions packages/block-editor/src/components/block-breadcrumb/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Block Breadcrumb

The block breadcrumb trail displays the hierarchy of the current block selection as a breadcrumb. It also allows, using this hierarchy, to navigate to the parent elements of the current block selection. It is located at the very bottom of the editor interface.

![Button block breadcrumb](https://make.wordpress.org/core/files/2020/08/gutenberg-button-block-breadcrumb.png)

![Image in column block breadcrumb](https://make.wordpress.org/core/files/2020/08/gutenberg-image-in-column-block-breadcrumb.png)

## Table of contents

1. [Development guidelines](#development-guidelines)


## Development guidelines

### Usage

Renders a block breadcrumb with default style.

```jsx
import { BlockBreadcrumb } from '@wordpress/block-editor';

<div className="add-your-class-name">
<BlockBreadcrumb />
</div>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is bad code, it needs to be wrapper inside a function (component), we can't just use JSX top level like that.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

something like
const MyBreadcrumb = () => <BlockBreadcrumb />; I guess.

I think I can also remove the div.

```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think most components in the block-editor package including this one need to be embedded in the React tree under BlockEditorProvider. I wonder if it's worth mentioning in the READMEs of the different components or not.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I think we should include in each example, because a developer may approach any page without seeing others, the more we can do to make the examples "just work" when copy-and-paste the better.

The example could be just updated to, if you want to include the <div> it'd be fine too, but probably not necessary.

import { 
  BlockBreadcrumb,
  BlockEditorProvider  } from '@wordpress/block-editor';

<BlockEditorProvider>
    <BlockBreadcrumb/>
</BlockEditorProvider>

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's not sufficient though because using BlockEditorProvider is more complex than that. Maybe we can link to its README?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, just updated the example with BlockEditorProvider.
Is there anything thing else that should be added?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add something in a "Related components" section?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I personally think we should revert to your original code example but add a sentence like that somewhere:

Block Editor components are components that can be used to compose the UI of your block editor. Thus, they can only be used under a `BlockEditorProvider` in the components tree.

and link the word BlockEditorProvider to its README.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Works for me. The BlockEditorProvider readme has a complete example 👍