diff --git a/docs/reference-guides/block-api/block-metadata.md b/docs/reference-guides/block-api/block-metadata.md index 9967579d22dcf..5d3f387204645 100644 --- a/docs/reference-guides/block-api/block-metadata.md +++ b/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,8 +601,8 @@ 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 ``` @@ -579,7 +610,7 @@ build/ In `block.json`: ```json -{ "editorScript": "file:./build/index.js" } +{ "editorScript": "file:./index.js" } ``` In `build/index.asset.php`: diff --git a/lib/compat/wordpress-6.1/blocks.php b/lib/compat/wordpress-6.1/blocks.php index cbbf676cfcb90..5fdbe11dc08ed 100644 --- a/lib/compat/wordpress-6.1/blocks.php +++ b/lib/compat/wordpress-6.1/blocks.php @@ -205,3 +205,44 @@ 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'] ) + ) + ); + + /** + * 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 ); diff --git a/schemas/json/block.json b/schemas/json/block.json index 4a343c51f4fb4..7553a564fe90e 100644 --- a/schemas/json/block.json +++ b/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" ],