Block Patterns Doc Updates (#31060)

docs/reference-guides/block-api/block-patterns.md

@@ -1,23 +1,33 @@
 # Patterns
 
-Block Patterns are predefined block layouts, ready to insert and tweak.
+Block Patterns are predefined block layouts, available from the patterns tab of the block inserter. Once inserted into content, the blocks are ready for additional or modified content and configuration.
 
-## Block Patterns Registration
+In this Document:
+* [`register_block_pattern`](#register_block_pattern)
+* [`unregister_block_pattern`](#unregister_block_pattern)
+* [`register_block_pattern_category`](#register_block_pattern_category)
+* [`unregister_block_pattern_category`](#unregister_block_pattern_category)
+
+## Block Patterns
 
 ### register_block_pattern
 
-The editor comes with a list of built-in block patterns. Theme and plugin authors can register addition custom block patterns using the `register_block_pattern` function.
+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` function receives the name of the pattern as the first argument and an array describing properties of the pattern as the second argument.
+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.
 
-The properties of the block pattern include:
+The properties available for block patterns are:
 
 -   `title` (required): A human-readable title for the pattern.
--   `content` (required): Raw HTML content for the pattern.
--   `description`: A visually hidden text used to describe the pattern in the inserter. A description is optional but it is strongly encouraged when the title does not fully describe what the pattern does.
--   `categories`: An array of pattern categories used to group block patterns. Block patterns can be shown on multiple categories.
--   `keywords`: An array of aliases or keywords that help users discover the pattern while searching.
--   `viewportWidth`: An integer specifying the width of the pattern in the inserter.
+-   `content` (required): Block HTML Markup for the pattern.
+-   `description` (optional): A visually hidden text used to describe the pattern in the inserter. A description is optional but it is strongly encouraged when the title does not fully describe what the pattern does. The description will help users discover the pattern while searching.
+-   `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.
+
+The following code sample registers a block pattern named 'my-plugin/my-awesome-pattern':
 
 ```php
 register_block_pattern(
@@ -27,48 +37,102 @@ 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'     => "<!-- wp:buttons {\"align\":\"center\"} -->\n<div class=\"wp-block-buttons aligncenter\"><!-- wp:button {\"backgroundColor\":\"very-dark-gray\",\"borderRadius\":0} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-background has-very-dark-gray-background-color no-border-radius\">" . esc_html__( 'Button One', 'my-plugin' ) . "</a></div>\n<!-- /wp:button -->\n\n<!-- wp:button {\"textColor\":\"very-dark-gray\",\"borderRadius\":0,\"className\":\"is-style-outline\"} -->\n<div class=\"wp-block-button is-style-outline\"><a class=\"wp-block-button__link has-text-color has-very-dark-gray-color no-border-radius\">" . esc_html__( 'Button Two', 'my-plugin' ) . "</a></div>\n<!-- /wp:button --></div>\n<!-- /wp:buttons -->",
 	)
-);
+); 
 ```
 
-### unregister_block_pattern
+_Note:_ 
 
-`unregister_block_pattern` allows unregistering a pattern previously registered on the server using `register_block_pattern`.
+`register_block_pattern()` should be called from a handler attached to the init hook.
 
-The function's argument is the registered name of the pattern.
+```php
+function my_plugin_register_my_patterns() {
+  register_block_pattern( ... );
+}
+
+add_action( 'init', 'my_plugin_register_my_patterns' );
+```
 
-The following code sample unregisters the style named 'my-plugin/my-awesome-pattern':
+## Unregistering Block 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. 
+-   `title`: The name of the block pattern to be unregistered.
+
+The following code sample unregisters the block pattern named 'my-plugin/my-awesome-pattern':
 
 ```php
 unregister_block_pattern( 'my-plugin/my-awesome-pattern' );
 ```
 
+_Note:_ 
+
+`unregister_block_pattern()` should be called from a handler attached to the init hook.
+
+```php
+function my_plugin_unregister_my_patterns() {
+  unregister_block_pattern( ... );
+}
+
+add_action( 'init', 'my_plugin_unregister_my_patterns' );
+```
+
 ## Block Pattern Categories
 
-Block patterns can be grouped using categories. The block editor comes with bundled categories you can use on your custom block patterns. You can also register your own pattern categories.
+Block patterns can be grouped using categories. The block editor comes with bundled categories you can use on your custom block patterns. You can also register your own block pattern categories.
 
 ### register_block_pattern_category
 
-The `register_block_pattern_category` function receives the name of the category as the first argument and an array describing properties of the category as the second argument.
+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.
 
 The properties of the pattern categories include:
 
 -   `label` (required): A human-readable label for the pattern category.
 
+The following code sample registers the category named 'hero':
+
 ```php
 register_block_pattern_category(
 	'hero',
 	array( 'label' => __( 'Hero', 'my-plugin' ) )
 );
 ```
 
+_Note:_ 
+
+`register_block_pattern_category()` should be called from a handler attached to the init hook.
+
+```php
+function my_plugin_register_my_pattern_categories() {
+  register_block_pattern_category( ... );
+}
+
+add_action( 'init', 'my_plugin_register_my_pattern_categories' );
+```
+
 ### unregister_block_pattern_category
 
 `unregister_block_pattern_category` allows unregistering a pattern category.
 
-The function's argument is the name of the pattern category to unregister.
+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':
 
 ```php
 unregister_block_pattern_category( 'hero' );
 ```
+
+_Note:_ 
+
+`unregister_block_pattern_category()` should be called from a handler attached to the init hook.
+
+```php
+function my_plugin_unregister_my_pattern_categories() {
+  unregister_block_pattern_category( ... );
+}
+
+add_action( 'init', 'my_plugin_unregister_my_pattern_categories' );
+```