Changeset 56587

Timestamp:

09/14/2023 01:23:13 PM (12 months ago)

Author:

Bernhard Reiter

Message:

General: Add block_hooks field to block type registration, REST API.

In order to implement Block Hooks, we need to add a new block_hooks field to the WP_Block_Type class, as well as to block registration related functions, the block types REST API controller, etc.

Props gziolo.
Fixes #59346. See #59313.

Location:

trunk

Files:

• src/wp-admin/includes/post.php (modified) (2 diffs)
• src/wp-includes/blocks.php (modified) (2 diffs)
• src/wp-includes/class-wp-block-type.php (modified) (3 diffs)
• src/wp-includes/rest-api/endpoints/class-wp-rest-block-types-controller.php (modified) (2 diffs)
• tests/phpunit/data/blocks/notice/block.json (modified) (1 diff)
• tests/phpunit/tests/admin/includesPost.php (modified) (2 diffs)
• tests/phpunit/tests/blocks/register.php (modified) (1 diff)
• tests/phpunit/tests/rest-api/rest-block-type-controller.php (modified) (11 diffs)

trunk/src/wp-admin/includes/post.php

@@ -2208 +2208 @@
  * @since 5.0.0
  * @since 6.3.0 Added `selectors` field.
+ * @since 6.4.0 Added `block_hooks` field.
  *
  * @return array An associative array of registered block data.
@@ -2222 +2223 @@
         'provides_context' => 'providesContext',
         'uses_context'     => 'usesContext',
+        'block_hooks'      => 'blockHooks',
         'selectors'        => 'selectors',
         'supports'         => 'supports',

trunk/src/wp-includes/blocks.php

@@ -343 +343 @@
  * @since 6.1.0 Added support for `render` field.
  * @since 6.3.0 Added `selectors` field.
+ * @since 6.4.0 Added support for `blockHooks` field.
  *
  * @param string $file_or_folder Path to the JSON file with metadata definition for
@@ -514 +515 @@
     }
 
+    if ( ! empty( $metadata['blockHooks'] ) ) {
+        /**
+         * Map camelCased position string (from block.json) to snake_cased block type position.
+         *
+         * @var array
+         */
+        $position_mappings = array(
+            'before'     => 'before',
+            'after'      => 'after',
+            'firstChild' => 'first_child',
+            'lastChild'  => 'last_child',
+        );
+
+        $settings['block_hooks'] = array();
+        foreach ( $metadata['blockHooks'] as $anchor_block_name => $position ) {
+            // Avoid infinite recursion (hooking to itself).
+            if ( $metadata['name'] === $anchor_block_name ) {
+                _doing_it_wrong(
+                    __METHOD__,
+                    __( 'Cannot hook block to itself.', 'gutenberg' ),
+                    '6.4.0'
+                );
+                continue;
+            }
+
+            if ( ! isset( $position_mappings[ $position ] ) ) {
+                continue;
+            }
+
+            $settings['block_hooks'][ $anchor_block_name ] = $position_mappings[ $position ];
+        }
+    }
+
     if ( ! empty( $metadata['render'] ) ) {
         $template_path = wp_normalize_path(

trunk/src/wp-includes/class-wp-block-type.php

@@ -173 +173 @@
      */
     public $provides_context = null;
+
+    /**
+     * Block hooks for this block type.
+     *
+     * A block hook is specified by a block type and a relative position.
+     * The hooked block will be automatically inserted in the given position
+     * next to the "anchor" block whenever the latter is encountered.
+     *
+     * @since 6.4.0
+     * @var array[]
+     */
+    public $block_hooks = array();
 
     /**
@@ -255 +267 @@
      *              Deprecated the `editor_script`, `script`, `view_script`, `editor_style`, and `style` properties.
      * @since 6.3.0 Added the `selectors` property.
+     * @since 6.4.0 Added the `block_hooks` property.
      *
      * @see register_block_type()
@@ -285 +298 @@
      *     @type string[]      $uses_context             Context values inherited by blocks of this type.
      *     @type string[]|null $provides_context         Context provided by blocks of this type.
+     *     @type array[]       $block_hooks              Block hooks.
      *     @type string[]      $editor_script_handles    Block type editor only script handles.
      *     @type string[]      $script_handles           Block type front end and editor script handles.

trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-block-types-controller.php

@@ -292 +292 @@
                 'style_handles',
                 'variations',
+                'block_hooks',
             ),
             $deprecated_fields
@@ -707 +708 @@
                 'keywords'              => $keywords_definition,
                 'example'               => $example_definition,
+                'block_hooks'           => array(
+                    'description'       => __( 'This block is automatically inserted near any occurence of the block types used as keys of this map, into a relative position given by the corresponding value.' ),
+                    'type'              => 'object',
+                    'patternProperties' => array(
+                        '^[a-zA-Z0-9-]+/[a-zA-Z0-9-]+$' => array(
+                            'type' => 'string',
+                            'enum' => array( 'before', 'after', 'first_child', 'last_child' ),
+                        ),
+                    ),
+                    'default'           => array(),
+                    'context'           => array( 'embed', 'view', 'edit' ),
+                    'readonly'          => true,
+                ),
             ),
         );

trunk/tests/phpunit/data/blocks/notice/block.json

@@ -30 +30 @@
     "selectors": {
         "root": ".wp-block-notice"
+    },
+    "blockHooks": {
+        "core/post-content": "before"
     },
     "supports": {

trunk/tests/phpunit/tests/admin/includesPost.php

@@ -919 +919 @@
             'ancestor'        => array( 'core/test-ancestor' ),
             'selectors'       => array( 'root' => '.wp-block-test' ),
+            'block_hooks'     => array( 'core/post-content' => 'before' ),
         );
 
@@ -938 +939 @@
                 ),
                 'usesContext' => array(),
+                'blockHooks'  => array( 'core/post-content' => 'before' ),
                 'selectors'   => array( 'root' => '.wp-block-test' ),
                 'category'    => 'common',

trunk/tests/phpunit/tests/blocks/register.php

@@ -645 +645 @@
             'Block type should contain selectors from metadata.'
         );
+        // @ticket 59346
+        $this->assertSame(
+            array( 'core/post-content' => 'before' ),
+            $result->block_hooks,
+            'Block type should contain block hooks from metadata.'
+        );
         $this->assertSame(
             array(

trunk/tests/phpunit/tests/rest-api/rest-block-type-controller.php

@@ -196 +196 @@
      * @ticket 47620
      * @ticket 57585
+     * @ticket 59346
      */
     public function test_get_item_invalid() {
@@ -206 +207 @@
             'provides_context' => 'invalid_provides_context',
             'uses_context'     => 'invalid_uses_context',
+            'block_hooks'      => 'invalid_block_hooks',
             'category'         => true,
             'editor_script'    => true,
@@ -245 +247 @@
         );
         $this->assertSameSets( array( 'invalid_uses_context' ), $data['uses_context'] );
+        $this->assertSameSets( array(), $data['block_hooks'], 'invalid block_hooks defaults to empty array' );
         $this->assertSameSets( array( 'invalid_keywords' ), $data['keywords'] );
         $this->assertSameSets( array( 'invalid_parent' ), $data['parent'] );
@@ -267 +270 @@
      * @ticket 47620
      * @ticket 57585
+     * @ticket 59346
      */
     public function test_get_item_defaults() {
@@ -277 +281 @@
             'provides_context' => false,
             'uses_context'     => false,
+            'block_hooks'      => false,
             'category'         => false,
             'editor_script'    => false,
@@ -315 +320 @@
         );
         $this->assertSameSets( array(), $data['provides_context'] );
+        $this->assertSameSets( array(), $data['block_hooks'], 'block_hooks defaults to empty array' );
         $this->assertSameSets( array(), $data['uses_context'] );
         $this->assertSameSets( array(), $data['keywords'] );
@@ -539 +545 @@
      * @ticket 47620
      * @ticket 57585
+     * @ticket 59346
      */
     public function test_get_item_schema() {
@@ -546 +553 @@
         $data       = $response->get_data();
         $properties = $data['schema']['properties'];
-        $this->assertCount( 29, $properties );
+        $this->assertCount( 30, $properties );
         $this->assertArrayHasKey( 'api_version', $properties );
         $this->assertArrayHasKey( 'title', $properties );
@@ -569 +576 @@
         $this->assertArrayHasKey( 'uses_context', $properties );
         $this->assertArrayHasKey( 'provides_context', $properties );
+        $this->assertArrayHasKey( 'block_hooks', $properties );
         $this->assertArrayHasKey( 'variations', $properties );
         $this->assertArrayHasKey( 'ancestor', $properties );
@@ -665 +673 @@
      *
      * @since 5.5.0
+     * @since 6.4.0 Added the `block_hooks` extra field.
      *
      * @param WP_Block_Type $block_type Sample block type.
@@ -691 +700 @@
             'provides_context',
             'uses_context',
+            'block_hooks',
             'supports',
             'styles',