From a24468bbd898967d2df18843fe35dbc7352fce20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9?= <583546+oandregal@users.noreply.github.com> Date: Fri, 14 Apr 2023 13:38:04 +0200 Subject: [PATCH 1/3] Document variations in theme.json --- docs/how-to-guides/themes/theme-json.md | 36 +++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/docs/how-to-guides/themes/theme-json.md b/docs/how-to-guides/themes/theme-json.md index ba0e921109d755..041b202ac8318f 100644 --- a/docs/how-to-guides/themes/theme-json.md +++ b/docs/how-to-guides/themes/theme-json.md @@ -18,6 +18,7 @@ WordPress 5.8 comes with [a new mechanism](https://make.wordpress.org/core/2021/ - Top-level - Block-level - Elements + - Variations - customTemplates - templateParts - patterns @@ -1084,6 +1085,41 @@ Pseudo selectors `:hover`, `:focus`, `:visited`, `:active`, `:link`, `:any-link` } ``` +#### Variations + +A block can have a "style variation", as defined per the [block.json specification](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#styles-optional). Theme authors can define the style attributes for an existing style variation using the `theme.json`. Styles for unregistered style variations will be ignored. + +Note that variations are a "block concept", they only exist bound to blocks. The `theme.json` specification respects that distinction by only allowing `variations` at the block-level but not at the top-level. + +For example, this is how to provide styles for the existing `plain` variation for the `core/quote` block: + +```json +{ + "version": 2, + "styles":{ + "blocks": { + "core/quote": { + "variations": { + "plain": { + "color": { + "background": "red" + } + } + } + } + } + } +} +``` + +The resulting CSS output is this: + +```css +.wp-block-quote.is-style-plain { + background-color: red; +} +``` + ### customTemplates
Supported in WordPress from version 5.9.
From 9c4cffee385738b290ab76a60ddcf90f502a15c0 Mon Sep 17 00:00:00 2001 From: Andrew Serong <14988353+andrewserong@users.noreply.github.com> Date: Mon, 17 Apr 2023 10:25:54 +0200 Subject: [PATCH 2/3] Fix grammar --- docs/how-to-guides/themes/theme-json.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/themes/theme-json.md b/docs/how-to-guides/themes/theme-json.md index 041b202ac8318f..6ca33e425a4cfc 100644 --- a/docs/how-to-guides/themes/theme-json.md +++ b/docs/how-to-guides/themes/theme-json.md @@ -1087,7 +1087,7 @@ Pseudo selectors `:hover`, `:focus`, `:visited`, `:active`, `:link`, `:any-link` #### Variations -A block can have a "style variation", as defined per the [block.json specification](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#styles-optional). Theme authors can define the style attributes for an existing style variation using the `theme.json`. Styles for unregistered style variations will be ignored. +A block can have a "style variation", as defined per the [block.json specification](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#styles-optional). Theme authors can define the style attributes for an existing style variation using the theme.json file. Styles for unregistered style variations will be ignored. Note that variations are a "block concept", they only exist bound to blocks. The `theme.json` specification respects that distinction by only allowing `variations` at the block-level but not at the top-level. From 1f2098d71a7017e36fc4e3c0a0c2947a01311e04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9?= <583546+oandregal@users.noreply.github.com> Date: Mon, 17 Apr 2023 10:29:27 +0200 Subject: [PATCH 3/3] Add caveat about what style variations are considered --- docs/how-to-guides/themes/theme-json.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/themes/theme-json.md b/docs/how-to-guides/themes/theme-json.md index 6ca33e425a4cfc..5956f36d52563c 100644 --- a/docs/how-to-guides/themes/theme-json.md +++ b/docs/how-to-guides/themes/theme-json.md @@ -1089,7 +1089,7 @@ Pseudo selectors `:hover`, `:focus`, `:visited`, `:active`, `:link`, `:any-link` A block can have a "style variation", as defined per the [block.json specification](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#styles-optional). Theme authors can define the style attributes for an existing style variation using the theme.json file. Styles for unregistered style variations will be ignored. -Note that variations are a "block concept", they only exist bound to blocks. The `theme.json` specification respects that distinction by only allowing `variations` at the block-level but not at the top-level. +Note that variations are a "block concept", they only exist bound to blocks. The `theme.json` specification respects that distinction by only allowing `variations` at the block-level but not at the top-level. It's also worth highlighting that only variations defined in the `block.json` file of the block are considered "registered": so far, the style variations added via `register_block_style` or in the client are ignored, see [this issue](https://github.com/WordPress/gutenberg/issues/49602) for more information. For example, this is how to provide styles for the existing `plain` variation for the `core/quote` block: