diff --git a/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md b/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md index d1b28f84a651a8..aff5e2852fae7a 100644 --- a/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md +++ b/docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md @@ -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" ], + // ... +} ``` diff --git a/docs/reference-guides/block-api/block-metadata.md b/docs/reference-guides/block-api/block-metadata.md index 801a3f0fa47f66..0e5c26d42af65d 100644 --- a/docs/reference-guides/block-api/block-metadata.md +++ b/docs/reference-guides/block-api/block-metadata.md @@ -215,6 +215,20 @@ An implementation should expect and tolerate unknown categories, providing some Setting `parent` lets a block require that it is only available when nested within the specified blocks. For example, you might want to allow an 'Add to Cart' block to only be available within a 'Product' block. +### Ancestor + +- Type: `string[]` +- Optional +- Localized: No +- Property: `ancestor` +- Since: `WordPress 6.0.0` + +```json +{ "ancestor": [ "my-block/product" ] } +``` + +The `ancestor` property makes a block available inside the specified block types at any position of the ancestor block subtree. That allows, for example, to place a ‘Comment Content’ block inside a ‘Column’ block, as long as ‘Column’ is somewhere within a ‘Comment Template’ block. In comparrison to the `parent` property blocks that specify their `ancestor` can be placed anywhere in the subtree whilst blocks with a specified `parent` need to be direct children. + ### Icon - Type: `string`