Blocks: Add new render field to block.json

[gziolo]

What?

A technical prototype for Editor: Consider adding render property for block types in WordPress Trac. I will add tests and documentation only when people find this proposal useful.

Related to the proposal #41289 from @ryanwelcher to add --is-dynamic flag to @wordpress/create-block.

Why?

See comment from @spacedmonkey #13693 (comment).

Current the render callback is a function call. How would it work as a file? Why not make it renderTemplate but still allow for renderCallback. Function calls, should be a method in a class or be namespaced, which wouldn't really work in another file.

ACF blocks, has a rendercallback / render template in it's block definitions.

There is also another thread started by @spacedmonkey in #13693 (comment) which expands on this topic.

How?

New render field in block.json file that accepts a string value.

The path to the file should be prefixed with file: and be relative to the block.json file in the build (target) folder. It's exactly the same pattern as used with scripts and styles in block.json.

PHP file that renders the template for the block can use 3 variables that are the same as render_callback takes as params:

• $attributes (array) - block attributes.
• $content (string) - block default content.
• $block (WP_Block) - block instance.

Important note: I refactored the Archive block to use the new render field in block.json only for testing purposes. We rather won't do it as using function declarations is problematic with this approach because template files sometimes need to load several times for a given block type. When that happens, then we encounter a function redeclaration error. Removed from PR.

Testing Instructions

Ensure that the temporarily refactored Archive blocks still work as before.

To test with custom blocks you need to add render field in the block.json file.

Example:

src/block.json

{
    "name": "test/my-block",
    "render": "file:./render.php"
}

src/render.php

<div <?php echo get_block_wrapper_attributes(); ?>>
    <?php echo $attributes['text']; ?>
</div>

[luisherranz]

This is very interesting 🙂

I'm trying to figure out what would be the DX of adding functions without facing the redeclaration error:

• Move the logic to a different file and use require.
• Move the function to another file and use require_once.
• Use function_exists.

  if ( ! function_exists( 'my_dynamic_block_logic' ) ) {
    function my_dynamic_block_logic( $params ) use ( $attributes ) {
      // ... logic here
    }
  }
  
  my_dynamic_block_logic( 123 );

• Use anonymous functions

  $my_dynamic_block_logic = function ( $params ) use ( $attributes ) {
    // ... logic here
  }
  
  $my_dynamic_block_logic( 123 );

Is there any other option?

[ryanwelcher]

IMO, there really shouldn't be any function declarations in the template file at all. This file can be conceptually compared to files that would be used with get_template_part() in that they usually only contain function calls and markup.

This is definitely a case of making sure there is proper documentation and best practices around this feature but I think that any functionality this block requires is better defined in the plugin.php or functions.php file - depending on whether the block is registered from a theme or plugin.

[luisherranz]

I think that any functionality this block requires is better defined in the plugin.php or functions.php file

Yeah, I guess that makes sense from a WordPress point of view.

Sorry, I was thinking from the perspective of devs without much WP/PHP background that want to componentize their markup logic, so they just start adding functions to those entry points. And probably thinking of a future where just adding a bunch of block.json files is enough (no plugin.php nor functions.php required) 😅

[noisysocks]

Is there any other option?

Could use a namespace? Agree with @ryanwelcher though that not putting declarations in these files feels more WordPress-ey.

[gziolo]

The example included in the Blocks ACF plugin doesn't contain any function and class declarations:
https://www.advancedcustomfields.com/resources/blocks/#introduction

IMO, there really shouldn't be any function declarations in the template file at all. This file can be conceptually compared to files that would be used with get_template_part() in that they usually only contain function calls and markup.

So that explanation makes perfect sense here. It's also similar to what you can observe in templates for themes, for example:

https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-content/themes/twentyeleven/single.php

[mtias]

The name is a bit weird to me. What would be the relationship between a renderTemplate field and a view or frontend field as discussed in WordPress/block-interactivity-experiments#37 ?

[ryanwelcher]

The name is a bit weird to me. What would be the relationship between a renderTemplate field and a view or frontend field as discussed in WordPress/block-hydration-experiments#37 ?

@mtias IMO as a PHP-first developer, renderTemplate aligns with the idea of a file that we would require inside the render_callback function - here's an example from one of my last streams.

It is also closer in naming to get_template_part() which again, resonates with developers used to including templates into PHP files in WordPress.

[mtias]

The semantics of renderTemplate doesn't make much sense next to edit and save because those also represent templates

[gziolo]

The semantics of renderTemplate doesn't make much sense next to edit and save because those also represent templates

Interesting observation. I didn't consider that at all. I guess the render_callback method that existed from the beginning is misleading here. When writing PHP code, that name isn't that problematic because edit and save exist as concepts only on the client side. We already have view reserved in the block.json file for JavaScript that should be loaded only on the frontend. Maybe viewTemplate could be a good alternative? As of today, it would support PHP templates only. If one day, we will figure out the format that works cross-platform as summarized in Universal blocks and block hydration, then we just wire it with viewTemplate. What do you think?

[mtias]

render_callback happens directly in the PHP context so it makes more sense. If we are modelling something for block.json we need to take all environments into account for API clarity. In the context of edit, save, and view, perhaps render would be an ok designation, or server otherwise. I think "view" should eventually coalesce for server / client, so not opposed to exploring something where view could be a "file:./template.php" or a JS function. In some of the single file explorations from @luisherranz we have that dichotomy present.

[gziolo]

. I think "view" should eventually coalesce for server / client, so not opposed to exploring something where view could be a "file:./template.php" or a JS function. In some of the single file explorations from @luisherranz we have that dichotomy present.

That's an interesting take. We have only viewScript at the moment. We have already received some feedback that viewStyle would be helpful as well. Here, we would have something closer to viewRender or viewServer. We could definitely consolidate all that under one view field in the block.json and handle everything behind the scenes:

{
    "view": [ "file:./template.php", "file:./view.js", "file:./view.css" ]
}

It would be less straightforward when passing script or style handles, but we could always run some detection whether this handle is for a style, a script, or both.

I would love to hear what @luisherranz thinks about all these ideas in the context of the block hydration experiments.

[luisherranz]

I would love to hear what @luisherranz thinks about all these ideas in the context of the block hydration experiments.

Categorizing the PHP rendering as view feels a bit confusing to me because Gutenberg uses that term to designate what is sent to the browser. It's true that in the block hydration experiments, we're trying to get rid of save. But it's not clear yet to me if/how that would happen, especially for dynamic blocks.

Today, technically speaking, the PHP rendering is the dynamic equivalent of the save.js, but the save action (saving to the database) doesn't apply to PHP. On the other hand, the render action describes what is happening on the PHP side. So I don't have a strong opinion at the moment, and I'm not sure yet if the PHP rendering will fit better in the save or the view category, or if it will be better to rename save to render instead in the future.

Anyway, if I had to vote, I'd use the render name for now to keep the status quo, knowing that we can rename it in a future block.json version (along with other inconsistencies), but I'll also be happy with any other decision 🙂

[gziolo]

Anyway, if I had to vote, I'd use the render name for now to keep the status quo, knowing that we can rename it in a future block.json version (along with other inconsistencies), but I'll also be happy with any other decision 🙂

It's only processed on the server, so we shouldn't be worried about renaming that later and even keeping it backward-compatible. I'm fine with using render in block.json. It's also one of the options that @mtias mentioned in his comment.

Today, technically speaking, the PHP rendering is the dynamic equivalent of the save.js, but the save action (saving to the database) doesn't apply to PHP.

It's more nuanced. We have more places these days where render_callback uses the content produced by save and further processes it before sending it to the user.

[gziolo]

I updated this branch upon the feedback received. I included documentation changes necessary for the new render field in the block.json file that'd be available starting from WordPress 6.1.0 in core.

Before merging this PR, I will have to remove changes from the Archive block, as noted in the description. Everything else should be ready for the final feedback.

[gziolo]

I removed the refactoring applied to the Archive block that was presenting the idea. I think this PR received enough feedback so let's make the final decision whether it's good enough to get included in WordPress 6.1.

[fabiankaegy]

I think this API is very valuable. In the scaffolding we use for custom block development we already have a similar abstraction which we could drop in favor of the core approach if this were to land.

Also, thank you @gziolo for writing such great documentation for this feature! :) It is really appreciated <3

[adamziel]

This looks and works great, thank you @gziolo!

Here's a caveat for a follow-up PR: The Gutenberg plugin build process does not bundle the render.php files in the build directory, which means the render scripts cannot be used with core blocks yet.

[gziolo]

Here's a caveat for a follow-up PR: The Gutenberg plugin build process does not bundle the render.php files in the build directory, which means the render scripts cannot be used with core blocks yet.

We don't necessarily need to immediately refactor any of the existing core blocks to use render. However, we definitely can update the webpack config to read this new field in block.json to discover the exact file path used. This way, we would no longer need to harcode the name of the PHP file processed during the build and remember to update the list of dynamic blocks in:

gutenberg/lib/blocks.php

Line 47 in 1d778aa

'block_names' => array(

[gziolo]

I landed the current version, but I'd like to double-check what do you think about making it possible to pass also the callback name in the render field like we do it today with render_callback on the server with register_block_type?

[Rahe]

Hello,

Allowing multiple values for this render attribute could be possible ? and use an get_template_part like function ?

This will allow to redefine Dynamic blocs, even core ones, within themes.
Like ["theme:./blocs/my-template.php","./render.php"]
In this exemple the theme file on child/parent will be searched, then fallback on plugin file.

This will allow to have a template hierarchy like rendering process for Dynamic blocs.

Nicolas,

[gziolo]

Allowing multiple values for this render attribute could be possible ? and use an get_template_part like function ?

Not at the moment. Similar to how render_callback with register_block_type works today, you can pass only a single file path.

This will allow to redefine Dynamic blocs, even core ones, within themes. Like ["theme:./blocs/my-template.php","./render.php"] In this exemple the theme file on child/parent will be searched, then fallback on plugin file.

This will allow to have a template hierarchy like rendering process for Dynamic blocs.

Interesting idea. You can get close to that with WP hook. See block_type_metadata. This way, you can provide your templates within a plugin or theme by overriding the value provided in render. Although the challenge would be that the path is relative to block.json file.

[gziolo]

I backported this new API to WordPress core with https://core.trac.wordpress.org/changeset/54132.