Skip to content

Commit

Permalink
Blocks: Add new render field to block.json (#42430)
Browse files Browse the repository at this point in the history
* 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>
  • Loading branch information
gziolo and aristath authored Aug 30, 2022
1 parent c724c39 commit 132b86c
Show file tree
Hide file tree
Showing 3 changed files with 102 additions and 22 deletions.
75 changes: 53 additions & 22 deletions docs/reference-guides/block-api/block-metadata.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
```

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
{
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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:**

Expand Down Expand Up @@ -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`:
Expand Down
45 changes: 45 additions & 0 deletions lib/compat/wordpress-6.1/blocks.php
Original file line number Diff line number Diff line change
Expand Up @@ -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 );
4 changes: 4 additions & 0 deletions schemas/json/block.json
Original file line number Diff line number Diff line change
Expand Up @@ -574,6 +574,10 @@
}
}
}
},
"render": {
"type": "string",
"description": "Template file loaded on the server when rendering a block."
}
},
"required": [ "name", "title" ],
Expand Down

0 comments on commit 132b86c

Please sign in to comment.