Make WordPress Core

Opened 5 weeks ago

Last modified 4 days ago

#61280 new enhancement

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

Reported by: bernhard-reiter's profile Bernhard Reiter Owned by:
Milestone: 6.7 Priority: normal
Severity: normal Version:
Component: Editor Keywords: has-patch
Focuses: Cc:

Description (last modified by 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.

Change History (8)

This ticket was mentioned in PR #6668 on WordPress/wordpress-develop by @Bernhard Reiter.


4 weeks ago
#1

  • Keywords has-patch added

TODO:

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

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

#2 @Bernhard Reiter
4 weeks ago

  • Description modified (diff)
  • Summary changed from Block Variations: Allow server-side registration via variations.php or .json to Block Variations: Allow server-side registration via variations.php

#3 @Bernhard Reiter
4 weeks ago

  • Description modified (diff)

#4 @oglekler
3 weeks ago

  • Component changed from General to Editor

#5 @gziolo
3 weeks ago

  • Milestone changed from 6.6 to 6.7

Moving to WordPress 6.7 release cycle.

@Bernhard Reiter commented on PR #6668:


6 days ago
#6

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

👍

@Bernhard Reiter commented on PR #6668:


6 days ago
#7

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.

@gziolo commented on PR #6668:


4 days ago
#8

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.

Note: See TracTickets for help on using tickets.