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.

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

Doc: Add documentation for ancestor property in block metadata #40027

Merged
merged 3 commits into from
Apr 13, 2022
Merged
Changes from 1 commit
Commits
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
Prev Previous commit
Add ancestors example in innerblocks tutorial
luisherranz authored Apr 6, 2022
commit 0921a493c47c499f70eaab7c7c7eb710e19521d1
32 changes: 22 additions & 10 deletions docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md
Original file line number Diff line number Diff line change
@@ -155,18 +155,30 @@ add_action( 'init', function() {
} );
```

## Parent-Child InnerBlocks
## Child InnerBlocks: Parent and Ancestors

A common pattern for using InnerBlocks is to create a custom block that will be included only in the InnerBlocks. An example of this is the Columns block, that creates a single parent block called `columns` and then creates an child block called `column`. The parent block is defined to only allow the child blocks. See [Column code for reference](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-library/src/column).
A common pattern for using InnerBlocks is to create a custom block that will be included only in the InnerBlocks.

An example of this is the Columns block, that creates a single parent block called `columns` and then creates an child block called `column`. The parent block is defined to only allow the child blocks. See [Column code for reference](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-library/src/column).

When defining a child block, use the `parent` block setting to define which block is the parent. This prevents the block showing in the inserter outside of the InnerBlock it is defined for.

```js
export const settings = {
title: __( 'Column' ),
parent: [ 'core/columns' ],
icon,
description: __( 'A single column within a columns block.' ),
//...
};
```json
{
"title": "Column",
"name": "core/column",
"parent": [ "core/columns" ],
// ...
}
```

Another example is using the `ancestors` block setting to define a block that must be present as an ancestor, but it doesn't need to be the direct parent (like with `parent`). This prevents the block from showing in the inserter if the ancestor is not in the tree, but other blocks can be added in between, like a Columns or Group block. See [Comment Author Name code for reference](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-library/src/comment-author-name).

```json
{
"title": "Comment Author Name",
"name": "core/comment-author-name",
"ancestor": [ "core/comment-template" ],
// ...
}
```