diff --git a/docs/how-to-guides/themes/theme-json.md b/docs/how-to-guides/themes/theme-json.md index 3f3da4c9f4a75..f6671698afc09 100644 --- a/docs/how-to-guides/themes/theme-json.md +++ b/docs/how-to-guides/themes/theme-json.md @@ -280,6 +280,14 @@ Each block can configure any of these settings separately, providing a more fine Note, however, that not all settings are relevant for all blocks. The settings section provides an opt-in/opt-out mechanism for themes, but it's the block's responsibility to add support for the features that are relevant to it. For example, if a block doesn't implement the `dropCap` feature, a theme can't enable it for such a block through `theme.json`. +### Opt-in into appearance controls + +There's one special setting property, `appareance`, which can be a boolean and its default value is true. When this is enabled, the following setting properties will be on by default: + +- border: color, radius, style, width +- spacing: margin, padding, units +- typography: customFontSize, lineHeight + #### Backward compatibility with add_theme_support To retain backward compatibility, the existing `add_theme_support` declarations that configure the block editor are retrofit in the proper categories for the top-level section. For example, if a theme uses `add_theme_support('disable-custom-colors')`, it'll be the same as setting `settings.color.custom` to `false`. If the `theme.json` contains any settings, these will take precedence over the values declared via `add_theme_support`. This is the complete list of equivalences: diff --git a/lib/class-wp-theme-json-gutenberg.php b/lib/class-wp-theme-json-gutenberg.php index 52d1cbbb643aa..523e65d046cc2 100644 --- a/lib/class-wp-theme-json-gutenberg.php +++ b/lib/class-wp-theme-json-gutenberg.php @@ -81,6 +81,7 @@ class WP_Theme_JSON_Gutenberg { ); const VALID_SETTINGS = array( + 'appearance' => null, 'border' => array( 'color' => null, 'radius' => null, @@ -290,7 +291,8 @@ public function __construct( $theme_json = array(), $origin = 'theme' ) { $valid_block_names = array_keys( self::get_blocks_metadata() ); $valid_element_names = array_keys( self::ELEMENTS ); - $this->theme_json = self::sanitize( $theme_json, $valid_block_names, $valid_element_names ); + $theme_json = self::sanitize( $theme_json, $valid_block_names, $valid_element_names ); + $this->theme_json = self::maybe_opt_in_into_settings( $theme_json ); // Internally, presets are keyed by origin. $nodes = self::get_setting_nodes( $this->theme_json ); @@ -305,6 +307,48 @@ public function __construct( $theme_json = array(), $origin = 'theme' ) { } } + /** + * Enables some opt-in settings if theme declared support. + * + * @param array $theme_json A theme.json structure to modify. + * @return array The modified theme.json structure. + */ + private static function maybe_opt_in_into_settings( $theme_json ) { + $new_theme_json = $theme_json; + + if ( isset( $new_theme_json['settings']['appearance'] ) ) { + self::do_opt_in_into_settings( $new_theme_json['settings'] ); + } + + if ( isset( $new_theme_json['settings']['blocks'] ) && is_array( $new_theme_json['settings']['blocks'] ) ) { + foreach ( $new_theme_json['settings']['blocks'] as &$block ) { + if ( isset( $block['appearance'] ) ) { + self::do_opt_in_into_settings( $block ); + } + } + } + + return $new_theme_json; + } + + /** + * Enables some settings. + * + * @param array $context The context to which the settings belong. + */ + private static function do_opt_in_into_settings( &$context ) { + gutenberg_experimental_set( $context, array( 'border', 'color' ), true ); + gutenberg_experimental_set( $context, array( 'border', 'radius' ), true ); + gutenberg_experimental_set( $context, array( 'border', 'style' ), true ); + gutenberg_experimental_set( $context, array( 'border', 'width' ), true ); + gutenberg_experimental_set( $context, array( 'spacing', 'margin' ), true ); + gutenberg_experimental_set( $context, array( 'spacing', 'padding' ), true ); + gutenberg_experimental_set( $context, array( 'spacing', 'units' ), true ); + gutenberg_experimental_set( $context, array( 'typography', 'customFontSize' ), true ); + gutenberg_experimental_set( $context, array( 'typography', 'lineHeight' ), true ); + unset( $context['appearance'] ); + } + /** * Sanitizes the input according to the schemas. * diff --git a/lib/theme.json b/lib/theme.json index 7629089219f8e..ecc8beceda717 100644 --- a/lib/theme.json +++ b/lib/theme.json @@ -1,6 +1,7 @@ { "version": 2, "settings": { + "appearance": true, "color": { "background": true, "palette": [ diff --git a/phpunit/class-wp-theme-json-test.php b/phpunit/class-wp-theme-json-test.php index d8c9f47a14607..55036af9c107d 100644 --- a/phpunit/class-wp-theme-json-test.php +++ b/phpunit/class-wp-theme-json-test.php @@ -188,6 +188,75 @@ function test_get_settings_presets_are_keyed_by_origin() { $this->assertEqualSetsWithIndex( $expected_no_origin, $actual_no_origin ); } + function test_get_settings_using_opt_in_key() { + $theme_json = new WP_Theme_JSON_Gutenberg( + array( + 'version' => WP_Theme_JSON_Gutenberg::LATEST_SCHEMA, + 'settings' => array( + 'appearance' => true, + 'blocks' => array( + 'core/paragraph' => array( + 'typography' => array( + 'lineHeight' => false, + ), + ), + 'core/group' => array( + 'appearance' => true, + 'typography' => array( + 'lineHeight' => false, // This is overridden by appearance. + ), + ), + ), + ), + ) + ); + + $actual = $theme_json->get_settings(); + $expected = array( + 'border' => array( + 'width' => true, + 'style' => true, + 'radius' => true, + 'color' => true, + ), + 'spacing' => array( + 'margin' => true, + 'padding' => true, + 'units' => true, + ), + 'typography' => array( + 'customFontSize' => true, + 'lineHeight' => true, + ), + 'blocks' => array( + 'core/paragraph' => array( + 'typography' => array( + 'lineHeight' => false, + ), + ), + 'core/group' => array( + 'border' => array( + 'width' => true, + 'style' => true, + 'radius' => true, + 'color' => true, + ), + 'spacing' => array( + 'margin' => true, + 'padding' => true, + 'units' => true, + ), + 'typography' => array( + 'customFontSize' => true, + 'lineHeight' => true, + ), + ), + ), + ); + + $this->assertEqualSetsWithIndex( $expected, $actual ); + } + function test_get_stylesheet_support_for_shorthand_and_longhand_values() { $theme_json = new WP_Theme_JSON_Gutenberg( array(