From d099f2f7084d3753d3b4f20e5a77660ea236604e Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Wed, 1 Feb 2023 15:02:14 +0000 Subject: [PATCH] Docs: Improve documentation for block pattern properties. 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. Built from https://develop.svn.wordpress.org/trunk@55173 git-svn-id: http://core.svn.wordpress.org/trunk@54706 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/block-patterns.php | 6 ++- .../class-wp-block-patterns-registry.php | 26 ++++++------ ...lass-wp-rest-block-patterns-controller.php | 42 +++++++++---------- wp-includes/version.php | 2 +- 4 files changed, 40 insertions(+), 36 deletions(-) diff --git a/wp-includes/block-patterns.php b/wp-includes/block-patterns.php index 05bb6817eb..ff3d03cd43 100644 --- a/wp-includes/block-patterns.php +++ b/wp-includes/block-patterns.php @@ -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() { @@ -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', ); diff --git a/wp-includes/class-wp-block-patterns-registry.php b/wp-includes/class-wp-block-patterns-registry.php index a11c99d8c8..8d86b34087 100644 --- a/wp-includes/class-wp-block-patterns-registry.php +++ b/wp-includes/class-wp-block-patterns-registry.php @@ -43,6 +43,8 @@ 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 { @@ -50,17 +52,18 @@ final class WP_Block_Patterns_Registry { * * @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 @@ -68,12 +71,11 @@ final class WP_Block_Patterns_Registry { * 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. */ diff --git a/wp-includes/rest-api/endpoints/class-wp-rest-block-patterns-controller.php b/wp-includes/rest-api/endpoints/class-wp-rest-block-patterns-controller.php index 4d50bfae04..445f8c82f6 100644 --- a/wp-includes/rest-api/endpoints/class-wp-rest-block-patterns-controller.php +++ b/wp-includes/rest-api/endpoints/class-wp-rest-block-patterns-controller.php @@ -165,14 +165,14 @@ class WP_REST_Block_Patterns_Controller extends WP_REST_Controller { $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(); @@ -213,6 +213,12 @@ class WP_REST_Block_Patterns_Controller extends WP_REST_Controller { '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', @@ -225,15 +231,9 @@ class WP_REST_Block_Patterns_Controller extends WP_REST_Controller { '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' ), ), @@ -249,21 +249,21 @@ class WP_REST_Block_Patterns_Controller extends WP_REST_Controller { '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' ), ), diff --git a/wp-includes/version.php b/wp-includes/version.php index 9e9fa489b2..d9b8285eb1 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.2-alpha-55172'; +$wp_version = '6.2-alpha-55173'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.