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
This commit is contained in:
Sergey Biryukov 2023-02-01 15:02:14 +00:00
parent cafd7544c2
commit d099f2f708
4 changed files with 40 additions and 36 deletions

View File

@ -298,14 +298,16 @@ function _register_remote_theme_patterns() {
* *
* - Description * - Description
* - Viewport Width * - Viewport Width
* - Inserter (yes/no)
* - Categories (comma-separated values) * - Categories (comma-separated values)
* - Keywords (comma-separated values) * - Keywords (comma-separated values)
* - Block Types (comma-separated values) * - Block Types (comma-separated values)
* - Post Types (comma-separated values) * - Post Types (comma-separated values)
* - Template Types (comma-separated values) * - Template Types (comma-separated values)
* - Inserter (yes/no)
* *
* @since 6.0.0 * @since 6.0.0
* @since 6.1.0 The `postTypes` property was added.
* @since 6.2.0 The `templateTypes` property was added.
* @access private * @access private
*/ */
function _register_theme_block_patterns() { function _register_theme_block_patterns() {
@ -314,11 +316,11 @@ function _register_theme_block_patterns() {
'slug' => 'Slug', 'slug' => 'Slug',
'description' => 'Description', 'description' => 'Description',
'viewportWidth' => 'Viewport Width', 'viewportWidth' => 'Viewport Width',
'inserter' => 'Inserter',
'categories' => 'Categories', 'categories' => 'Categories',
'keywords' => 'Keywords', 'keywords' => 'Keywords',
'blockTypes' => 'Block Types', 'blockTypes' => 'Block Types',
'postTypes' => 'Post Types', 'postTypes' => 'Post Types',
'inserter' => 'Inserter',
'templateTypes' => 'Template Types', 'templateTypes' => 'Template Types',
); );

View File

@ -43,6 +43,8 @@ final class WP_Block_Patterns_Registry {
* *
* @since 5.5.0 * @since 5.5.0
* @since 5.8.0 Added support for the `blockTypes` property. * @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 string $pattern_name Block pattern name including namespace.
* @param array $pattern_properties { * @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 $title Required. A human-readable title for the pattern.
* @type string $content Required. Block HTML markup 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 * @type string $description Optional. Visually hidden text used to describe the pattern
* inserter. A description is optional, but is strongly * in the inserter. A description is optional, but is strongly
* encouraged when the title does not fully describe what the * encouraged when the title does not fully describe what the
* pattern does. The description will help users discover the * pattern does. The description will help users discover the
* pattern while searching. * pattern while searching.
* @type int $viewportWidth Optional. The intended width of the pattern to allow for a scaled * @type int $viewportWidth Optional. The intended width of the pattern to allow for a scaled
* preview within the pattern inserter. * preview within the pattern inserter.
* @type array $categories Optional. A list of registered pattern categories used to group block * @type array $categories Optional. A list of registered pattern categories used to group
* patterns. Block patterns can be shown on multiple categories. * block patterns. Block patterns can be shown on multiple categories.
* A category must be registered separately in order to be used * A category must be registered separately in order to be used here.
* 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 * @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 in certain contexts (placeholder, transforms).
* The block pattern is available in the block editor inserter * 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 * Certain blocks support further specificity besides the block name
* (e.g. for `core/template-part` you can specify areas * (e.g. for `core/template-part` you can specify areas
* like `core/template-part/header` or `core/template-part/footer`). * 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. * @type array $postTypes Optional. An array of post types that the pattern is restricted
* The pattern will only be available when editing one of the post types * to be used with. The pattern will only be available when editing one
* passed on the array. For all the other post types not part of the array * of the post types passed on the array. For all the other post types
* the pattern is not available at all. * 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 * @type array $templateTypes Optional. An array of template types where the pattern fits.
* pattern while searching.
* } * }
* @return bool True if the pattern was registered with success and false otherwise. * @return bool True if the pattern was registered with success and false otherwise.
*/ */

View File

@ -165,14 +165,14 @@ class WP_REST_Block_Patterns_Controller extends WP_REST_Controller {
$keys = array( $keys = array(
'name' => 'name', 'name' => 'name',
'title' => 'title', 'title' => 'title',
'content' => 'content',
'description' => 'description', 'description' => 'description',
'viewportWidth' => 'viewport_width', 'viewportWidth' => 'viewport_width',
'blockTypes' => 'block_types', 'inserter' => 'inserter',
'postTypes' => 'post_types',
'categories' => 'categories', 'categories' => 'categories',
'keywords' => 'keywords', 'keywords' => 'keywords',
'content' => 'content', 'blockTypes' => 'block_types',
'inserter' => 'inserter', 'postTypes' => 'post_types',
'templateTypes' => 'template_types', 'templateTypes' => 'template_types',
); );
$data = array(); $data = array();
@ -213,6 +213,12 @@ class WP_REST_Block_Patterns_Controller extends WP_REST_Controller {
'readonly' => true, 'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ), 'context' => array( 'view', 'edit', 'embed' ),
), ),
'content' => array(
'description' => __( 'The pattern content.' ),
'type' => 'string',
'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ),
),
'description' => array( 'description' => array(
'description' => __( 'The pattern detailed description.' ), 'description' => __( 'The pattern detailed description.' ),
'type' => 'string', 'type' => 'string',
@ -225,15 +231,9 @@ class WP_REST_Block_Patterns_Controller extends WP_REST_Controller {
'readonly' => true, 'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ), 'context' => array( 'view', 'edit', 'embed' ),
), ),
'block_types' => array( 'inserter' => array(
'description' => __( 'Block types that the pattern is intended to be used with.' ), 'description' => __( 'Determines whether the pattern is visible in inserter.' ),
'type' => 'array', 'type' => 'boolean',
'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',
'readonly' => true, 'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ), 'context' => array( 'view', 'edit', 'embed' ),
), ),
@ -249,21 +249,21 @@ class WP_REST_Block_Patterns_Controller extends WP_REST_Controller {
'readonly' => true, 'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ), 'context' => array( 'view', 'edit', 'embed' ),
), ),
'template_types' => array( 'block_types' => array(
'description' => __( 'An array of template types where the pattern fits.' ), 'description' => __( 'Block types that the pattern is intended to be used with.' ),
'type' => 'array', 'type' => 'array',
'readonly' => true, 'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ), 'context' => array( 'view', 'edit', 'embed' ),
), ),
'content' => array( 'post_types' => array(
'description' => __( 'The pattern content.' ), 'description' => __( 'An array of post types that the pattern is restricted to be used with.' ),
'type' => 'string', 'type' => 'array',
'readonly' => true, 'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ), 'context' => array( 'view', 'edit', 'embed' ),
), ),
'inserter' => array( 'template_types' => array(
'description' => __( 'Determines whether the pattern is visible in inserter.' ), 'description' => __( 'An array of template types where the pattern fits.' ),
'type' => 'boolean', 'type' => 'array',
'readonly' => true, 'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ), 'context' => array( 'view', 'edit', 'embed' ),
), ),

View File

@ -16,7 +16,7 @@
* *
* @global string $wp_version * @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. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.