Make WordPress Core

Changeset 55173


Ignore:
Timestamp:
02/01/2023 03:00:19 PM (4 years ago)
Author:
SergeyBiryukov
Message:

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.

Location:
trunk
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/block-patterns.php

    r55168 r55173  
    299299 *   - Description
    300300 *   - Viewport Width
     301 *   - Inserter         (yes/no)
    301302 *   - Categories       (comma-separated values)
    302303 *   - Keywords         (comma-separated values)
    … …  
    304305 *   - Post Types       (comma-separated values)
    305306 *   - Template Types   (comma-separated values)
    306  *   - Inserter         (yes/no)
    307307 *
    308308 * @since 6.0.0
     309 * @since 6.1.0 The `postTypes` property was added.
     310 * @since 6.2.0 The `templateTypes` property was added.
    309311 * @access private
    310312 */
    … …  
    315317                'description'   => 'Description',
    316318                'viewportWidth' => 'Viewport Width',
     319                'inserter'      => 'Inserter',
    317320                'categories'    => 'Categories',
    318321                'keywords'      => 'Keywords',
    319322                'blockTypes'    => 'Block Types',
    320323                'postTypes'     => 'Post Types',
    321                 'inserter'      => 'Inserter',
    322324                'templateTypes' => 'Template Types',
    323325        );
  • trunk/src/wp-includes/class-wp-block-patterns-registry.php

    r54850 r55173  
    4444         * @since 5.5.0
    4545         * @since 5.8.0 Added support for the `blockTypes` property.
     46         * @since 6.1.0 Added support for the `postTypes` property.
     47         * @since 6.2.0 Added support for the `templateTypes` property.
    4648         *
    4749         * @param string $pattern_name       Block pattern name including namespace.
    … …  
    5153         *     @type string $title         Required. A human-readable title for the pattern.
    5254         *     @type string $content       Required. Block HTML markup for the pattern.
    53          *     @type string $description   Optional. Visually hidden text used to describe the pattern in the
    54          *                                 inserter. A description is optional, but is strongly
     55         *     @type string $description   Optional. Visually hidden text used to describe the pattern
     56         *                                 in the inserter. A description is optional, but is strongly
    5557         *                                 encouraged when the title does not fully describe what the
    5658         *                                 pattern does. The description will help users discover the
    … …  
    5860         *     @type int    $viewportWidth Optional. The intended width of the pattern to allow for a scaled
    5961         *                                 preview within the pattern inserter.
    60          *     @type array  $categories    Optional. A list of registered pattern categories used to group block
    61          *                                 patterns. Block patterns can be shown on multiple categories.
    62          *                                 A category must be registered separately in order to be used
    63          *                                 here.
     62         *     @type array  $categories    Optional. A list of registered pattern categories used to group
     63         *                                 block patterns. Block patterns can be shown on multiple categories.
     64         *                                 A category must be registered separately in order to be used here.
     65         *     @type array  $keywords      Optional. A list of aliases or keywords that help users discover
     66         *                                 the pattern while searching.
    6467         *     @type array  $blockTypes    Optional. A list of block names including namespace that could use
    6568         *                                 the block pattern in certain contexts (placeholder, transforms).
    … …  
    6972         *                                 (e.g. for `core/template-part` you can specify areas
    7073         *                                 like `core/template-part/header` or `core/template-part/footer`).
    71          *     @type array  $postTypes     An array of post types that the pattern is restricted to be used with.
    72          *                                 The pattern will only be available when editing one of the post types
    73          *                                 passed on the array. For all the other post types not part of the array
    74          *                                 the pattern is not available at all.
    75          *     @type array  $keywords      Optional. A list of aliases or keywords that help users discover the
    76          *                                 pattern while searching.
     74         *     @type array  $postTypes     Optional. An array of post types that the pattern is restricted
     75         *                                 to be used with. The pattern will only be available when editing one
     76         *                                 of the post types passed on the array. For all the other post types
     77         *                                 not part of the array the pattern is not available at all.
     78         *     @type array  $templateTypes Optional. An array of template types where the pattern fits.
    7779         * }
    7880         * @return bool True if the pattern was registered with success and false otherwise.
  • trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-block-patterns-controller.php

    r55168 r55173  
    166166                        'name'          => 'name',
    167167                        'title'         => 'title',
     168                        'content'       => 'content',
    168169                        'description'   => 'description',
    169170                        'viewportWidth' => 'viewport_width',
     171                        'inserter'      => 'inserter',
     172                        'categories'    => 'categories',
     173                        'keywords'      => 'keywords',
    170174                        'blockTypes'    => 'block_types',
    171175                        'postTypes'     => 'post_types',
    172                         'categories'    => 'categories',
    173                         'keywords'      => 'keywords',
    174                         'content'       => 'content',
    175                         'inserter'      => 'inserter',
    176176                        'templateTypes' => 'template_types',
    177177                );
    … …  
    214214                                        'context'     => array( 'view', 'edit', 'embed' ),
    215215                                ),
     216                                'content'        => array(
     217                                        'description' => __( 'The pattern content.' ),
     218                                        'type'        => 'string',
     219                                        'readonly'    => true,
     220                                        'context'     => array( 'view', 'edit', 'embed' ),
     221                                ),
    216222                                'description'    => array(
    217223                                        'description' => __( 'The pattern detailed description.' ),
    … …  
    226232                                        'context'     => array( 'view', 'edit', 'embed' ),
    227233                                ),
    228                                 'block_types'    => array(
    229                                         'description' => __( 'Block types that the pattern is intended to be used with.' ),
    230                                         'type'        => 'array',
    231                                         'readonly'    => true,
    232                                         'context'     => array( 'view', 'edit', 'embed' ),
    233                                 ),
    234                                 'post_types'     => array(
    235                                         'description' => __( 'An array of post types that the pattern is restricted to be used with.' ),
    236                                         'type'        => 'array',
    237                                         'readonly'    => true,
    238                                         'context'     => array( 'view', 'edit', 'embed' ),
    239                                 ),
    240                                 'categories'     => array(
    241                                         'description' => __( 'The pattern category slugs.' ),
    242                                         'type'        => 'array',
    243                                         'readonly'    => true,
    244                                         'context'     => array( 'view', 'edit', 'embed' ),
    245                                 ),
    246                                 'keywords'       => array(
    247                                         'description' => __( 'The pattern keywords.' ),
    248                                         'type'        => 'array',
    249                                         'readonly'    => true,
    250                                         'context'     => array( 'view', 'edit', 'embed' ),
    251                                 ),
    252                                 'template_types' => array(
    253                                         'description' => __( 'An array of template types where the pattern fits.' ),
    254                                         'type'        => 'array',
    255                                         'readonly'    => true,
    256                                         'context'     => array( 'view', 'edit', 'embed' ),
    257                                 ),
    258                                 'content'        => array(
    259                                         'description' => __( 'The pattern content.' ),
    260                                         'type'        => 'string',
    261                                         'readonly'    => true,
    262                                         'context'     => array( 'view', 'edit', 'embed' ),
    263                                 ),
    264234                                'inserter'       => array(
    265235                                        'description' => __( 'Determines whether the pattern is visible in inserter.' ),
    … …  
    268238                                        'context'     => array( 'view', 'edit', 'embed' ),
    269239                                ),
     240                                'categories'     => array(
     241                                        'description' => __( 'The pattern category slugs.' ),
     242                                        'type'        => 'array',
     243                                        'readonly'    => true,
     244                                        'context'     => array( 'view', 'edit', 'embed' ),
     245                                ),
     246                                'keywords'       => array(
     247                                        'description' => __( 'The pattern keywords.' ),
     248                                        'type'        => 'array',
     249                                        'readonly'    => true,
     250                                        'context'     => array( 'view', 'edit', 'embed' ),
     251                                ),
     252                                'block_types'    => array(
     253                                        'description' => __( 'Block types that the pattern is intended to be used with.' ),
     254                                        'type'        => 'array',
     255                                        'readonly'    => true,
     256                                        'context'     => array( 'view', 'edit', 'embed' ),
     257                                ),
     258                                'post_types'     => array(
     259                                        'description' => __( 'An array of post types that the pattern is restricted to be used with.' ),
     260                                        'type'        => 'array',
     261                                        'readonly'    => true,
     262                                        'context'     => array( 'view', 'edit', 'embed' ),
     263                                ),
     264                                'template_types' => array(
     265                                        'description' => __( 'An array of template types where the pattern fits.' ),
     266                                        'type'        => 'array',
     267                                        'readonly'    => true,
     268                                        'context'     => array( 'view', 'edit', 'embed' ),
     269                                ),
    270270                        ),
    271271                );
  • trunk/tests/phpunit/tests/rest-api/wpRestBlockPatternsController.php

    r55168 r55173  
    7979                        array(
    8080                                'title'         => 'Pattern One',
     81                                'content'       => '<!-- wp:heading {"level":1} --><h1>One</h1><!-- /wp:heading -->',
     82                                'viewportWidth' => 1440,
    8183                                'categories'    => array( 'test' ),
    82                                 'viewportWidth' => 1440,
    83                                 'content'       => '<!-- wp:heading {"level":1} --><h1>One</h1><!-- /wp:heading -->',
    8484                                'templateTypes' => array( 'page' ),
    8585                        )
    … …  
    9090                        array(
    9191                                'title'         => 'Pattern Two',
     92                                'content'       => '<!-- wp:paragraph --><p>Two</p><!-- /wp:paragraph -->',
    9293                                'categories'    => array( 'test' ),
    93                                 'content'       => '<!-- wp:paragraph --><p>Two</p><!-- /wp:paragraph -->',
    9494                                'templateTypes' => array( 'single' ),
    9595                        )
    … …  
    100100                        array(
    101101                                'title'      => 'Pattern Three',
     102                                'content'    => '<!-- wp:paragraph --><p>Three</p><!-- /wp:paragraph -->',
    102103                                'categories' => array( 'test', 'buttons', 'query' ),
    103                                 'content'    => '<!-- wp:paragraph --><p>Three</p><!-- /wp:paragraph -->',
    104104                        )
    105105                );
Note: See TracChangeset for help on using the changeset viewer.