Skip to content

Commit

Permalink
Add context properties to block types REST endpoint (#22686)
Browse files Browse the repository at this point in the history 
* Docs: Add context properties to Block RFC

* Lib: Add context properties to block types endpoint

* RFC: Add default context properties

* Rename context to use_context when using inside REST API

* Include context properties in the RFC example

* Go with uses_context in REST API

* Follow PHP convention for naming fields: `provides_context` and `uses_context`

* Fix the usage of blockType.context in JS code

* Docs: Add deprecation entry for Block Context changes

* Fix missed places where context was not renamed to usesContext

* Add deprecation logic

* Remove an empty line

* Apply suggestions from code review

Co-authored-by: Miguel Fonseca <[email protected]>

* Add more deprecation details

* Update compat.php

Co-authored-by: Grzegorz Ziolkowski <[email protected]>
Co-authored-by: Miguel Fonseca <[email protected]>
  • Loading branch information
@aduth @gziolo @mcsf
3 people authored Jun 19, 2020
1 parent 9a988cf commit c33a5a5
Show file tree
Hide file tree
Showing 27 changed files with 229 additions and 107 deletions.
6 changes: 5 additions & 1 deletion docs/designers-developers/developers/backward-compatibility/deprecations.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,14 @@

For features included in the Gutenberg plugin, the deprecation policy is intended to support backward compatibility for two minor plugin releases, when possible. Features and code included in a stable release of WordPress are not included in this deprecation timeline, and are instead subject to the [versioning policies of the WordPress project](https://make.wordpress.org/core/handbook/about/release-cycle/version-numbering/). The current deprecations are listed below and are grouped by _the version at which they will be removed completely_. If your plugin depends on these behaviors, you must update to the recommended alternative before the noted version.

## 8.6.0

- Block API integration with [Block Context](https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/block-api/block-context.md) was updated. When registering a block use `usesContext` and `providesContext` pair in JavaScript files and `uses_context` and `provides_context` pair in PHP files instead of previous pair `context` and `providesContext`.

## 8.3.0

- The PHP function `gutenberg_get_post_from_context` has been removed. Use [Block Context](https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/block-api/block-context.md) instead.
- The old Block Pattern APIs `register_pattern`/`unregister_pattern` have been removed. Use the [new functions](https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/block-api/block-patterns.md#register_block_pattern) instead.
- The old Block Pattern APIs `register_pattern`/`unregister_pattern` have been removed. Use the [new functions](https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/block-api/block-patterns.md#register_block_pattern) instead.

## 5.5.0

Expand Down
4 changes: 2 additions & 2 deletions docs/designers-developers/developers/block-api/block-context.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,14 +34,14 @@ As seen in the above example, it is recommended that you include a namespace as

### Consuming Block Context

A block can inherit a context value from an ancestor provider by assigning a `context` property in its registered settings. This should be assigned as an array of the context names the block seeks to inherit.
A block can inherit a context value from an ancestor provider by assigning a `usesContext` property in its registered settings. This should be assigned as an array of the context names the block seeks to inherit.

`record-title/block.json`

```json
{
"name": "my-plugin/record-title",
"context": [ "my-plugin/recordId" ]
"usesContext": [ "my-plugin/recordId" ]
}
```

Expand Down
46 changes: 46 additions & 0 deletions docs/rfc/block-registration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,12 @@ To register a new block type, start by creating a `block.json` file. This file:
"selector": ".message"
}
},
"providesContext": {
"my-plugin/message": "message"
},
"usesContext": [
"groupId"
],
"supports": {
"align": true,
"lightBlockWrapper": true
Expand Down Expand Up @@ -252,6 +258,46 @@ Attributes provide the structured data needs of a block. They can exist in diffe

See the [the attributes documentation](/docs/designers-developers/developers/block-api/block-attributes.md) for more details.

### Provides Context

* Type: `object`
* Optional
* Localized: No
* Property: `providesContext`
* Default: `{}`

Context provided for available access by descendants of blocks of this type, in the form of an object which maps a context name to one of the block's own attribute.

See [the block context documentation](/docs/designers-developers/developers/block-api/block-context.md) for more details.

```json
{
"providesContext": {
"my-plugin/recordId": "recordId"
}
}
```

### Context

* Type: `string[]`
* Optional
* Localized: No
* Property: `usesContext`
* Default: `[]`

Array of the names of context values to inherit from an ancestor provider.

See [the block context documentation](/docs/designers-developers/developers/block-api/block-context.md) for more details.

```json
{
"usesContext": [
"message"
]
}
```

### Supports

* Type: `object`
Expand Down
29 changes: 23 additions & 6 deletions lib/class-wp-block.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -105,10 +105,29 @@ public function __construct( $block, $available_context = array(), $registry = n

$this->block_type = $registry->get_registered( $this->name );

if ( ! empty( $this->block_type->context ) ) {
$message = sprintf(
/* translators: 1: Block name. */
__( 'The "context" parameter provided in block type "%s" is deprecated. Please use "uses_context" instead.', 'gutenberg' ),
$this->name
);
_doing_it_wrong( __CLASS__, $message, '8.6.0' );
$this->block_type->uses_context = $this->block_type->context;
}
if ( ! empty( $this->block_type->providesContext ) ) {
$message = sprintf(
/* translators: 1: Block name. */
__( 'The "providesContext" parameter provided in block type "%s" is deprecated. Please use "provides_context".', 'gutenberg' ),
$this->name
);
_doing_it_wrong( __CLASS__, $message, '8.6.0' );
$this->block_type->provides_context = $this->block_type->providesContext;
}

$this->available_context = $available_context;

if ( ! empty( $this->block_type->context ) ) {
foreach ( $this->block_type->context as $context_name ) {
if ( ! empty( $this->block_type->uses_context ) ) {
foreach ( $this->block_type->uses_context as $context_name ) {
if ( array_key_exists( $context_name, $this->available_context ) ) {
$this->context[ $context_name ] = $this->available_context[ $context_name ];
}
Expand All @@ -118,15 +137,13 @@ public function __construct( $block, $available_context = array(), $registry = n
if ( ! empty( $block['innerBlocks'] ) ) {
$child_context = $this->available_context;

/* phpcs:disable WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase */
if ( ! empty( $this->block_type->providesContext ) ) {
foreach ( $this->block_type->providesContext as $context_name => $attribute_name ) {
if ( ! empty( $this->block_type->provides_context ) ) {
foreach ( $this->block_type->provides_context as $context_name => $attribute_name ) {
if ( array_key_exists( $attribute_name, $this->attributes ) ) {
$child_context[ $context_name ] = $this->attributes[ $attribute_name ];
}
}
}
/* phpcs:enable */

$this->inner_blocks = new WP_Block_List( $block['innerBlocks'], $child_context, $registry );
}
Expand Down
87 changes: 55 additions & 32 deletions lib/class-wp-rest-block-types-controller.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -239,21 +239,23 @@ public function prepare_item_for_response( $block_type, $request ) {

$schema = $this->get_item_schema();
$extra_fields = array(
'name' => 'name',
'title' => 'title',
'description' => 'description',
'icon' => 'icon',
'category' => 'category',
'keywords' => 'keywords',
'parent' => 'parent',
'supports' => 'supports',
'styles' => 'styles',
'textdomain' => 'textdomain',
'example' => 'example',
'editor_script' => 'editor_script',
'script' => 'script',
'editor_style' => 'editor_style',
'style' => 'style',
'name' => 'name',
'title' => 'title',
'description' => 'description',
'icon' => 'icon',
'category' => 'category',
'keywords' => 'keywords',
'parent' => 'parent',
'provides_context' => 'provides_context',
'uses_context' => 'uses_context',
'supports' => 'supports',
'styles' => 'styles',
'textdomain' => 'textdomain',
'example' => 'example',
'editor_script' => 'editor_script',
'script' => 'script',
'editor_style' => 'editor_style',
'style' => 'style',
);
foreach ( $extra_fields as $key => $extra_field ) {
if ( rest_is_field_included( $key, $fields ) ) {
Expand Down Expand Up @@ -337,35 +339,35 @@ public function get_item_schema() {
'title' => 'block-type',
'type' => 'object',
'properties' => array(
'title' => array(
'title' => array(
'description' => __( 'Title of block type.', 'gutenberg' ),
'type' => 'string',
'default' => '',
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'name' => array(
'name' => array(
'description' => __( 'Unique name identifying the block type.', 'gutenberg' ),
'type' => 'string',
'default' => '',
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'description' => array(
'description' => array(
'description' => __( 'Description of block type.', 'gutenberg' ),
'type' => 'string',
'default' => '',
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'icon' => array(
'icon' => array(
'description' => __( 'Icon of block type.', 'gutenberg' ),
'type' => array( 'string', 'null' ),
'default' => null,
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'attributes' => array(
'attributes' => array(
'description' => __( 'Block attributes.', 'gutenberg' ),
'type' => array( 'object', 'null' ),
'properties' => array(),
Expand All @@ -376,57 +378,78 @@ public function get_item_schema() {
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'supports' => array(
'provides_context' => array(
'description' => __( 'Context provided by blocks of this type.', 'gutenberg' ),
'type' => 'object',
'properties' => array(),
'additionalProperties' => array(
'type' => 'string',
),
'default' => array(),
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'uses_context' => array(
'description' => __( 'Context values inherited by blocks of this type.', 'gutenberg' ),
'type' => 'array',
'default' => array(),
'items' => array(
'type' => 'string',
),
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'supports' => array(
'description' => __( 'Block supports.', 'gutenberg' ),
'type' => 'object',
'default' => array(),
'properties' => array(),
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'category' => array(
'category' => array(
'description' => __( 'Block category.', 'gutenberg' ),
'type' => array( 'string', null ),
'default' => null,
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'is_dynamic' => array(
'is_dynamic' => array(
'description' => __( 'Is the block dynamically rendered.', 'gutenberg' ),
'type' => 'boolean',
'default' => false,
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'editor_script' => array(
'editor_script' => array(
'description' => __( 'Editor script handle.', 'gutenberg' ),
'type' => array( 'string', null ),
'default' => null,
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'script' => array(
'script' => array(
'description' => __( 'Public facing script handle.', 'gutenberg' ),
'type' => array( 'string', null ),
'default' => null,
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'editor_style' => array(
'editor_style' => array(
'description' => __( 'Editor style handle.', 'gutenberg' ),
'type' => array( 'string', null ),
'default' => null,
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'style' => array(
'style' => array(
'description' => __( 'Public facing style handle.', 'gutenberg' ),
'type' => array( 'string', null ),
'default' => null,
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'styles' => array(
'styles' => array(
'description' => __( 'Block style variations.', 'gutenberg' ),
'type' => 'array',
'properties' => array(),
Expand All @@ -437,14 +460,14 @@ public function get_item_schema() {
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'textdomain' => array(
'textdomain' => array(
'description' => __( 'Public text domain.', 'gutenberg' ),
'type' => array( 'string', 'null' ),
'default' => null,
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'parent' => array(
'parent' => array(
'description' => __( 'Parent blocks.', 'gutenberg' ),
'type' => array( 'array', 'null' ),
'items' => array(
Expand All @@ -454,7 +477,7 @@ public function get_item_schema() {
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'keywords' => array(
'keywords' => array(
'description' => __( 'Block keywords.', 'gutenberg' ),
'type' => 'array',
'items' => array(
Expand All @@ -464,7 +487,7 @@ public function get_item_schema() {
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'example' => array(
'example' => array(
'description' => __( 'Block example.', 'gutenberg' ),
'type' => array( 'object', 'null' ),
'default' => null,
Expand Down
25 changes: 14 additions & 11 deletions lib/compat.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -167,17 +167,20 @@ function register_block_type_from_metadata( $file_or_folder, $args = array() ) {

$settings = array();
$property_mappings = array(
'title' => 'title',
'category' => 'category',
'context' => 'context',
'parent' => 'parent',
'icon' => 'icon',
'description' => 'description',
'keywords' => 'keywords',
'attributes' => 'attributes',
'supports' => 'supports',
'styles' => 'styles',
'example' => 'example',
'title' => 'title',
'category' => 'category',
'parent' => 'parent',
'icon' => 'icon',
'description' => 'description',
'keywords' => 'keywords',
'attributes' => 'attributes',
'providesContext' => 'provides_context',
'usesContext' => 'uses_context',
// Deprecated: remove with Gutenberg 8.6 release.
'context' => 'context',
'supports' => 'supports',
'styles' => 'styles',
'example' => 'example',
);

foreach ( $property_mappings as $key => $mapped_key ) {
Expand Down
Loading

0 comments on commit c33a5a5

Please sign in to comment.