Skip to content

Commit

Permalink
Docs: Improve documentation for block pattern properties.
Browse files Browse the repository at this point in the history
Includes:
* Adding the `templateTypes` property to the `WP_Block_Patterns_Registry::register()` DocBlock.
* Adding `@since` notes for the `postTypes` and `templateTypes` properties to:
 * `_register_theme_block_patterns()`
 * `WP_Block_Patterns_Registry::register()`
* Bringing some consistency to the order of properties between:
 * `_register_theme_block_patterns()`
 * `WP_Block_Patterns_Registry::register()`
 * `WP_REST_Block_Patterns_Controller::prepare_item_for_response()`
 * `WP_REST_Block_Patterns_Controller::get_item_schema()`

Follow-up to [52943], [53152], [54263], [55168].

See #56792.

git-svn-id: https://develop.svn.wordpress.org/trunk@55173 602fd350-edb4-49c9-b593-d223f7449a82
  • Loading branch information
SergeyBiryukov committed Feb 1, 2023
1 parent 52e5e06 commit d2f6c41
Show file tree
Hide file tree
Showing 4 changed files with 43 additions and 39 deletions.
6 changes: 4 additions & 2 deletions src/wp-includes/block-patterns.php
Original file line number Diff line number Diff line change
Expand Up @@ -298,14 +298,16 @@ function _register_remote_theme_patterns() {
*
* - Description
* - Viewport Width
* - Inserter (yes/no)
* - Categories (comma-separated values)
* - Keywords (comma-separated values)
* - Block Types (comma-separated values)
* - Post Types (comma-separated values)
* - Template Types (comma-separated values)
* - Inserter (yes/no)
*
* @since 6.0.0
* @since 6.1.0 The `postTypes` property was added.
* @since 6.2.0 The `templateTypes` property was added.
* @access private
*/
function _register_theme_block_patterns() {
Expand All @@ -314,11 +316,11 @@ function _register_theme_block_patterns() {
'slug' => 'Slug',
'description' => 'Description',
'viewportWidth' => 'Viewport Width',
'inserter' => 'Inserter',
'categories' => 'Categories',
'keywords' => 'Keywords',
'blockTypes' => 'Block Types',
'postTypes' => 'Post Types',
'inserter' => 'Inserter',
'templateTypes' => 'Template Types',
);

Expand Down
26 changes: 14 additions & 12 deletions src/wp-includes/class-wp-block-patterns-registry.php
Original file line number Diff line number Diff line change
Expand Up @@ -43,37 +43,39 @@ final class WP_Block_Patterns_Registry {
*
* @since 5.5.0
* @since 5.8.0 Added support for the `blockTypes` property.
* @since 6.1.0 Added support for the `postTypes` property.
* @since 6.2.0 Added support for the `templateTypes` property.
*
* @param string $pattern_name Block pattern name including namespace.
* @param array $pattern_properties {
* List of properties for the block pattern.
*
* @type string $title Required. A human-readable title for the pattern.
* @type string $content Required. Block HTML markup for the pattern.
* @type string $description Optional. Visually hidden text used to describe the pattern in the
* inserter. A description is optional, but is strongly
* @type string $description Optional. Visually hidden text used to describe the pattern
* in the inserter. A description is optional, but is strongly
* encouraged when the title does not fully describe what the
* pattern does. The description will help users discover the
* pattern while searching.
* @type int $viewportWidth Optional. The intended width of the pattern to allow for a scaled
* preview within the pattern inserter.
* @type array $categories Optional. A list 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.
* @type array $categories Optional. A list 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.
* @type array $keywords Optional. A list of aliases or keywords that help users discover
* the pattern while searching.
* @type array $blockTypes Optional. A list of block names including namespace that could use
* the block pattern in certain contexts (placeholder, transforms).
* The block pattern is available in the block editor inserter
* regardless of this list of block names.
* Certain blocks support further specificity besides the block name
* (e.g. for `core/template-part` you can specify areas
* like `core/template-part/header` or `core/template-part/footer`).
* @type array $postTypes An array of post types that the pattern is restricted to be used with.
* The pattern will only be available when editing one of the post types
* passed on the array. For all the other post types not part of the array
* the pattern is not available at all.
* @type array $keywords Optional. A list of aliases or keywords that help users discover the
* pattern while searching.
* @type array $postTypes Optional. An array of post types that the pattern is restricted
* to be used with. The pattern will only be available when editing one
* of the post types passed on the array. For all the other post types
* not part of the array the pattern is not available at all.
* @type array $templateTypes Optional. An array of template types where the pattern fits.
* }
* @return bool True if the pattern was registered with success and false otherwise.
*/
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -165,14 +165,14 @@ public function prepare_item_for_response( $item, $request ) {
$keys = array(
'name' => 'name',
'title' => 'title',
'content' => 'content',
'description' => 'description',
'viewportWidth' => 'viewport_width',
'blockTypes' => 'block_types',
'postTypes' => 'post_types',
'inserter' => 'inserter',
'categories' => 'categories',
'keywords' => 'keywords',
'content' => 'content',
'inserter' => 'inserter',
'blockTypes' => 'block_types',
'postTypes' => 'post_types',
'templateTypes' => 'template_types',
);
$data = array();
Expand Down Expand Up @@ -213,6 +213,12 @@ public function get_item_schema() {
'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ),
),
'content' => array(
'description' => __( 'The pattern content.' ),
'type' => 'string',
'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ),
),
'description' => array(
'description' => __( 'The pattern detailed description.' ),
'type' => 'string',
Expand All @@ -225,15 +231,9 @@ public function get_item_schema() {
'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ),
),
'block_types' => array(
'description' => __( 'Block types that the pattern is intended to be used with.' ),
'type' => 'array',
'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ),
),
'post_types' => array(
'description' => __( 'An array of post types that the pattern is restricted to be used with.' ),
'type' => 'array',
'inserter' => array(
'description' => __( 'Determines whether the pattern is visible in inserter.' ),
'type' => 'boolean',
'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ),
),
Expand All @@ -249,21 +249,21 @@ public function get_item_schema() {
'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ),
),
'template_types' => array(
'description' => __( 'An array of template types where the pattern fits.' ),
'block_types' => array(
'description' => __( 'Block types that the pattern is intended to be used with.' ),
'type' => 'array',
'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ),
),
'content' => array(
'description' => __( 'The pattern content.' ),
'type' => 'string',
'post_types' => array(
'description' => __( 'An array of post types that the pattern is restricted to be used with.' ),
'type' => 'array',
'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ),
),
'inserter' => array(
'description' => __( 'Determines whether the pattern is visible in inserter.' ),
'type' => 'boolean',
'template_types' => array(
'description' => __( 'An array of template types where the pattern fits.' ),
'type' => 'array',
'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ),
),
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -78,9 +78,9 @@ public static function wpSetUpBeforeClass( $factory ) {
'test/one',
array(
'title' => 'Pattern One',
'categories' => array( 'test' ),
'viewportWidth' => 1440,
'content' => '<!-- wp:heading {"level":1} --><h1>One</h1><!-- /wp:heading -->',
'viewportWidth' => 1440,
'categories' => array( 'test' ),
'templateTypes' => array( 'page' ),
)
);
Expand All @@ -89,8 +89,8 @@ public static function wpSetUpBeforeClass( $factory ) {
'test/two',
array(
'title' => 'Pattern Two',
'categories' => array( 'test' ),
'content' => '<!-- wp:paragraph --><p>Two</p><!-- /wp:paragraph -->',
'categories' => array( 'test' ),
'templateTypes' => array( 'single' ),
)
);
Expand All @@ -99,8 +99,8 @@ public static function wpSetUpBeforeClass( $factory ) {
'test/three',
array(
'title' => 'Pattern Three',
'categories' => array( 'test', 'buttons', 'query' ),
'content' => '<!-- wp:paragraph --><p>Three</p><!-- /wp:paragraph -->',
'categories' => array( 'test', 'buttons', 'query' ),
)
);
}
Expand Down

0 comments on commit d2f6c41

Please sign in to comment.