From e3296c97336f81ccc8ffb652e5807cef811243db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9?= Date: Thu, 1 Jul 2021 11:53:31 +0200 Subject: [PATCH 1/4] Intro and version --- docs/how-to-guides/themes/theme-json.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/how-to-guides/themes/theme-json.md b/docs/how-to-guides/themes/theme-json.md index 4a217a3c4d3ca..f864c88cdeabb 100644 --- a/docs/how-to-guides/themes/theme-json.md +++ b/docs/how-to-guides/themes/theme-json.md @@ -1,12 +1,6 @@ # Global Settings & Styles (theme.json) -
-These features are still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes. - -Documentation has been shared early to surface what’s being worked on and invite feedback from those experimenting with the APIs. Please share your feedback in the weekly #core-editor or #fse-outreach-experiment channels in Slack, or async in GitHub issues. -
- -This is documentation for the current direction and work in progress about how themes can hook into the various sub-systems that the Block Editor provides. +WordPress 5.8 comes with [a new mechanism](https://make.wordpress.org/core/2021/06/25/introducing-theme-json-in-wordpress-5-8/) to configure the editor that enables a finer-grained control and introduces the first step in managing styles for future WordPress releases: the `theme.json` file. This page documents its format. - Rationale - Settings for the block editor @@ -152,7 +146,9 @@ This specification is the same for the three different origins that use this for ### Version -This field describes the format of the `theme.json` file and it's used to detect different versions and migrate them to the latest format. +This field describes the format of the `theme.json` file. The current and only version is 1. + +WordPress 5.8 will ignore the contents of any `theme.json` whose version is not equals to the current. Should the Gutenberg plugin need it, it'll update the version and will add the corresponding migration mechanisms from older versions. ### Settings From 6ee3a246d59c441940035e0fb9442e936dd77ddb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9?= Date: Thu, 1 Jul 2021 12:01:35 +0200 Subject: [PATCH 2/4] Settings: WordPress vs Gutenberg --- docs/how-to-guides/themes/theme-json.md | 57 ++++++++++++++++++++++++- 1 file changed, 55 insertions(+), 2 deletions(-) diff --git a/docs/how-to-guides/themes/theme-json.md b/docs/how-to-guides/themes/theme-json.md index f864c88cdeabb..715ea1f61f977 100644 --- a/docs/how-to-guides/themes/theme-json.md +++ b/docs/how-to-guides/themes/theme-json.md @@ -152,8 +152,62 @@ WordPress 5.8 will ignore the contents of any `theme.json` whose version is not ### Settings +
+The Gutenberg plugin extends the settings available from WordPress 5.8, so they can be used with other WordPress versions and they go through a maturation process before being ported to core. + +The tabs below show WordPress 5.8 supported settings and the ones supported by the Gutenberg plugin. +
+ The settings section has the following structure: +{% codetabs %} +{% WordPress %} + +```json +{ + "version": 1, + "settings": { + "color": { + "custom": true, + "customGradient": true, + "duotone": [], + "gradients": [], + "link": false, + "palette": [] + }, + "custom": {}, + "layout": { + "contentSize": "800px", + "wideSize": "1000px" + }, + "spacing": { + "customMargin": false, + "customPadding": false, + "units": [ "px", "em", "rem", "vh", "vw" ] + }, + "typography": { + "customFontSize": true, + "customLineHeight": false, + "dropCap": true, + "fontSizes": [] + }, + "blocks": { + "core/paragraph": { + "color": {}, + "custom": {}, + "layout": {}, + "spacing": {}, + "typography": {} + }, + "core/heading": {}, + "etc": {} + } + } +} +``` + +{% Gutenberg %} + ```json { "version": 1, @@ -209,7 +263,7 @@ The settings section has the following structure: } ``` - +{% end %} Each block can configure any of these settings separately, providing a more fine-grained control over what exists via `add_theme_support`. The settings declared at the top-level affect to all blocks, unless a particular block overwrites it. It's a way to provide inheritance and configure all blocks at once. @@ -399,7 +453,6 @@ body { .wp-block-group.has-white-border-color { border-color: #444 !important; } ``` - {% end %} To maintain backward compatibility, the presets declared via `add_theme_support` will also generate the CSS Custom Properties. If the `theme.json` contains any presets, these will take precedence over the ones declared via `add_theme_support`. From 1c0c7a3a72895cb8ae5f3bd84f3a62fbb3b94dae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9?= Date: Thu, 1 Jul 2021 12:05:09 +0200 Subject: [PATCH 3/4] Styles: WordPress vs Gutenberg --- docs/how-to-guides/themes/theme-json.md | 79 ++++++++++++++++++++++++- 1 file changed, 77 insertions(+), 2 deletions(-) diff --git a/docs/how-to-guides/themes/theme-json.md b/docs/how-to-guides/themes/theme-json.md index 715ea1f61f977..558a2f4867fbd 100644 --- a/docs/how-to-guides/themes/theme-json.md +++ b/docs/how-to-guides/themes/theme-json.md @@ -511,8 +511,81 @@ Note that the name of the variable is created by adding `--` in between each nes ### Styles +
+The Gutenberg plugin extends the styles available from WordPress 5.8, so they can be used with other WordPress versions and they go through a maturation process before being ported to core. + +The tabs below show WordPress 5.8 supported styles and the ones supported by the Gutenberg plugin. +
+ Each block declares which style properties it exposes via the [block supports mechanism](../block-api/block-supports.md). The support declarations are used to automatically generate the UI controls for the block in the editor. Themes can use any style property via the `theme.json` for any block ― it's the theme's responsibility to verify that it works properly according to the block markup, etc. +{% codetabs %} + +{% WordPress %} + +```json +{ + "version": 1, + "styles": { + "color": { + "background": "value", + "gradient": "value", + "text": "value" + }, + "spacing": { + "margin": { + "top": "value", + "right": "value", + "bottom": "value", + "left": "value" + }, + "padding": { + "top": "value", + "right": "value", + "bottom": "value", + "left": "value" + } + }, + "typography": { + "fontSize": "value", + "lineHeight": "value" + }, + "elements": { + "link": { + "color": {}, + "spacing": {}, + "typography": {} + }, + "h1": {}, + "h2": {}, + "h3": {}, + "h4": {}, + "h5": {}, + "h6": {} + }, + "blocks": { + "core/group": { + "color": {}, + "spacing": {}, + "typography": {}, + "elements": { + "link": {}, + "h1": {}, + "h2": {}, + "h3": {}, + "h4": {}, + "h5": {}, + "h6": {} + } + }, + "etc": {} + } + } +} +``` + +{% Gutenberg %} + ```json { "version": 1, @@ -556,7 +629,7 @@ Each block declares which style properties it exposes via the [block supports me "border": {}, "color": {}, "spacing": {}, - "typography": {}, + "typography": {} }, "h1": {}, "h2": {}, @@ -581,12 +654,14 @@ Each block declares which style properties it exposes via the [block supports me "h6": {} } }, - "etc": {} + "etc": {} } } } ``` +{% end%} + ### Top-level styles Styles found at the top-level will be enqueued using the `body` selector. From 2e4dcbcd3eefaa95dd8ac1536de618b5cd47813b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9?= Date: Thu, 1 Jul 2021 12:07:27 +0200 Subject: [PATCH 4/4] Callouts for customTemplates and templateParts --- docs/how-to-guides/themes/theme-json.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/how-to-guides/themes/theme-json.md b/docs/how-to-guides/themes/theme-json.md index 558a2f4867fbd..0990c618ea9f4 100644 --- a/docs/how-to-guides/themes/theme-json.md +++ b/docs/how-to-guides/themes/theme-json.md @@ -826,6 +826,10 @@ h3 { ### customTemplates +
+This field is only allowed when the Gutenberg plugin is active. In WordPress 5.8 will be ignored. +
+ Within this field themes can list the custom templates present in the `block-templates` folder. For example, for a custom template named `my-custom-template.html`, the `theme.json` can declare what post types can use it and what's the title to show the user: - name: mandatory. @@ -851,6 +855,10 @@ Within this field themes can list the custom templates present in the `block-tem ### templateParts +
+This field is only allowed when the Gutenberg plugin is active. In WordPress 5.8 will be ignored. +
+ Within this field themes can list the template parts present in the `block-template-parts` folder. For example, for a template part named `my-template-part.html`, the `theme.json` can declare the area term for the template part entity which is responsible for rendering the corresponding block variation (Header block, Footer block, etc.) in the editor. Defining this area term in the json will allow the setting to persist across all uses of that template part entity, as opposed to a block attribute that would only affect one block. Defining area as a block attribute is not recommended as this is only used 'behind the scenes' to aid in bridging the gap between placeholder flows and entity creation. Currently block variations exist for "header" and "footer" values of the area term, any other values and template parts not defined in the json will default to the general template part block. Variations will be denoted by specific icons within the editor's interface, will default to the corresponding semantic HTML element for the wrapper (this can also be overridden by the `tagName` attribute set on the template part block), and will contextualize the template part allowing more custom flows in future editor improvements.