Skip to content

Commit

Permalink
Clarification for parent and ancestor hierarchical relationships (#…
Browse files Browse the repository at this point in the history
…53855)

* Clarify parent and ancestor usage

* Another pass at refining phrasing for parent/ancestor
  • Loading branch information
colorful-tones authored Aug 24, 2023
1 parent 306a4a9 commit bc94b20
Showing 1 changed file with 19 additions and 6 deletions.
25 changes: 19 additions & 6 deletions docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,13 +155,20 @@ add_action( 'init', function() {
} );
```

## Child InnerBlocks: Parent and Ancestors
## Using Parent and Ancestor Relationships in Blocks

A common pattern for using InnerBlocks is to create a custom block that will be included only in the InnerBlocks.
A common pattern for using InnerBlocks is to create a custom block that will be only be available if its parent block is inserted. This allows builders to establish a relationship between blocks, while limiting a nested block's discoverability. Currently, there are two relationships builders can use: `parent` and `ancestor`. The differences are:

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).
- If you assign a `parent` then you’re stating that the nested block can only be used and inserted as a __direct descendant of the parent__.
- If you assign an `ancestor` then you’re stating that the nested block can only be used and inserted as a __descendent of the parent__.

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.
The key difference between `parent` and `ancestor` is `parent` has finer specificity, while an `ancestor` has greater flexibility in its nested hierarchy.

### Defining Parent Block Relationship

An example of this is the Column block, which is assigned the `parent` block setting. This allows the Column block to only be available as a nested direct descendant in its parent Columns block. Otherwise, the Column block will not be available as an option within the block inserter. See [Column code for reference](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-library/src/column).

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

```json
{
Expand All @@ -172,7 +179,13 @@ When defining a child block, use the `parent` block setting to define which bloc
}
```

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).
### Defining Ancestor Block Relationship

An example of this is the Comment Author Name block, which is assigned the `ancestor` block setting. This allows the Comment Author Name block to only be available as a nested descendant in its ancestral Comment Template block. Otherwise, the Comment Author Name block will not be available as an option within the block inserter. See [Comment Author Name code for reference](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-library/src/comment-author-name).

The `ancestor` relationship allows the Comment Author Name block to be anywhere in the hierarchical tree, and not _just_ a direct child of the parent Comment Template block, while still limiting its availability within the block inserter to only be visible an an option to insert if the Comment Template block is available.

When defining a descendent block, use the `ancestor` block setting. This prevents the nested block from showing in the inserter outside of the InnerBlock it is defined for.

```json
{
Expand All @@ -183,7 +196,7 @@ Another example is using the `ancestors` block setting to define a block that mu
}
```

## Using a react hook
## Using a React Hook

You can use a react hook called `useInnerBlocksProps` instead of the `InnerBlocks` component. This hook allows you to take more control over the markup of inner blocks areas.

Expand Down

0 comments on commit bc94b20

Please sign in to comment.