diff --git a/docs/designers-developers/developers/themes/theme-json.md b/docs/designers-developers/developers/themes/theme-json.md index cb1a39c69a429d..161ca5f9d7c558 100644 --- a/docs/designers-developers/developers/themes/theme-json.md +++ b/docs/designers-developers/developers/themes/theme-json.md @@ -14,7 +14,7 @@ This is documentation for the current direction and work in progress about how t The Block Editor surface API has evolved at different velocities, and it's now at a point where is showing some growing pains, specially in areas that affect themes. Examples of this are: the ability to [control the editor programmatically](https://make.wordpress.org/core/2020/01/23/controlling-the-block-editor/), or [a block style system](https://github.com/WordPress/gutenberg/issues/9534) that facilitates user, theme, and core style preferences. -This describes the current efforts to consolidate the various APIs into a single point: a `experimental-theme.json` file. +This describes the current efforts to consolidate the various APIs into a single point – a `experimental-theme.json` file that should be located inside the root of the theme directory. When this file is present a few Block Editor mechanisms are activated. @@ -34,17 +34,17 @@ The Block Editor already allows the control of specific features such as alignme ## Specification -The specification for the `experimental-theme.json` follows the three main functions described in the section above: presets, styles, and features. +The specification for the `experimental-theme.json` follows the three main functions described in the section above: `presets`, `styles`, and `features`. ``` { - presets: { - color: [ ... ], - font-size: [ ... ], - gradient: [ ... ], + "presets": { + "color": [ ... ], + "font-size": [ ... ], + "gradient": [ ... ], }, - styles: { ... }, - features: { ... } + "styles": { ... }, + "features": {... } } ``` @@ -52,20 +52,20 @@ The file is divided into sections that represent different contexts: individual ``` { - global: { - presets: { ... }, - styles: { ... }, - features: { ... } + "global": { + "presets": { ... }, + "styles": { ... }, + "features": { ... } }, - core/paragraph: { - presets: { ... }, - styles: { ... }, - features: { ... } + "core/paragraph": { + "presets": { ... }, + "styles": { ... }, + "features": { ... } }, - core/group: { - presets: { ... }, - styles: { ... }, - features: { ... } + "core/group": { + "presets": { ... }, + "styles": { ... }, + "features": { ... } } } ``` @@ -74,25 +74,31 @@ Some of the functions are context-dependant. Take, as an example, the drop cap: ``` { - global: { - features: { - dropCap: false + "global": { + "features": { + "typography": { + "dropCap": false + } } }, - core/paragraph: { - features: { - dropCap: true, + "core/paragraph": { + "features": { + "typography": { + "dropCap": true + } } }, - core/image: { - features: { - dropCap: true + "core/image": { + "features": { + "typography": { + "dropCap": true + } } } } ``` -In the example above, we aim to encapsulate that the drop cap should be disabled globally but enabled in the paragraph context. The drop cap in the image context wouldn't make sense so should be ignored. +In the example above, we aim to encapsulate that the drop cap should be disabled globally but enabled in the paragraph context. The drop cap in the Image block context wouldn't make sense based on the current implementation so would be ignored, but it could be used by plugins that extend its functionality. ## Current Status @@ -105,17 +111,19 @@ The generated CSS Custom Properties follow this naming schema: `--wp--preset--{p For this input: ``` -presets: { - color: [ - { - slug: 'strong-magenta', - value: #a156b4, - }, - { - slug: 'very-dark-grey', - value: #444, - } - ], +"global": { + "presets": { + "color": [ + { + "slug": "strong-magenta", + "value": "#a156b4" + }, + { + "slug": "very-dark-grey", + "value": "#444" + } + ] + } } ``` @@ -166,7 +174,45 @@ The list of properties that are currently exposed via this method are: ### Features -This is being implemented, so it's not currently available. +Via the features key we allow controlling some editor and block features according to the following rules: +- The features within `global` override the default editor settings, which plugins can modify by hooking into the `block_editor_settings` filter on the server. +- The features within the context of each block override the default block settings, which plugins can modify by hooking into the `blocks.registerBlockType` filter on the client. +- Block settings take precedence over global settings. + +For example, if a feature is enabled for a block by default, although the theme disables it at the global level, the block keeps it enabled. If the theme wants to override a block's default, it has to target that particular block. + +So far, this function is enabled only for the `global` section in `lib/experimental-default-theme.json`. + +``` +{ + "global": { + "features": { + "typography": { + "dropCap": false + } + } + } +} +``` + +Then each block can decide to override how they handle block editor features during their registration process (`register_block_type` or `registerBlockType` calls) using `supports` object in `block.json` file: + +``` +{ + "supports": { + "__experimentalFeatures": { + "typography": { + "dropCap": true + } + } + } +} +``` + +Moving forward, we plan to integrate overrides targeting individual blocks defined inside a theme specific file (`experimental-theme.json`) that would be applied on top of features defined by block authors in `supports` property. + +The list of features that are currently supported are: +- Paragraph: drop cap. ### Recap of current available functions @@ -187,7 +233,7 @@ This is being implemented, so it's not currently available. "value": }, { } - ], + ], "gradient": [ { "slug": , @@ -204,85 +250,73 @@ This is being implemented, so it's not currently available. }, "core/paragraph": { "styles": { - "typography": { - "fontSize": , - "lineHeight": - }, "color": { "background": , "text": + }, + "typography": { + "fontSize": , + "lineHeight": } } }, "core/heading/h1": { "styles": { - "typography": { - "fontSize": , - "lineHeight": - }, "color": { "background": , "text": + }, + "typography": { + "fontSize": , + "lineHeight": } } }, "core/heading/h2": { "styles": { - "typography": { - "fontSize": , - "lineHeight": - }, "color": { "background": , "text": + }, + "typography": { + "fontSize": , + "lineHeight": } } }, "core/heading/h3": { "styles": { - "typography": { - "fontSize": , - "lineHeight": - }, "color": { "background": , "text": - } - } - }, - "core/heading/h4": { - "styles": { + }, "typography": { "fontSize": , "lineHeight": - }, - "color": { - "background": , - "text": } } }, "core/heading/h5": { "styles": { - "typography": { - "fontSize": , - "lineHeight": - }, "color": { "background": , "text": + }, + "typography": { + "fontSize": , + "lineHeight": } } }, "core/heading/h6": { "styles": { - "typography": { - "fontSize": , - "lineHeight": - }, "color": { "background": , "text": + }, + "typography": { + "fontSize": , + "lineHeight": } } },