WordPress.org
Get WordPress

Make WordPress Core

Changeset 55173


Ignore:
Timestamp:
02/01/2023 03:00:19 PM (20 months 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.