From a9e8a8565e2c7bdf3e44a04462d96db5288428ff Mon Sep 17 00:00:00 2001 From: Andrew Serong <14988353+andrewserong@users.noreply.github.com> Date: Mon, 18 Jul 2022 10:45:03 +1000 Subject: [PATCH] Theme JSON Docs: Clarify null, true, and false values for blockGap setting (#42447) * Theme JSON Documentation: Clarify null, true, and false values for blockGap setting * Clarify which blockGap value is ouput to the CSS variable * Improve clarity of boolean vs null Co-authored-by: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> * Change in to to into Co-authored-by: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> * Remove redundant words Co-authored-by: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> * Add `the` to null description Co-authored-by: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> Co-authored-by: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> --- docs/how-to-guides/themes/theme-json.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/how-to-guides/themes/theme-json.md b/docs/how-to-guides/themes/theme-json.md index d4e305693d1aef..dfa0e442d34fb3 100644 --- a/docs/how-to-guides/themes/theme-json.md +++ b/docs/how-to-guides/themes/theme-json.md @@ -1147,7 +1147,7 @@ body { /* CSS classes for the preset values */ .has-- { ... } -.has-pale-pink-color { color: var(--wp--preset--color--pale-pink) !important; } +.has-pale-pink-color { color: var(--wp--preset--color--pale-pink) !important; } .has-large-font-size { font-size: var(--wp--preset--font-size--large) !important; } ``` @@ -1179,12 +1179,7 @@ As a result of this change, it’s now the block author and theme author’s res ### What is blockGap and how can I use it? -blockGap adjusts the vertical margin, or gap, between blocks. -It is also used for margins between inner blocks in columns, buttons, and social icons. -In the editor, the control for the blockGap is called Block spacing, located in the Dimensions panel. - -The value you define for the blockGap style uses a CSS property, a preset, named `--wp--style--block-gap`. -The default value is 2em. +For blocks that contain inner blocks, such as Group, Columns, Buttons, and Social Icons, `blockGap` controls the spacing between inner blocks. Depending on the layout of the block, the `blockGap` value will be output as either a vertical margin or a `gap` value. In the editor, the control for the `blockGap` value is called _Block spacing_, located in the Dimensions panel. ```json { @@ -1202,6 +1197,14 @@ The default value is 2em. } ``` +The setting for `blockGap` is either a boolean or `null` value and is `null` by default. This allows an extra level of control over style output. The `settings.spacing.blockGap` setting in a `theme.json` file accepts the following values: + +- `true`: Opt into displaying _Block spacing_ controls in the editor UI and output `blockGap` styles. +- `false`: Opt out of displaying _Block spacing_ controls in the editor UI, with `blockGap` styles stored in `theme.json` still being rendered. This allows themes to use `blockGap` values without allowing users to make changes within the editor. +- `null` (default): Opt out of displaying _Block spacing_ controls, _and_ prevent the output of `blockGap` styles. + +The value defined for the root `styles.spacing.blockGap` style is also output as a CSS property, named `--wp--style--block-gap`. + ### Why does it take so long to update the styles in the browser? When you are actively developing with theme.json you may notice it takes 30+ seconds for your changes to show up in the browser, this is because `theme.json` is cached. To remove this caching issue, set either [`WP_DEBUG`](https://wordpress.org/support/article/debugging-in-wordpress/#wp_debug) or [`SCRIPT_DEBUG`](https://wordpress.org/support/article/debugging-in-wordpress/#script_debug) to 'true' in your [`wp-config.php`](https://wordpress.org/support/article/editing-wp-config-php/). This tells WordPress to skip the cache and always use fresh data.