Docs: Add tutorial explaining how to use block variations API

[gziolo]

Description

Originally raised in #16283.

Based on the examples shared in #20068 and e2e tests created in #20286 we could create tutorials presenting how to make the most using the block variations API.

Examples

Recorded screencasts contain unstable API but included code examples are up to date.

1. Registers the variation with the inner blocks to apply from the block variation picker using scope limited to the block:

wp.blocks.registerBlockVariation( 'core/columns', { name: 'custom', title: 'Smiley', isDefault: true, innerBlocks: [ [ 'core/column' ], [ 'core/column' ], [ 'core/column' ], [ 'core/column' ] ], icon: 'smiley', scope: [ 'block' ] } );

2. Registers the variation with the inner blocks to apply from the inserter using scope limited to the inserter:

wp.blocks.registerBlockVariation( 'core/columns', { name: 'custom', title: 'Smiley', isDefault: true, innerBlocks: [ [ 'core/column' ], [ 'core/column' ], [ 'core/column' ], [ 'core/column' ] ], icon: 'smiley', scope: [ 'inserter' ] } );

2. Registers two variations with initial attributes to apply from the inserter directly:

wp.blocks.registerBlockVariation( 'core/heading', { name: 'green-text', title: 'Green Text', description: 'This block has green text. It overrides the default description.',  attributes: { content: 'Green Text', textColor: 'vivid-green-cyan' }, icon: 'palmtree', scope: [ 'inserter' ] } );
wp.blocks.registerBlockVariation( 'core/heading', { name: 'red-text', title: 'Red Text', attributes: { content: 'Red Text', level: 3, textColor: 'vivid-red' }, icon: 'smiley', scope: [ 'inserter' ] } );

3. Registers a variation which allows changing the default style variation:

wp.blocks.registerBlockVariation( 'core/quote', { name: 'large', title: 'Large Quote', isDefault: true, attributes: { className: 'is-style-large' }, icon: 'palmtree', scope: [ 'inserter' ] } );

[gziolo]

It's currently documented in the following places:

• https://developer.wordpress.org/block-editor/developers/block-api/block-registration/#variations-optional
• https://make.wordpress.org/core/2020/02/27/introduce-block-variations-api/

There is also a very helpful post from @richtabor on his blog: https://richtabor.com/block-variations/

[jorgefilipecosta]

I'm closing the issue for now as it seems variations are already documented.

[aacassandra]

Hi everyone, im trying to implement the code as above

1. scope as block, not work
2. scope as inserter is work

wp.blocks.registerBlockVariation( 'core/columns', {
	name: 'custom',
	title: 'Smiley',
	isDefault: true,
	innerBlocks: [ [ 'core/column' ], [ 'core/column' ], [ 'core/column' ], [ 'core/column' ] ],
	icon: 'smiley',
	scope: [ 'block' ],
} );

why not work? is there something wrong with this code?

For variation like social-link, how do we get into sidebar blocks? any examples for this or documentation?
@gziolo

[coreyworrell]

@aacassandra it looks like there is no a scope option for transform which adds the sidebar option there. Not sure what block scope is supposed to do.

block – Used by blocks to filter specific block variations. Mostly used in Placeholder patterns like Columns block.

Not very clear what that means.

I also noticed though that if you specify { attributes: { className: 'is-style-whatever' } } that you can no longer add additional classes via the Advanced sidebar panel, or else it "deactivates" the variation.

[Humanify-nl]

Sorry to add this to a closed issue. But I found it is very elusive in the documentation how to use the variations picker if block scope is chosen. I had to find it digging into the core src, comparing groups & columns.

For example, when creating variations on the core group block, the variations picker is not found. Yet, it allows me to choose block scope, while this doesnt do anything (because there is no <__experimentalBlockVariationPicker /> in core/group).

Would it be helpful if this is mentioned somewhere in the docs? (if you choose block scope, make sure there is a variation picker)

[gziolo]

Would it be helpful if this is mentioned somewhere in the docs? (if you choose block scope, make sure there is a variation picker)

Yes, that sounds like a good clarification to include. It looks like there are only 2 core blocks that have it integrated:

• Columns
• Query Loop

@ntsekouras, can you confirm?

[ntsekouras]

Yes, that sounds like a good clarification to include. It looks like there are only 2 core blocks that have it integrated:
Columns
Query Loop
@ntsekouras, can you confirm?

I can confirm that. I'll open a PR to update the docs a bit.