Blocks: Add new render field to block.json (#42430)

* Blocks: Add new `renderTemplate` field to `block.json`

* Update lib/compat/wordpress-6.1/blocks.php

Co-authored-by: Ari Stathopoulos <aristath@gmail.com>

Co-authored-by: Ari Stathopoulos <aristath@gmail.com>

docs/reference-guides/block-api/block-metadata.md

@@ -46,14 +46,15 @@ Starting in WordPress 5.8 release, we encourage using the `block.json` metadata
 			"title": "Example",
 			"attributes": {
 				"message": "This is an example!"
-			},
+			}
 		}
 	],
-	"editorScript": "file:./build/index.js",
-	"script": "file:./build/script.js",
-	"viewScript": "file:./build/view.js",
-	"editorStyle": "file:./build/index.css",
-	"style": "file:./build/style.css"
+	"editorScript": "file:./index.js",
+	"script": "file:./script.js",
+	"viewScript": "file:./view.js",
+	"editorStyle": "file:./index.css",
+	"style": "file:./style.css",
+	"render": "file:./render.php"
 }
 ```
 
@@ -83,7 +84,7 @@ This function takes two params relevant in this context (`$block_type` accepts m
 
 -   `$block_type` (`string`) – path to the folder where the `block.json` file is located or full path to the metadata file if named differently.
 -   `$args` (`array`) – an optional array of block type arguments. Default value: `[]`. Any arguments may be defined. However, the one described below is supported by default:
-    -   `$render_callback` (`callable`) – callback used to render blocks of this block type.
+    -   `$render_callback` (`callable`) – callback used to render blocks of this block type, it's an alternative to the `render` field in `block.json`.
 
 It returns the registered block type (`WP_Block_Type`) on success or `false` on failure.
 
@@ -432,11 +433,11 @@ See the [the example documentation](/docs/reference-guides/block-api/block-regis
 
 ### Variations
 
-- Type: `object[]`
-- Optional
-- Localized: Yes (`title`, `description`, and `keywords` of each variation only)
-- Property: `variations`
-- Since: `WordPress 5.9.0`
+-   Type: `object[]`
+-   Optional
+-   Localized: Yes (`title`, `description`, and `keywords` of each variation only)
+-   Property: `variations`
+-   Since: `WordPress 5.9.0`
 
 ```json
 {
@@ -469,7 +470,7 @@ See the [the variations documentation](/docs/reference-guides/block-api/block-va
 -   Property: `editorScript`
 
 ```json
-{ "editorScript": "file:./build/index.js" }
+{ "editorScript": "file:./index.js" }
 ```
 
 Block type editor script definition. It will only be enqueued in the context of the editor.
@@ -482,7 +483,7 @@ Block type editor script definition. It will only be enqueued in the context of
 -   Property: `script`
 
 ```json
-{ "script": "file:./build/script.js" }
+{ "script": "file:./script.js" }
 ```
 
 Block type frontend and editor script definition. It will be enqueued both in the editor and when viewing the content on the front of the site.
@@ -496,7 +497,7 @@ Block type frontend and editor script definition. It will be enqueued both in th
 -   Since: `WordPress 5.9.0`
 
 ```json
-{ "viewScript": "file:./build/view.js" }
+{ "viewScript": "file:./view.js" }
 ```
 
 Block type frontend script definition. It will be enqueued only when viewing the content on the front of the site.
@@ -511,7 +512,7 @@ _Note: An option to pass also an array of view scripts exists since WordPress `6
 -   Property: `editorStyle`
 
 ```json
-{ "editorStyle": "file:./build/index.css" }
+{ "editorStyle": "file:./index.css" }
 ```
 
 Block type editor style definition. It will only be enqueued in the context of the editor.
@@ -526,20 +527,50 @@ _Note: An option to pass also an array of editor styles exists since WordPress `
 -   Property: `style`
 
 ```json
-{ "style": "file:./build/style.css" }
+{ "style": "file:./style.css" }
 ```
 
 Block type frontend and editor style definition. It will be enqueued both in the editor and when viewing the content on the front of the site.
 
 _Note: An option to pass also an array of styles exists since WordPress `5.9.0`._
 
+### Render
+
+-   Type: `WPDefinedPath` ([learn more](#wpdefinedpath))
+-   Optional
+-   Localized: No
+-   Property: `render`
+-   Since: `WordPress 6.1.0`
+
+```json
+{ "render": "file:./render.php" }
+```
+
+PHP file to use when rendering the block type on the server to show on the front end. The following variables are exposed to the file:
+
+-   `$attributes` (`array`): The block attributes.
+-   `$content` (`string`): The block default content.
+-   `$block` (`WP_Block`): The block instance.
+
 ## Assets
 
-### `WPDefinedAsset`
+### `WPDefinedPath`
+
+The `WPDefinedPath` type is a subtype of string, where the value represents a path to a JavaScript, CSS or PHP file relative to where `block.json` file is located. The path provided must be prefixed with `file:`. This approach is based on how npm handles [local paths](https://docs.npmjs.com/files/package.json#local-paths) for packages.
+
+**Example:**
+
+In `block.json`:
 
-The `WPDefinedAsset` type is a subtype of string, where the value represents a path to a JavaScript or CSS file relative to where `block.json` file is located. The path provided must be prefixed with `file:`. This approach is based on how npm handles [local paths](https://docs.npmjs.com/files/package.json#local-paths) for packages.
+```json
+{
+	"render": "file:./render.php"
+}
+```
+
+### `WPDefinedAsset`
 
-An alternative would be a script or style handle name referencing an already registered asset using WordPress helpers.
+It extends `WPDefinedPath` for JavaScript and CSS files. An alternative to the file path would be a script or style handle name referencing an already registered asset using WordPress helpers.
 
 **Example:**
 
@@ -570,16 +601,16 @@ The definition is stored inside separate PHP file which ends with `.asset.php` a
 **Example:**
 
 ```
-block.json
 build/
+├─ block.json
 ├─ index.js
 └─ index.asset.php
 ```
 
 In `block.json`:
 
 ```json
-{ "editorScript": "file:./build/index.js" }
+{ "editorScript": "file:./index.js" }
 ```
 
 In `build/index.asset.php`:

lib/compat/wordpress-6.1/blocks.php

@@ -205,3 +205,48 @@ function gutenberg_block_type_metadata_multiple_view_scripts( $metadata ) {
 	return $metadata;
 }
 add_filter( 'block_type_metadata', 'gutenberg_block_type_metadata_multiple_view_scripts' );
+
+/**
+ * Register render template for core blocks if handling is missing in WordPress core.
+ *
+ * @since 6.1.0
+ *
+ * @param array $settings Array of determined settings for registering a block type.
+ * @param array $metadata Metadata provided for registering a block type.
+ *
+ * @return array Array of settings for registering a block type.
+ */
+function gutenberg_block_type_metadata_render_template( $settings, $metadata ) {
+	if ( empty( $metadata['render'] ) || isset( $settings['render_callback'] ) ) {
+		return $settings;
+	}
+
+	$template_path = wp_normalize_path(
+		realpath(
+			dirname( $metadata['file'] ) . '/' .
+			remove_block_asset_path_prefix( $metadata['render'] )
+		)
+	);
+
+	// Bail if the file does not exist.
+	if ( ! file_exists( $template_path ) ) {
+		return $settings;
+	}
+	/**
+	 * Renders the block on the server.
+	 *
+	 * @param array    $attributes Block attributes.
+	 * @param string   $content    Block default content.
+	 * @param WP_Block $block      Block instance.
+	 *
+	 * @return string Returns the block content.
+	 */
+	$settings['render_callback'] = function( $attributes, $content, $block ) use ( $template_path ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
+		ob_start();
+		require $template_path;
+		return ob_get_clean();
+	};
+
+	return $settings;
+}
+add_filter( 'block_type_metadata_settings', 'gutenberg_block_type_metadata_render_template', 10, 2 );

schemas/json/block.json

@@ -574,6 +574,10 @@
 					}
 				}
 			}
+		},
+		"render": {
+			"type": "string",
+			"description": "Template file loaded on the server when rendering a block."
 		}
 	},
 	"required": [ "name", "title" ],