diff --git a/docs/reference-guides/block-api/block-variations.md b/docs/reference-guides/block-api/block-variations.md index 019c73fa4507c..96930dc6b9b62 100644 --- a/docs/reference-guides/block-api/block-variations.md +++ b/docs/reference-guides/block-api/block-variations.md @@ -1,58 +1,82 @@ # Variations -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. +The Block Variations API allows you to define multiple versions (variations) of a block. A block variation differs from the original block by a set of initial attributes or inner blocks. When you insert the block variation into the Editor, these attributes and/or inner blocks are applied. -A great way to understand this API better is by using the `embed` block as an example. The numerous existing variations for embed (WordPress, Youtube, etc..) share the same functionality for editing, saving, and so on, but their basic difference is the `providerNameSlug` attribute's value, which defines the provider that needs to be used. +Variations are an excellent way to create iterations of existing blocks without building entirely new blocks from scratch. + +To better understand this API, consider the Embed block. This block contains numerous variations for each type of embeddable content (WordPress, Youtube, etc.). Each Embed block variation shares the same underlying functionality for editing, saving, and so on. Besides the name and descriptive information, the main difference is the `providerNameSlug` attribute. Below is a simplified example of the variations in the Embed block. View the [source code](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/embed/variations.js) for the complete specification. -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. ```js variations: [ { name: 'wordpress', - isDefault: true, - title: __( 'WordPress' ), - description: __( 'Code is poetry!' ), - icon: WordPressIcon, + title: 'WordPress', + description: __( 'Embed a WordPress post.' ), attributes: { providerNameSlug: 'wordpress' }, }, { - name: 'google', - title: __( 'Google' ), - icon: GoogleIcon, - attributes: { providerNameSlug: 'google' }, - }, - { - name: 'twitter', - title: __( 'Twitter' ), - icon: TwitterIcon, - attributes: { providerNameSlug: 'twitter' }, - keywords: [ __('tweet') ], + name: 'youtube', + title: 'YouTube', + description: __( 'Embed a YouTube video.' ), + attributes: { providerNameSlug: 'youtube' }, }, ], ``` -An object describing a variation defined for the block type can contain the following fields: +## Defining a block variation + +A block variation is defined by an object that 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. -- `category` (optional, type `string`) - A category classification, used in search interfaces to arrange block types by category. +- `name` (type `string`) – A unique and machine-readable name. +- `title` (optional, type `string`) – A human-readable variation title. +- `description` (optional, type `string`) – A human-readable variation description. +- `category` (optional, type `string`) - A category classification used in search interfaces to arrange block types by category. +- `keywords` (optional, type `string[]`) - An array of terms (which can be translated) that help users discover the variation while searching. - `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. For more details about the `example` object [see here](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#example-optional). -- `scope` (optional, type `WPBlockVariationScope[]`) - the list of scopes where the variation is applicable. When not provided, it defaults to `block` and `inserter`. Available options: - - `inserter` - Block Variation is shown on the inserter. - - `block` - Used by blocks to filter specific block variations. `Columns` and `Query Loop` blocks have such variations and are passed to the [experimental BlockVariationPicker](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-variation-picker/README.md) component, which is handling the displaying of variations and the ability to select one from them. - - `transform` - Block Variation will be shown in the component for Block Variations transformations. -- `keywords` (optional, type `string[]`) - An array of terms (which can be translated) that help users discover the variation while searching. -- `isActive` (optional, type `Function|string[]`) - This can be a function or an array of block attributes. Function that accepts a block's attributes and the variation's attributes and determines if a variation is active. This function doesn't try to find a match dynamically based on all block's attributes, as in many cases some attributes are irrelevant. An example would be for `embed` block where we only care about `providerNameSlug` attribute's value. We can also use a `string[]` to tell which attributes should be compared as a shorthand. Each attributes will be matched and the variation will be active if all of them are matching. +- `example` (optional, type `Object`) – Provides structured data for the block preview. Set to `undefined` to disable the preview. See the [Block Registration API](/docs/reference-guides/block-api/block-registration.md#example-optional) for more details. +- `scope` (optional, type `WPBlockVariationScope[]`) - Defaults to `block` and `inserter`. The list of scopes where the variation is applicable. Available options include: + - `block` - Used by blocks to filter specific block variations. `Columns` and `Query` blocks have such variations, which are passed to the [experimental BlockVariationPicker](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-variation-picker/README.md) component. This component handles displaying the variations and allows users to choose one of them. + - `inserter` - Block variation is shown on the inserter. + - `transform` - Block variation is shown in the component for variation transformations. +- `isDefault` (optional, type `boolean`) – Defaults to `false`. Indicates whether the current variation is the default one (details below). +- `isActive` (optional, type `Function|string[]`) - A function or an array of block attributes that is used to determine if the variation is active when the block is selected. The function accepts `blockAttributes` and `variationAttributes` (details below). + +
name
, but this is not recommended. A unique name
allows the Editor to differentiate between your variation and others that may exist. It also allows your variation to be unregistered as needed and has implications for the isDefault
settings (details below).
+