From a32929134aa224bb15d9064fd57f25893388aca6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20Ka=CC=88gy?= Date: Tue, 19 Jul 2022 20:21:26 +0200 Subject: [PATCH 1/7] add variations key to block.json JSON schema definition --- schemas/json/block.json | 80 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) diff --git a/schemas/json/block.json b/schemas/json/block.json index fb1aa5ce49ff0..22d9caf7daf4c 100644 --- a/schemas/json/block.json +++ b/schemas/json/block.json @@ -482,6 +482,86 @@ } } ] + }, + "variations": { + "type": "array", + "description": "Block Variations is the API that allows a block to have similar versions of it, but all these versions share some common functionality.", + "items": { + "type": "object", + "required": [ "name", "title" ], + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "description": "The unique and machine-readable name." + }, + "title": { + "type": "string", + "description": "A human-readable variation title." + }, + "description": { + "type": "string", + "description": "A detailed variation description." + }, + "category": { + "type": "string", + "description": "A category classification, used in search interfaces to arrange block types by category." + }, + "icon": { + "description": "An icon helping to visualize the variation. It can have the same shape as the block type.", + "oneOf": [ + { + "type": "string" + }, + { + "type": "object" + } + ] + }, + "isDefault": { + "type": "boolean", + "default": false, + "description": "Indicates whether the current variation is the default one." + }, + "attributes": { + "type": "object", + "description": "Values that override block attributes." + }, + "innerBlocks": { + "type": "array", + "items": { + "type": "array" + }, + "description": "Initial configuration of nested blocks." + }, + "example": { + "type": "object", + "description": "Example provides structured data for the block preview. You can set to undefined to disable the preview shown for the block type." + }, + "scope": { + "type": "array", + "description": "The list of scopes where the variation is applicable.", + "items": { + "enum": [ "inserter", "block", "transform" ] + }, + "default": [ "inseter", "block" ] + }, + "keywords": { + "type": "array", + "description": "An array of terms (which can be translated) that help users discover the variation while searching.", + "items": { + "type": "string" + } + }, + "isActive": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The list of attributes that should be compared. Each attributes will be matched and the variation will be active if all of them are matching." + } + } + } } }, "required": [ "name", "title" ], From 1e170ed680572338f44aae98a038e3e120fab97e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20Ka=CC=88gy?= Date: Tue, 19 Jul 2022 20:52:48 +0200 Subject: [PATCH 2/7] fix add string suggestions to variation category --- schemas/json/block.json | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/schemas/json/block.json b/schemas/json/block.json index 22d9caf7daf4c..a862caf0a3aa5 100644 --- a/schemas/json/block.json +++ b/schemas/json/block.json @@ -504,8 +504,22 @@ "description": "A detailed variation description." }, "category": { - "type": "string", - "description": "A category classification, used in search interfaces to arrange block types by category." + "description": "A category classification, used in search interfaces to arrange block types by category.", + "anyOf": [ + { + "type": "string" + }, + { + "enum": [ + "text", + "media", + "design", + "widgets", + "theme", + "embed" + ] + } + ] }, "icon": { "description": "An icon helping to visualize the variation. It can have the same shape as the block type.", From e70e99e523b4c33b2de7c3c4690228861d2c3931 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20Ka=CC=88gy?= Date: Wed, 20 Jul 2022 09:48:29 +0200 Subject: [PATCH 3/7] fix type of variation icon to only string --- schemas/json/block.json | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/schemas/json/block.json b/schemas/json/block.json index a862caf0a3aa5..b823ab25fba23 100644 --- a/schemas/json/block.json +++ b/schemas/json/block.json @@ -523,14 +523,7 @@ }, "icon": { "description": "An icon helping to visualize the variation. It can have the same shape as the block type.", - "oneOf": [ - { - "type": "string" - }, - { - "type": "object" - } - ] + "type": "string" }, "isDefault": { "type": "boolean", From 4c8f4ff6531333b2dffd474806d283e2bae91c3e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20Ka=CC=88gy?= Date: Wed, 20 Jul 2022 10:12:33 +0200 Subject: [PATCH 4/7] add Variations section in block metadata documentation --- .../block-api/block-metadata.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/reference-guides/block-api/block-metadata.md b/docs/reference-guides/block-api/block-metadata.md index 4998e3dad0781..81490224a0cd1 100644 --- a/docs/reference-guides/block-api/block-metadata.md +++ b/docs/reference-guides/block-api/block-metadata.md @@ -421,6 +421,34 @@ It provides structured example data for the block. This data is used to construc See the [the example documentation](/docs/reference-guides/block-api/block-registration.md#example-optional) for more details. +### Variations + +- Type: `array` +- Optional +- Localized: Yes (`title`, `description`, and `keywords` of each variation only) +- Property: `variations` + +```json +{ + "variations": [ + { + "name": "example", + "title": "Example", + "attributes": { + "level": 2, + "message": "This is an example!" + }, + "scope": [ "block" ], + "isActive": [ "level" ] + } + ] +} +``` + +_Note: JavaScript functions (isActive) and React elements (icon) can't be used in block.json_ + +See the [the variations documentation](/docs/reference-guides/block-api/block-variations.md) for more details. + ### Editor Script - Type: `WPDefinedAsset` ([learn more](#wpdefinedasset)) From ca0d80c56fde22ab64b216eafbd3e3d27c16860e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20Ka=CC=88gy?= Date: Wed, 20 Jul 2022 10:22:05 +0200 Subject: [PATCH 5/7] fix type of variations in documentation --- docs/reference-guides/block-api/block-metadata.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/reference-guides/block-api/block-metadata.md b/docs/reference-guides/block-api/block-metadata.md index 81490224a0cd1..4ee1c50a2b836 100644 --- a/docs/reference-guides/block-api/block-metadata.md +++ b/docs/reference-guides/block-api/block-metadata.md @@ -423,7 +423,7 @@ See the [the example documentation](/docs/reference-guides/block-api/block-regis ### Variations -- Type: `array` +- Type: `object[]` - Optional - Localized: Yes (`title`, `description`, and `keywords` of each variation only) - Property: `variations` @@ -445,7 +445,9 @@ See the [the example documentation](/docs/reference-guides/block-api/block-regis } ``` -_Note: JavaScript functions (isActive) and React elements (icon) can't be used in block.json_ +Block Variations is the API that allows a block to have similar versions of it, but all these versions share some common functionality. Each block variation is differentiated from the others by setting some initial attributes or inner blocks. Then at the time when a block is inserted these attributes and/or inner blocks are applied. + +_Note: In JavaScript you can provide a function for the `isActive` property, and a React element for the `icon`. In the `block.json` file both only support strings_ See the [the variations documentation](/docs/reference-guides/block-api/block-variations.md) for more details. From 081f27e8fbcb017bf5c24431b0fdb94f425fbdce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20Ka=CC=88gy?= Date: Wed, 20 Jul 2022 10:24:14 +0200 Subject: [PATCH 6/7] add variations to overall block.json example --- docs/reference-guides/block-api/block-metadata.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/reference-guides/block-api/block-metadata.md b/docs/reference-guides/block-api/block-metadata.md index 4ee1c50a2b836..c22a88face9d2 100644 --- a/docs/reference-guides/block-api/block-metadata.md +++ b/docs/reference-guides/block-api/block-metadata.md @@ -40,6 +40,15 @@ Starting in WordPress 5.8 release, we encourage using the `block.json` metadata "message": "This is a notice!" } }, + "variations": [ + { + "name": "example", + "title": "Example", + "attributes": { + "message": "This is an example!" + }, + } + ] "editorScript": "file:./build/index.js", "script": "file:./build/script.js", "viewScript": "file:./build/view.js", From 920ffa8fe417dadc95d770dbb3df1f57d4922b9b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20K=C3=A4gy?= Date: Wed, 20 Jul 2022 10:28:09 +0200 Subject: [PATCH 7/7] Update docs/reference-guides/block-api/block-metadata.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Greg Ziółkowski --- docs/reference-guides/block-api/block-metadata.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference-guides/block-api/block-metadata.md b/docs/reference-guides/block-api/block-metadata.md index c22a88face9d2..a2282972f1d4e 100644 --- a/docs/reference-guides/block-api/block-metadata.md +++ b/docs/reference-guides/block-api/block-metadata.md @@ -436,6 +436,7 @@ See the [the example documentation](/docs/reference-guides/block-api/block-regis - Optional - Localized: Yes (`title`, `description`, and `keywords` of each variation only) - Property: `variations` +- Since: `WordPress 5.9.0` ```json {