From 10ffb7d1f37a2342d4c50beb0c5fe35a81627d4e Mon Sep 17 00:00:00 2001 From: ntsekouras Date: Tue, 15 Feb 2022 11:01:06 +0200 Subject: [PATCH 1/3] [Documentation]: Add more info about contextual patterns and pattern transformations --- .../block-api/block-patterns.md | 64 +++++++++++++------ 1 file changed, 44 insertions(+), 20 deletions(-) diff --git a/docs/reference-guides/block-api/block-patterns.md b/docs/reference-guides/block-api/block-patterns.md index 0f09711d766521..f58d843d9e2f63 100644 --- a/docs/reference-guides/block-api/block-patterns.md +++ b/docs/reference-guides/block-api/block-patterns.md @@ -14,7 +14,7 @@ In this Document: The editor comes with several core block patterns. Theme and plugin authors can register additional custom block patterns using the `register_block_pattern` helper function. -The `register_block_pattern` helper function receives two arguments. +The `register_block_pattern` helper function receives two arguments. - `title`: A machine-readable title with a naming convention of `namespace/title`. - `properties`: An array describing properties of the pattern. @@ -26,7 +26,7 @@ The properties available for block patterns are: - `categories` (optional): An array of registered pattern categories used to group block patterns. Block patterns can be shown on multiple categories. A category must be registered separately in order to be used here. - `keywords` (optional): An array of aliases or keywords that help users discover the pattern while searching. - `viewportWidth` (optional): An integer specifying the intended width of the pattern to allow for a scaled preview of the pattern in the inserter. -- `blockTypes` (optional): An array of block types that the pattern is intended to be used with. +- `blockTypes` (optional): An array of block types that the pattern is intended to be used with. Each value needs to be the declared block's `name`. This is used for finding proper matches in the patterns transformation mechanism. In addition this is used by `__experimentalBlockPatternSetup` component which displays patterns to choose from in some blocks, like `Query Loop` block. The following code sample registers a block pattern named 'my-plugin/my-awesome-pattern': @@ -38,10 +38,10 @@ register_block_pattern( 'description' => _x( 'Two horizontal buttons, the left button is filled in, and the right button is outlined.', 'Block pattern description', 'my-plugin' ), 'content' => "\n
\n
" . esc_html__( 'Button One', 'my-plugin' ) . "
\n\n\n\n
" . esc_html__( 'Button Two', 'my-plugin' ) . "
\n
\n", ) -); +); ``` -_Note:_ +_Note:_ `register_block_pattern()` should be called from a handler attached to the init hook. @@ -49,7 +49,7 @@ _Note:_ function my_plugin_register_my_patterns() { register_block_pattern( ... ); } - + add_action( 'init', 'my_plugin_register_my_patterns' ); ``` @@ -57,7 +57,7 @@ add_action( 'init', 'my_plugin_register_my_patterns' ); ### unregister_block_pattern -The `unregister_block_pattern` helper function allows for a previously registered block pattern to be unregistered from a theme or plugin and receives one argument. +The `unregister_block_pattern` helper function allows for a previously registered block pattern to be unregistered from a theme or plugin and receives one argument. - `title`: The name of the block pattern to be unregistered. The following code sample unregisters the block pattern named 'my-plugin/my-awesome-pattern': @@ -66,7 +66,7 @@ The following code sample unregisters the block pattern named 'my-plugin/my-awes unregister_block_pattern( 'my-plugin/my-awesome-pattern' ); ``` -_Note:_ +_Note:_ `unregister_block_pattern()` should be called from a handler attached to the init hook. @@ -74,7 +74,7 @@ _Note:_ function my_plugin_unregister_my_patterns() { unregister_block_pattern( ... ); } - + add_action( 'init', 'my_plugin_unregister_my_patterns' ); ``` @@ -84,7 +84,7 @@ Block patterns can be grouped using categories. The block editor comes with bund ### register_block_pattern_category -The `register_block_pattern_category` helper function receives two arguments. +The `register_block_pattern_category` helper function receives two arguments. - `title`: A machine-readable title for the block pattern category. - `properties`: An array describing properties of the pattern category. @@ -101,7 +101,7 @@ register_block_pattern_category( ); ``` -_Note:_ +_Note:_ `register_block_pattern_category()` should be called from a handler attached to the init hook. @@ -109,7 +109,7 @@ _Note:_ function my_plugin_register_my_pattern_categories() { register_block_pattern_category( ... ); } - + add_action( 'init', 'my_plugin_register_my_pattern_categories' ); ``` @@ -117,7 +117,7 @@ add_action( 'init', 'my_plugin_register_my_pattern_categories' ); `unregister_block_pattern_category` allows unregistering a pattern category. -The `unregister_block_pattern_category` helper function allows for a previously registered block pattern category to be unregistered from a theme or plugin and receives one argument. +The `unregister_block_pattern_category` helper function allows for a previously registered block pattern category to be unregistered from a theme or plugin and receives one argument. - `title`: The name of the block pattern category to be unregistered. The following code sample unregisters the category named 'hero': @@ -126,7 +126,7 @@ The following code sample unregisters the category named 'hero': unregister_block_pattern_category( 'hero' ); ``` -_Note:_ +_Note:_ `unregister_block_pattern_category()` should be called from a handler attached to the init hook. @@ -134,14 +134,16 @@ _Note:_ function my_plugin_unregister_my_pattern_categories() { unregister_block_pattern_category( ... ); } - + add_action( 'init', 'my_plugin_unregister_my_pattern_categories' ); ``` -## Block patterns contextual to block types +## Block patterns contextual to block types and pattern transformations It is possible to attach a block pattern to one or more block types. This adds the block pattern as an available transform for that block type. +Currently pattern transformations are available for simple blocks(blocks without inner blocks). In order for a pattern to be suggested, **every selected block must have matched with a pattern's block**. If a suggested pattern has more blocks than the selected blocks, they are added `as are` from the pattern. Every pattern block that matched with a selected block will be transformed. Noting that this doesn't necessarily mean the order of the blocks will be preserved. + For instance: ```php @@ -150,15 +152,37 @@ register_block_pattern( array( 'title' => __( 'Powered by WordPress', 'my-plugin' ), 'blockTypes' => array( 'core/paragraph' ), - 'content' => ' -

Powered by WordPress

- - ', + 'content' => ' +

Powered by WordPress

+ ', + ) +); +``` + +The above code registers a block pattern named 'my-plugin/powered-by-wordpress' and also shows the pattern in the "transform menu" of paragraph blocks. The transformation result will be keeping the paragraph's existing content and also apply the other attributes - in this case the background and text color. + +As mentioned above pattern transformations for simple blocks can also work if we have selected multiple blocks and there are matching contextual patterns to these blocks. Let's see an example of a pattern where two block types are attached. + +```php +register_block_pattern( + 'my-plugin/powered-by-wordpress', + array( + 'title' => __( 'Powered by WordPress', 'my-plugin' ), + 'blockTypes' => array( 'core/paragraph', 'core/heading' ), + 'content' => ' +
+ +

Hi everyone

+ + +

Powered by WordPress

+ +
', ) ); ``` -The above code registers a block pattern named 'my-plugin/powered-by-wordpress' and also shows the pattern in the "transform menu" of paragraph blocks. +In the above example if we select **one of the two** block types, either a paragraph or a heading block, this pattern will be suggested by transforming the selected block using its content and will also add the remaing blocks from the pattern. If on the other hand we multi select one paragraph and one heading block, both blocks will be transformed. Blocks can also use these contextual block patterns in other places. For instance, when inserting a new Query Loop block, the user is provided with a list of all patterns attached to the block. From cd0d1740548ab63437889d907e7e950dfc554dd0 Mon Sep 17 00:00:00 2001 From: ntsekouras Date: Tue, 15 Feb 2022 15:17:06 +0200 Subject: [PATCH 2/3] address feedback --- docs/reference-guides/block-api/block-patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference-guides/block-api/block-patterns.md b/docs/reference-guides/block-api/block-patterns.md index f58d843d9e2f63..bc29ce3cb933ea 100644 --- a/docs/reference-guides/block-api/block-patterns.md +++ b/docs/reference-guides/block-api/block-patterns.md @@ -26,7 +26,7 @@ The properties available for block patterns are: - `categories` (optional): An array of registered pattern categories used to group block patterns. Block patterns can be shown on multiple categories. A category must be registered separately in order to be used here. - `keywords` (optional): An array of aliases or keywords that help users discover the pattern while searching. - `viewportWidth` (optional): An integer specifying the intended width of the pattern to allow for a scaled preview of the pattern in the inserter. -- `blockTypes` (optional): An array of block types that the pattern is intended to be used with. Each value needs to be the declared block's `name`. This is used for finding proper matches in the patterns transformation mechanism. In addition this is used by `__experimentalBlockPatternSetup` component which displays patterns to choose from in some blocks, like `Query Loop` block. +- `blockTypes` (optional): An array of block types that the pattern is intended to be used with. Each value needs to be the declared block's `name`. The following code sample registers a block pattern named 'my-plugin/my-awesome-pattern': From 84b3d46539d11bd94db4d8f0f1b40b2c52e54d68 Mon Sep 17 00:00:00 2001 From: Nik Tsekouras Date: Tue, 15 Feb 2022 15:17:56 +0200 Subject: [PATCH 3/3] Update docs/reference-guides/block-api/block-patterns.md Co-authored-by: Riad Benguella --- docs/reference-guides/block-api/block-patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference-guides/block-api/block-patterns.md b/docs/reference-guides/block-api/block-patterns.md index bc29ce3cb933ea..0c8eecb0b5d0df 100644 --- a/docs/reference-guides/block-api/block-patterns.md +++ b/docs/reference-guides/block-api/block-patterns.md @@ -142,7 +142,7 @@ add_action( 'init', 'my_plugin_unregister_my_pattern_categories' ); It is possible to attach a block pattern to one or more block types. This adds the block pattern as an available transform for that block type. -Currently pattern transformations are available for simple blocks(blocks without inner blocks). In order for a pattern to be suggested, **every selected block must have matched with a pattern's block**. If a suggested pattern has more blocks than the selected blocks, they are added `as are` from the pattern. Every pattern block that matched with a selected block will be transformed. Noting that this doesn't necessarily mean the order of the blocks will be preserved. +Currently these transformations are available only to simple blocks (blocks without inner blocks). In order for a pattern to be suggested, **every selected block must be present in the block pattern**. For instance: