From 91d577875c430a384c3ab55452dcad311628b1c3 Mon Sep 17 00:00:00 2001 From: Fabian Todt Date: Wed, 31 Jan 2024 16:49:42 +0100 Subject: [PATCH] Block API: Add `viewStyle` property support to `block.json` (#55492) * add viewStyle property to block schema * add viewStyle property to create-block * Add better explanation for viewStyle property * fix docs review suggestions --- .../applying-styles-with-stylesheets.md | 6 ++--- .../block-api/block-metadata.md | 23 ++++++++++++++++++- packages/create-block/lib/init-block.js | 2 ++ packages/create-block/lib/scaffold.js | 2 ++ packages/create-block/lib/templates.js | 1 + schemas/json/block.json | 14 +++++++++++ 6 files changed, 43 insertions(+), 5 deletions(-) diff --git a/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md b/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md index 6397b57e83748e..122ee3eaa0c27e 100644 --- a/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md +++ b/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md @@ -95,11 +95,9 @@ npm run build Like scripts, you can enqueue your block's styles using the `block.json` file. -Use the `editorStyle` property to a CSS file you want to load in the editor view, and use the `style` property for a CSS file you want to load on the frontend when the block is used. +Use the `editorStyle` property to a CSS file you want to load in the editor view only, use the `style` property for a CSS file you want to load both in the editor view and on the frontend when the block is used, and use the `viewStyle` property for a CSS file you want to load only on the frontend when the block is used. -It is worth noting that, if the editor content is iframed, both of these will -load in the iframe. `editorStyle` will also load outside the iframe, so it can -be used for editor content as well as UI. +It is worth noting that, if the editor content is iframed, both the `style` and `editorStyle` will load in the iframe. `editorStyle` will also load outside the iframe, so it can be used for editor content as well as UI. For example: diff --git a/docs/reference-guides/block-api/block-metadata.md b/docs/reference-guides/block-api/block-metadata.md index 6e786a2ff6322c..63512c5303fd21 100644 --- a/docs/reference-guides/block-api/block-metadata.md +++ b/docs/reference-guides/block-api/block-metadata.md @@ -57,6 +57,7 @@ Starting in WordPress 5.8 release, we recommend using the `block.json` metadata "viewScript": [ "file:./view.js", "example-shared-view-script" ], "editorStyle": "file:./index.css", "style": [ "file:./style.css", "example-shared-style" ], + "viewStyle": [ "file:./view.css", "example-view-style" ], "render": "file:./render.php" } ``` @@ -560,6 +561,24 @@ It's possible to pass a style handle registered with the [`wp_register_style`](h _Note: An option to pass also an array of styles exists since WordPress `5.9.0`._ +### View Style + +- Type: `WPDefinedAsset`|`WPDefinedAsset[]` ([learn more](#wpdefinedasset)) +- Optional +- Localized: No +- Property: `viewStyle` +- Since: `WordPress 6.5.0` + +```json +{ "viewStyle": [ "file:./view.css", "example-view-style" ] } +``` + +Block type frontend styles definition. They will be enqueued only when viewing the content on the front of the site. + +It's possible to pass a style handle registered with the [`wp_register_style`](https://developer.wordpress.org/reference/functions/wp_register_style/) function, a path to a CSS file relative to the `block.json` file, or a list with a mix of both ([learn more](#wpdefinedasset)). + +Frontend-only styles are especially useful for interactive blocks, to style parts that will only be visible after a user performs some action and where those styles will never be needed in the editor. You can start with using the `style` property to put all your common styles in one stylesheet. Only when you need editor-specific styling or frontend-specific styling, you can expand to `editorStyle` and `viewStyle`, but still keep the common part of your styling in the main stylesheet. + ### Render - Type: `WPDefinedPath` ([learn more](#wpdefinedpath)) @@ -618,7 +637,8 @@ In `block.json`: "script": "file:./script.js", "viewScript": [ "file:./view.js", "example-shared-view-script" ], "editorStyle": "file:./index.css", - "style": [ "file:./style.css", "example-shared-style" ] + "style": [ "file:./style.css", "example-shared-style" ], + "viewStyle": [ "file:./view.css", "example-view-style" ] } ``` @@ -670,6 +690,7 @@ Starting in the WordPress 5.8 release, it is possible to instruct WordPress to e - `script` - `viewScript` - `style` +- `viewStyle` (Added in WordPress 6.5.0) ## Internationalization diff --git a/packages/create-block/lib/init-block.js b/packages/create-block/lib/init-block.js index 5a60e90197ee82..58e62f06bed099 100644 --- a/packages/create-block/lib/init-block.js +++ b/packages/create-block/lib/init-block.js @@ -29,6 +29,7 @@ async function initBlockJSON( { editorScript, editorStyle, style, + viewStyle, render, viewModule, viewScript, @@ -62,6 +63,7 @@ async function initBlockJSON( { editorScript, editorStyle, style, + viewStyle, render, viewModule, viewScript, diff --git a/packages/create-block/lib/scaffold.js b/packages/create-block/lib/scaffold.js index bd9ba0396b75e3..d0c09dcd07a6b0 100644 --- a/packages/create-block/lib/scaffold.js +++ b/packages/create-block/lib/scaffold.js @@ -43,6 +43,7 @@ module.exports = async ( editorScript, editorStyle, style, + viewStyle, render, viewModule, viewScript, @@ -84,6 +85,7 @@ module.exports = async ( editorScript, editorStyle, style, + viewStyle, render, viewModule, viewScript, diff --git a/packages/create-block/lib/templates.js b/packages/create-block/lib/templates.js index 5edaa3fcc8ba83..4e70ee66fd3a40 100644 --- a/packages/create-block/lib/templates.js +++ b/packages/create-block/lib/templates.js @@ -33,6 +33,7 @@ const predefinedPluginTemplates = { editorScript: null, editorStyle: null, style: null, + viewStyle: null, viewScript: 'file:./view.js', example: {}, }, diff --git a/schemas/json/block.json b/schemas/json/block.json index b75a7b295fe293..cabaa40b7aec76 100644 --- a/schemas/json/block.json +++ b/schemas/json/block.json @@ -798,6 +798,20 @@ } ] }, + "viewStyle": { + "description": "Block type frontend style definition. It will be enqueued only when viewing the content on the front of the site.", + "oneOf": [ + { + "type": "string" + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + }, "variations": { "type": "array", "description": "Block Variations is the API that allows a block to have similar versions of it, but all these versions share some common functionality.",