Background
In WordPress 5.8, the API An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. for registering block Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. variations was introduced, bringing new capabilities to developers. However, it soon became evident that generating these variations had a non-trivial performance cost, particularly when used for template-part
and navigation-link
in WordPress 5.9 and post-terms
in WordPress 6.1.
The core Core is the set of software required to run WordPress. The Core Development Team builds WordPress. of this issue was that these variations were being generated on every page load due to their registration using the init
hook. This was inefficient, as the variations were only needed in the editor or for returning block data in the REST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/.. This redundancy in loading led to unnecessary performance overhead, underscoring the need for a more streamlined approach.
What is changed
In WordPress 6.5, we’ve introduced $variation_callback
as a new attribute in WP_Block_Type. This feature allows developers to register variation-building functions as callbacks rather than building variations before registration. With this approach, variations are constructed from this callback only when they are accessed for the first time.
Consequently, the WP_Block_Type::get_variations()
method was introduced as the primary means to access variations. This method skillfully checks for a callback in variation_callback
and triggers the callback, but only during the first access of the variations. This efficient approach ensures that the callback is executed just once, optimizing performance by avoiding redundant processing on subsequent accesses. Additionally, this strategy aids in lazy loading, as variations no longer need to be loaded during registration.
Moreover, it integrates the get_block_type_variations
filter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output., which provides a versatile mechanism for developers to modify the resulting variations. These enhancements reflect WordPress’s ongoing commitment to improving its developer-centric features and maintaining compatibility with existing functionalities.
In WordPress 6.5, a significant alteration is made to WP_Block_Type::$variations
. The notable change involved transitioning the visibility of variations from public to private. This modification was specifically designed to necessitate the use of the PHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher magic __get
method for accessing variations only via WP_Block_Type::get_variations()
.
Please note that the modifications to WP_Block_Type::$variations
may introduce certain limitations that require developer attention. These are detailed in the “Developer Action” section below.
Lazy loading variations using variation_callback
To facilitate the lazy loading of variations, we can replace the traditional method of loading variations with a callback. This approach is exemplified in the case of Gutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ PR #56952, which is aimed at enhancing performance.
Previously, template-part
variations were loaded as follows:
register_block_type_from_metadata(
__DIR__ . '/template-part',
array(
'render_callback' => 'render_block_core_template_part',
'variations' => build_template_part_block_variations(),
)
);
To optimize this, we have transitioned to using a variation_callback
:
register_block_type_from_metadata(
__DIR__ . '/template-part',
array(
'render_callback' => 'render_block_core_template_part',
'variation_callback' => 'build_template_part_block_variations',
)
);
It’s important to note that if both variations
and variation_callback
are defined, like in the following example:
register_block_type_from_metadata(
'block-name',
array(
'variations' => array( 'test-variation' => array( 'test-variations' ) ),
'variation_callback' => 'get_test_variations',
)
);
In this scenario, the variations array takes precedence, and the variation_callback
will not be called.
Developer action required
With the addition of variations
to the existing magic function framework in WP_Block_Type
, a significant limitation emerges: the inability to modify variations by reference directly. This change impacts how variations were traditionally updated.
Consider these examples of updating variations by reference, which will no longer function as expected in WordPress 6.5:
$block_type->variations[] = array( 'test' => array( 'test' ) );
// or
$block_type->variations['example1'] = array( 'test' );
To overcome this limitation in WordPress 6.5, a workaround involving a temporary variable can be used. Here’s how you can modify the temporary variable and then reassign it back to $block_type->variations
:
$variations = $block_type->variations;
$variations[] = array( 'test' => array( 'test' ) );
$block_type->variations = $variations;
// Similarly
$variations = $block_type->variations;
$variations['example1'] = array( 'test' );$block_type->variations = $variations;
Alternatively, to align with the latest updates and best practices in WordPress, you might consider using the get_block_type_variations
filter (reference link).
Utilizing the get_block_type_variations
filter for enhanced variation management
The introduction of the get_block_type_variations
filter in WordPress 6.5 allows for the manipulation and customization of the variations array, providing greater flexibility in handling block variations.
Here’s an implementation example of the get_block_type_variations
filter:
function modify_block_type_variations( $variations, $block_type ) {
// Example: Add a new variation
if ( 'block-name' === $block_type->name ) {
$variations[] = array(
'name' => 'new-variation',
'title' => __( 'New Variation', 'textdomain' ),
// Other variation properties...
);
}
return $variations;
}
add_filter( 'get_block_type_variations', 'modify_block_type_variations', 10, 2 );
In this example, the modify_block_type_variations
function is hooked to the get_block_type_variations
filter. It checks if the block type is ‘block-name
‘ and then adds a new variation to the variations array. This function then returns the modified variations array.
By leveraging this filter, developers can dynamically adjust the variations according to specific requirements or conditions.
Please refer to #59969 for additional details on these changes.
Props to @adamsilverstein, @westonruter, @joemcgill, and @leonnugraha for reviewing this post.
#6-5, #block-api, #dev-notes, #dev-notes-6-5