From 10bf692288511d47b9ec5c597033051a15dbfafd Mon Sep 17 00:00:00 2001 From: Bernie Reiter Date: Mon, 31 Jul 2023 16:33:50 +0200 Subject: [PATCH 1/7] Document possible values of relative_position argument --- lib/experimental/auto-inserting-blocks.php | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/experimental/auto-inserting-blocks.php b/lib/experimental/auto-inserting-blocks.php index 9df94fcbfcd8fb..f01638065a3560 100644 --- a/lib/experimental/auto-inserting-blocks.php +++ b/lib/experimental/auto-inserting-blocks.php @@ -10,6 +10,7 @@ * * @param array $inserted_block The block to insert. * @param string $relative_position The position relative to the given block. + * Can be 'before', 'after', 'first_child', or 'last_child'. * @param string $anchor_block The block to insert relative to. * @return callable A function that accepts a block's content and returns the content with the inserted block. */ From 10151280ad7ee8729c3045e5212f67c85bef090c Mon Sep 17 00:00:00 2001 From: Bernie Reiter Date: Mon, 31 Jul 2023 16:38:37 +0200 Subject: [PATCH 2/7] Rename anchor_block param to anchor_block_type, document better --- lib/experimental/auto-inserting-blocks.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/experimental/auto-inserting-blocks.php b/lib/experimental/auto-inserting-blocks.php index f01638065a3560..f9da5d75f9d606 100644 --- a/lib/experimental/auto-inserting-blocks.php +++ b/lib/experimental/auto-inserting-blocks.php @@ -11,7 +11,7 @@ * @param array $inserted_block The block to insert. * @param string $relative_position The position relative to the given block. * Can be 'before', 'after', 'first_child', or 'last_child'. - * @param string $anchor_block The block to insert relative to. + * @param string $anchor_block_type The auto-inserted block will be inserted next to instances of this block type. * @return callable A function that accepts a block's content and returns the content with the inserted block. */ function gutenberg_auto_insert_block( $inserted_block, $relative_position, $anchor_block ) { From 4c312b8037b4e575fd32318926b713d9693568e6 Mon Sep 17 00:00:00 2001 From: Bernie Reiter Date: Tue, 1 Aug 2023 10:05:13 +0200 Subject: [PATCH 3/7] More explanatory PHPDoc for gutenberg_auto_insert_block; mention mutating --- lib/experimental/auto-inserting-blocks.php | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/lib/experimental/auto-inserting-blocks.php b/lib/experimental/auto-inserting-blocks.php index f9da5d75f9d606..4cc8de715535ce 100644 --- a/lib/experimental/auto-inserting-blocks.php +++ b/lib/experimental/auto-inserting-blocks.php @@ -6,7 +6,14 @@ */ /** - * Return a function that auto-inserts blocks relative to a given block. + * Return a function that auto-inserts a block next to a given "anchor" block. + * + * The auto-inserted block can be inserted before or after the anchor block, + * or as the first or last child of the anchor block. + * + * Note that the returned function mutates the auto-inserted block's designated + * parent block by inserting into the parent's `innerBlocks` array, and by + * updating the parent's `innerContent` array accordingly. * * @param array $inserted_block The block to insert. * @param string $relative_position The position relative to the given block. From 9c58e8710a7a9bcde02d2c285b4e5683b15acafe Mon Sep 17 00:00:00 2001 From: Bernie Reiter Date: Tue, 1 Aug 2023 10:15:45 +0200 Subject: [PATCH 4/7] Mention leveraging serialization depth-first traversal in PHPDoc. --- lib/experimental/auto-inserting-blocks.php | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/lib/experimental/auto-inserting-blocks.php b/lib/experimental/auto-inserting-blocks.php index 4cc8de715535ce..2ed2c8a8a485d3 100644 --- a/lib/experimental/auto-inserting-blocks.php +++ b/lib/experimental/auto-inserting-blocks.php @@ -152,7 +152,9 @@ function gutenberg_register_auto_inserted_block( $inserted_block, $position, $an * * By parsing a block template's content and then reserializing it * via `gutenberg_serialize_blocks()`, we are able to run filters - * on the parsed blocks. + * on the parsed blocks. This allows us to modify blocks during + * depth-first traversal already provided by the serialization process, + * rather than having to do so in a separate pass. * * @param WP_Block_Template[] $query_result Array of found block templates. * @return WP_Block_Template[] Updated array of found block templates. @@ -175,7 +177,9 @@ function gutenberg_parse_and_serialize_block_templates( $query_result ) { * * By parsing a block template's content and then reserializing it * via `gutenberg_serialize_blocks()`, we are able to run filters - * on the parsed blocks. + * on the parsed blocks. This allows us to modify blocks during + * depth-first traversal already provided by the serialization process, + * rather than having to do so in a separate pass. * * @param WP_Block_Template|null $block_template The found block template, or null if there is none. */ From 2446e3d9237b5c704453c5fa083fcb83026c9d1a Mon Sep 17 00:00:00 2001 From: Bernie Reiter Date: Tue, 1 Aug 2023 10:22:23 +0200 Subject: [PATCH 5/7] Minor tweak: add '(parsed)' to PHPDoc --- lib/experimental/auto-inserting-blocks.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/experimental/auto-inserting-blocks.php b/lib/experimental/auto-inserting-blocks.php index 2ed2c8a8a485d3..4d7117ff1eaa3a 100644 --- a/lib/experimental/auto-inserting-blocks.php +++ b/lib/experimental/auto-inserting-blocks.php @@ -152,7 +152,7 @@ function gutenberg_register_auto_inserted_block( $inserted_block, $position, $an * * By parsing a block template's content and then reserializing it * via `gutenberg_serialize_blocks()`, we are able to run filters - * on the parsed blocks. This allows us to modify blocks during + * on the parsed blocks. This allows us to modify (parsed) blocks during * depth-first traversal already provided by the serialization process, * rather than having to do so in a separate pass. * @@ -177,7 +177,7 @@ function gutenberg_parse_and_serialize_block_templates( $query_result ) { * * By parsing a block template's content and then reserializing it * via `gutenberg_serialize_blocks()`, we are able to run filters - * on the parsed blocks. This allows us to modify blocks during + * on the parsed blocks. This allows us to modify (parsed) blocks during * depth-first traversal already provided by the serialization process, * rather than having to do so in a separate pass. * From 764db1097b5bd2cc40bc7470953a012be0ec86ad Mon Sep 17 00:00:00 2001 From: Bernie Reiter Date: Tue, 1 Aug 2023 10:29:12 +0200 Subject: [PATCH 6/7] s/anchor_block/anchor_block_type/g --- lib/experimental/auto-inserting-blocks.php | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/lib/experimental/auto-inserting-blocks.php b/lib/experimental/auto-inserting-blocks.php index 4d7117ff1eaa3a..aa8b33fe1e9ef4 100644 --- a/lib/experimental/auto-inserting-blocks.php +++ b/lib/experimental/auto-inserting-blocks.php @@ -21,9 +21,9 @@ * @param string $anchor_block_type The auto-inserted block will be inserted next to instances of this block type. * @return callable A function that accepts a block's content and returns the content with the inserted block. */ -function gutenberg_auto_insert_block( $inserted_block, $relative_position, $anchor_block ) { - return function( $block ) use ( $inserted_block, $relative_position, $anchor_block ) { - if ( $anchor_block === $block['blockName'] ) { +function gutenberg_auto_insert_block( $inserted_block, $relative_position, $anchor_block_type ) { + return function( $block ) use ( $inserted_block, $relative_position, $anchor_block_type ) { + if ( $anchor_block_type === $block['blockName'] ) { if ( 'first_child' === $relative_position ) { array_unshift( $block['innerBlocks'], $inserted_block ); // Since WP_Block::render() iterates over `inner_content` (rather than `inner_blocks`) @@ -40,7 +40,7 @@ function gutenberg_auto_insert_block( $inserted_block, $relative_position, $anch return $block; } - $anchor_block_index = array_search( $anchor_block, array_column( $block['innerBlocks'], 'blockName' ), true ); + $anchor_block_index = array_search( $anchor_block_type, array_column( $block['innerBlocks'], 'blockName' ), true ); if ( false !== $anchor_block_index && ( 'after' === $relative_position || 'before' === $relative_position ) ) { if ( 'after' === $relative_position ) { $anchor_block_index++; @@ -164,8 +164,7 @@ function gutenberg_parse_and_serialize_block_templates( $query_result ) { if ( 'custom' === $block_template->source ) { continue; } - $blocks = parse_blocks( $block_template->content ); - $block_template->content = gutenberg_serialize_blocks( $blocks ); + gutenberg_parse_and_serialize_blocks( $block_template ); } return $query_result; @@ -183,7 +182,7 @@ function gutenberg_parse_and_serialize_block_templates( $query_result ) { * * @param WP_Block_Template|null $block_template The found block template, or null if there is none. */ -function gutenberg_parse_and_serialize_blocks( $block_template ) { +function gutenberg_parse_and_serialize_blocks( &$block_template ) { $blocks = parse_blocks( $block_template->content ); $block_template->content = gutenberg_serialize_blocks( $blocks ); From b36efef0e93473b071e0b58e43b880804a79df29 Mon Sep 17 00:00:00 2001 From: Bernie Reiter Date: Thu, 3 Aug 2023 11:12:14 +0200 Subject: [PATCH 7/7] Undo calling gutenberg_parse_and_serialize_blocks --- lib/experimental/auto-inserting-blocks.php | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/lib/experimental/auto-inserting-blocks.php b/lib/experimental/auto-inserting-blocks.php index aa8b33fe1e9ef4..90f3bdf15e509d 100644 --- a/lib/experimental/auto-inserting-blocks.php +++ b/lib/experimental/auto-inserting-blocks.php @@ -164,7 +164,8 @@ function gutenberg_parse_and_serialize_block_templates( $query_result ) { if ( 'custom' === $block_template->source ) { continue; } - gutenberg_parse_and_serialize_blocks( $block_template ); + $blocks = parse_blocks( $block_template->content ); + $block_template->content = gutenberg_serialize_blocks( $blocks ); } return $query_result; @@ -182,7 +183,7 @@ function gutenberg_parse_and_serialize_block_templates( $query_result ) { * * @param WP_Block_Template|null $block_template The found block template, or null if there is none. */ -function gutenberg_parse_and_serialize_blocks( &$block_template ) { +function gutenberg_parse_and_serialize_blocks( $block_template ) { $blocks = parse_blocks( $block_template->content ); $block_template->content = gutenberg_serialize_blocks( $blocks );