From 06c15f433a5e40ddbe803a9815154cc924b95132 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Mon, 10 Feb 2020 16:57:19 +0100 Subject: [PATCH 1/3] Docs: Add docs for variations in the block registration section --- .../block-api/block-registration.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/docs/designers-developers/developers/block-api/block-registration.md b/docs/designers-developers/developers/block-api/block-registration.md index e31115ea459b87..01848b7ecd4dc6 100644 --- a/docs/designers-developers/developers/block-api/block-registration.md +++ b/docs/designers-developers/developers/block-api/block-registration.md @@ -188,6 +188,69 @@ example: { If `example` is not defined, the preview will not be shown. So even if no-attributes are defined, setting a empty example object `example: {}` will trigger the preview to show. +#### variations (optional) + +- **Type:** `Array` + +Similar to how the block's style variations can be declared, a block type can define block variations the user can pick from. The difference is that rather than changing only the visual appearance, this field provides a way to apply initial custom attributes and inner blocks at the time when a block is inserted. All variations by default will show up in the inserter in addition to the regular block type item. When the `isDefault` flag is set for any of the variations listed, then it overrides the regular block type item in the inserter instead. + +{% codetabs %} +{% ES5 %} + +```js +variations: [ + { + name: 'wordpress', + isDefault: true, + title: __( 'WordPress' ), + description: __( 'Code is poetry!' ), + icon: WordPressIcon, + attributes: { service: 'wordpress' }, + }, + { + name: 'google', + title: __( 'Google' ), + icon: GoogleIcon, + attributes: { service: 'google' }, + }, + { + name: 'twitter', + title: __( 'Twitter' ), + icon: TwitterIcon, + attributes: { service: 'twitter' }, + }, +], +``` + +{% ESNext %} + +```js +variations: [ + { + name: 'wordpress', + isDefault: true, + title: __( 'WordPress' ), + description: __( 'Code is poetry!' ), + icon: WordPressIcon, + attributes: { service: 'wordpress' }, + }, + { + name: 'google', + title: __( 'Google' ), + icon: GoogleIcon, + attributes: { service: 'google' }, + }, + { + name: 'twitter', + title: __( 'Twitter' ), + icon: TwitterIcon, + attributes: { service: 'twitter' }, + }, +], +``` + +{% end %} + #### transforms (optional) - **Type:** `Array` From 7f5f198a06c79e77391c72b8bd7795f518072e00 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Grzegorz=20=28Greg=29=20Zi=C3=B3=C5=82kowski?= Date: Wed, 12 Feb 2020 10:54:15 +0100 Subject: [PATCH 2/3] Update docs/designers-developers/developers/block-api/block-registration.md Co-Authored-By: Miguel Fonseca --- .../developers/block-api/block-registration.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/block-api/block-registration.md b/docs/designers-developers/developers/block-api/block-registration.md index 01848b7ecd4dc6..91530666232fce 100644 --- a/docs/designers-developers/developers/block-api/block-registration.md +++ b/docs/designers-developers/developers/block-api/block-registration.md @@ -192,7 +192,9 @@ If `example` is not defined, the preview will not be shown. So even if no-attrib - **Type:** `Array` -Similar to how the block's style variations can be declared, a block type can define block variations the user can pick from. The difference is that rather than changing only the visual appearance, this field provides a way to apply initial custom attributes and inner blocks at the time when a block is inserted. All variations by default will show up in the inserter in addition to the regular block type item. When the `isDefault` flag is set for any of the variations listed, then it overrides the regular block type item in the inserter instead. +Similarly to how the block's style variations can be declared, a block type can define block variations that the user can pick from. The difference is that, rather than changing only the visual appearance, this field provides a way to apply initial custom attributes and inner blocks at the time when a block is inserted. + +By default, all variations will show up in the Inserter in addition to the regular block type item. However, setting the `isDefault` flag for any of the variations listed will override the regular block type in the Inserter. {% codetabs %} {% ES5 %} From 83b4c2edf03c5ab74c883ed5671902b0b762e009 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Mon, 17 Feb 2020 16:59:29 +0100 Subject: [PATCH 3/3] Docs: Add description of all availabled fields to be registered with block variations --- .../developers/block-api/block-registration.md | 14 +++++++++++++- packages/blocks/src/api/registration.js | 2 +- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/designers-developers/developers/block-api/block-registration.md b/docs/designers-developers/developers/block-api/block-registration.md index 91530666232fce..bc07a3bc075285 100644 --- a/docs/designers-developers/developers/block-api/block-registration.md +++ b/docs/designers-developers/developers/block-api/block-registration.md @@ -190,7 +190,7 @@ If `example` is not defined, the preview will not be shown. So even if no-attrib #### variations (optional) -- **Type:** `Array` +- **Type:** `Object[]` Similarly to how the block's style variations can be declared, a block type can define block variations that the user can pick from. The difference is that, rather than changing only the visual appearance, this field provides a way to apply initial custom attributes and inner blocks at the time when a block is inserted. @@ -253,6 +253,18 @@ variations: [ {% end %} +An object describing a variation defined for the block type can contain the following fields: + +- `name` (type `string`) – The unique and machine-readable name. +- `title` (type `string`) – A human-readable variation title. +- `description` (optional, type `string`) – A detailed variation description. +- `icon` (optional, type `String` | `Object`) – An icon helping to visualize the variation. It can have the same shape as the block type. +- `isDefault` (optional, type `boolean`) – Indicates whether the current variation is the default one. Defaults to `false`. +- `attributes` (optional, type `Object`) – Values that override block attributes. +- `innerBlocks` (optional, type `Array[]`) – Initial configuration of nested blocks. +- `example` (optional, type `Object`) – Example provides structured data for the block preview. You can set to `undefined` to disable the preview shown for the block type. +- `scope` (optional, type `String[]`) - the list of scopes where the variation is applicable. When not provided, it assumes all available scopes. Available options: `block`, `inserter`. + #### transforms (optional) - **Type:** `Array` diff --git a/packages/blocks/src/api/registration.js b/packages/blocks/src/api/registration.js index 6a82d0f90a7a4f..140c05622ab1ad 100644 --- a/packages/blocks/src/api/registration.js +++ b/packages/blocks/src/api/registration.js @@ -71,7 +71,7 @@ import { DEPRECATED_ENTRY_KEYS } from './constants'; * * @property {string} name The unique and machine-readable name. * @property {string} title A human-readable variation title. - * @property {string} description A detailed variation description. + * @property {string} [description] A detailed variation description. * @property {WPIcon} [icon] An icon helping to visualize the variation. * @property {boolean} [isDefault] Indicates whether the current variation is * the default one. Defaults to `false`.