Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Extend details about features integration with theme.json #22622

Merged
merged 6 commits into from
Jun 5, 2020
Merged

Docs: Extend details about features integration with theme.json #22622

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
88b883a
Docs: Extend details about features integration with `theme.json`
gziolo May 26, 2020
8e28af2
Docs: Explain the order of processing for block editor features
gziolo May 26, 2020
583ea7f
Apply suggestions from code review
gziolo May 27, 2020
aa79bb7
Improve formatting in the theme.json document
gziolo May 27, 2020
9cfaabe
Fix rebase issues
oandregal Jun 5, 2020
240bdf4
Fix rebase issues
oandregal Jun 5, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
186 changes: 110 additions & 76 deletions docs/designers-developers/developers/themes/theme-json.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -34,38 +34,38 @@ 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": {... }
}
```

The file is divided into sections that represent different contexts: individual blocks, as well as the global environment.

```
{
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": { ... }
}
}
```
Expand All @@ -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

Expand All @@ -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"
}
]
}
}
```

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

Expand All @@ -187,7 +233,7 @@ This is being implemented, so it's not currently available.
"value": <preset value>
},
{ <more font sizes> }
],
],
"gradient": [
{
"slug": <preset slug>,
Expand All @@ -204,85 +250,73 @@ This is being implemented, so it's not currently available.
},
"core/paragraph": {
"styles": {
"typography": {
"fontSize": <value>,
"lineHeight": <value>
},
"color": {
"background": <value>,
"text": <value>
},
"typography": {
"fontSize": <value>,
"lineHeight": <value>
}
}
},
"core/heading/h1": {
"styles": {
"typography": {
"fontSize": <value>,
"lineHeight": <value>
},
"color": {
"background": <value>,
"text": <value>
},
"typography": {
"fontSize": <value>,
"lineHeight": <value>
}
}
},
"core/heading/h2": {
"styles": {
"typography": {
"fontSize": <value>,
"lineHeight": <value>
},
"color": {
"background": <value>,
"text": <value>
},
"typography": {
"fontSize": <value>,
"lineHeight": <value>
}
}
},
"core/heading/h3": {
"styles": {
"typography": {
"fontSize": <value>,
"lineHeight": <value>
},
"color": {
"background": <value>,
"text": <value>
}
}
},
"core/heading/h4": {
"styles": {
},
"typography": {
"fontSize": <value>,
"lineHeight": <value>
},
"color": {
"background": <value>,
"text": <value>
}
}
},
"core/heading/h5": {
"styles": {
"typography": {
"fontSize": <value>,
"lineHeight": <value>
},
"color": {
"background": <value>,
"text": <value>
},
"typography": {
"fontSize": <value>,
"lineHeight": <value>
}
}
},
"core/heading/h6": {
"styles": {
"typography": {
"fontSize": <value>,
"lineHeight": <value>
},
"color": {
"background": <value>,
"text": <value>
},
"typography": {
"fontSize": <value>,
"lineHeight": <value>
}
}
},
Expand Down