Block Variations: Allow server-side registration via variations.php

[Bernhard Reiter]

As of WordPress 6.5, the ​recommended way to register Block Variations for a given block is via its variations_callback:

register_block_type_from_metadata(
    __DIR__ . '/template-part',
    array(
        'render_callback'    => 'render_block_core_template_part',
        'variation_callback' => 'build_template_part_block_variations',
    )
);

As the above example shows, this is somewhat similar to adding a render_callback for a dynamic block. The latter can alternatively be provided via a single PHP file -- typically called render.php -- that is ​specified via the `render` field in `block.json`.

variations.php

For developer experience, it would thus be beneficial to allow specifying the name of a PHP file in block.json that contains code to generate all known variations of that block.

Unlike [54132], we cannot simply introduce a variations field to hold that filename, as the variations field already exists; it is used to hold the list of block variations. We can however allow variations to accept a string, which will we can then interpret as the aforementioned filename.

variations.json

As a potential follow-up, it might be possible to point the variations field to a JSON file instead, as some variations are statically defined (and don't need to run any PHP code). In those cases, they are currently often defined on the client side (see e.g. ​Social Icon block variations).

As we're working to expand Block Variations to be better integrated and supported on the server side (e.g. ​automatic class name generation for block variations), they will need to be registered there to fully benefit from those new, server-side, features. Allowing a JSON format will enable block authors to migrate existing ("static") JS files that they use for variation registration more easily.

TODO:

• [ ] Unit test coverage
• [ ] Schemas?
• [ ] Docs?

Trac ticket: https://core.trac.wordpress.org/ticket/61280

[gziolo]

Moving to WordPress 6.7 release cycle.

That looks like nice enhancement. We will need some changes also on the editor side:

• extend block.json schema to cover the string value

That's handled in ​https://github.com/WordPress/gutenberg/pull/62092. I'm going to extend that PR to also implement the logic from this PR in the 6.7 compat layer, and to include changes to block variation docs.

• add simple logic that ignores the file path when consuming the metadata from JS as it can’t process PHP file - for WordPress context it’s going to be handled on the server anyway

👍

I had one minor comment regarding enforcing file: prefix for paths. However, conceptually everything looks great. I like how this proposal abstracts the usage of lazy evaluated definition of block variations.

Thank you! I ​changed the unit test ​according to your suggestion 😊 (The code I was using for the variations field was copied from the render field, so it already had a call to remove_block_asset_path_prefix, which processed the file: prefix.)

Since we're still in Beta, I'm planning to wait for RC1 (after which a branch for 6.6 should be created) before I commit this change to trunk.

It even made me wonder, whether we should do a similar trick with variations_callback for the block variations defined as an array in block.json.

You mean so that all variations aren't loaded and built right away if they're specified in block.json? 🤔 Yeah, we could do that. FWIW, I was planning to allow passing a JSON file as variations value, which would allow block authors to simply move a static variations definition to a separate file. This will likely require code that's quite similar.

Since we're still in Beta, I'm planning to wait for RC1 (after which a branch for 6.6 should be created) before I commit this change to trunk.

Yes, it sounds like a great plan.

You mean so that all variations aren't loaded and built right away if they're specified in block.json? 🤔 Yeah, we could do that. FWIW, I was planning to allow passing a JSON file as variations value, which would allow block authors to simply move a static variations definition to a separate file. This will likely require code that's quite similar.

Yes, that would be an enhancement specific only to block.json integration. Referencing a JSON file also sounds like a good addition. The only caveat is that it will need some coordination with WP-CLI team to ensure that translations are still handled for variations when moved to another JSON file.

[noisysocks]

@bernhard-reiter: OK to commit this?

[Bernhard Reiter]

@noisysocks Apologies, I missed your ping! I've only recently landed the ​GB PR. I'll need to review the wordpress-develop one to make sure it doesn't need any changes carried over.

Thank you @gziolo!

I'll have to re-review this PR now that I've landed the ​GB counterpart, to see if any changes need carrying over.

I'll have to re-review this PR now that I've landed the ​GB counterpart, to see if any changes need carrying over.

Alright, looks like it doesn't need any changes. I'll land it 😊

[Bernhard Reiter]

In 58801:

block.json: Allow passing PHP filename as variations field.

Previously, the variations field in a block.json file could be used to provide a static list of the block's variations (i.e., an array). Alternatively, the block's variation_callback could be set during server-side block registration to point to a PHP function to generate those variations.

This changeset makes it so that the block.json variations field can be alternatively set to a string, which will be interpreted as the filename of a PHP file that generates the variations.

It is loosely modeled after [54132], which introduced the render field for block.json, as a way to point to a PHP file instead of providing a render_callback.

Props bernhard-reiter, gziolo.
Fixes #61280.

Committed to Core in https://core.trac.wordpress.org/changeset/58801.

Thanks for committing this early in the 6.7 cycle ❤️