From 2dfafa98cb2315cfc0e369d46428d5d28b2b87c2 Mon Sep 17 00:00:00 2001 From: Brandon Payton Date: Tue, 29 May 2018 09:49:38 -0700 Subject: [PATCH 1/3] Support opt-in visual styles for core blocks --- core-blocks/separator/index.js | 1 + core-blocks/separator/theme.scss | 2 + docs/extensibility/theme-support.md | 8 +++ lib/client-assets.php | 17 ++++- phpunit/class-core-block-theme-test.php | 85 +++++++++++++++++++++++++ webpack.config.js | 13 ++++ 6 files changed, 124 insertions(+), 2 deletions(-) create mode 100644 core-blocks/separator/theme.scss create mode 100644 phpunit/class-core-block-theme-test.php diff --git a/core-blocks/separator/index.js b/core-blocks/separator/index.js index 17ec90ca938c2..283c6cc744266 100644 --- a/core-blocks/separator/index.js +++ b/core-blocks/separator/index.js @@ -8,6 +8,7 @@ import { createBlock } from '@wordpress/blocks'; * Internal dependencies */ import './style.scss'; +import './theme.scss'; export const name = 'core/separator'; diff --git a/core-blocks/separator/theme.scss b/core-blocks/separator/theme.scss new file mode 100644 index 0000000000000..b887c36c184c0 --- /dev/null +++ b/core-blocks/separator/theme.scss @@ -0,0 +1,2 @@ +// TODO: Remove this comment when adding theme styles. +// Including an empty file for now so webpack will build an aggregate build/core-blocks/theme.css. diff --git a/docs/extensibility/theme-support.md b/docs/extensibility/theme-support.md index eb1306d02f126..4246d38fcbd12 100644 --- a/docs/extensibility/theme-support.md +++ b/docs/extensibility/theme-support.md @@ -151,3 +151,11 @@ body.gutenberg-editor-page .editor-block-list__block[data-align="full"] { You can use those editor widths to match those in your theme. You can use any CSS width unit, including `%` or `px`. Further reading: [Applying Styles with Stylesheets](https://wordpress.org/gutenberg/handbook/blocks/applying-styles-with-stylesheets/). + +## Styling blocks + +Core blocks come with default styles. The styles are always enqueued for the editor but, by default, are not enqueued for the front end. If you'd like to take advantage of these styles on the front end, simply add theme support for `wp-block-styles`, and the styles will be enqueued. + +```php +add_theme_support( 'wp-block-styles' ); +``` diff --git a/lib/client-assets.php b/lib/client-assets.php index 71be6a780ef12..346e0a7543045 100644 --- a/lib/client-assets.php +++ b/lib/client-assets.php @@ -426,7 +426,7 @@ function gutenberg_register_scripts_and_styles() { wp_register_style( 'wp-core-blocks', gutenberg_url( 'build/core-blocks/style.css' ), - array(), + current_theme_supports( 'wp-block-styles' ) ? array( 'wp-core-blocks-theme' ) : array(), filemtime( gutenberg_dir_path() . 'build/core-blocks/style.css' ) ); wp_style_add_data( 'wp-core-blocks', 'rtl', 'replace' ); @@ -434,11 +434,24 @@ function gutenberg_register_scripts_and_styles() { wp_register_style( 'wp-edit-blocks', gutenberg_url( 'build/core-blocks/edit-blocks.css' ), - array( 'wp-components', 'wp-editor' ), + array( + 'wp-components', + 'wp-editor', + // Always include theme styles to avoid appearance of a broken editor. + 'wp-core-blocks-theme', + ), filemtime( gutenberg_dir_path() . 'build/core-blocks/edit-blocks.css' ) ); wp_style_add_data( 'wp-edit-blocks', 'rtl', 'replace' ); + wp_register_style( + 'wp-core-blocks-theme', + gutenberg_url( 'build/core-blocks/theme.css' ), + array(), + filemtime( gutenberg_dir_path() . 'build/core-blocks/theme.css' ) + ); + wp_style_add_data( 'wp-core-blocks-theme', 'rtl', 'replace' ); + wp_register_script( 'wp-plugins', gutenberg_url( 'build/plugins/index.js' ), diff --git a/phpunit/class-core-block-theme-test.php b/phpunit/class-core-block-theme-test.php new file mode 100644 index 0000000000000..0074463dce364 --- /dev/null +++ b/phpunit/class-core-block-theme-test.php @@ -0,0 +1,85 @@ +old_wp_scripts = isset( $GLOBALS['wp_scripts'] ) ? $GLOBALS['wp_scripts'] : null; + remove_action( 'wp_default_scripts', 'wp_default_scripts' ); + + $GLOBALS['wp_scripts'] = new WP_Scripts(); + $GLOBALS['wp_scripts']->default_version = get_bloginfo( 'version' ); + + $this->old_wp_styles = isset( $GLOBALS['wp_styles'] ) ? $GLOBALS['wp_styles'] : null; + remove_action( 'wp_default_styles', 'wp_default_styles' ); + + $GLOBALS['wp_styles'] = new WP_Styles(); + $GLOBALS['wp_styles']->default_version = get_bloginfo( 'version' ); + } + + function tearDown() { + $GLOBALS['wp_scripts'] = $this->old_wp_scripts; + add_action( 'wp_default_scripts', 'wp_default_scripts' ); + + $GLOBALS['wp_styles'] = $this->old_wp_styles; + add_action( 'wp_default_styles', 'wp_default_styles' ); + + if ( current_theme_supports( 'wp-block-styles' ) ) { + remove_theme_support( 'wp-block-styles' ); + } + + parent::tearDown(); + } + + function test_block_theme_in_editor_without_theme_support() { + // Confirm assumption. + $this->assertFalse( current_theme_supports( 'wp-block-styles' ) ); + + gutenberg_register_scripts_and_styles(); + + $this->assertFalse( wp_style_is( 'wp-core-blocks-theme' ) ); + wp_enqueue_style( 'wp-edit-blocks' ); + $this->assertTrue( wp_style_is( 'wp-core-blocks-theme' ) ); + } + + function test_block_theme_in_editor_with_theme_support() { + add_theme_support( 'wp-block-styles' ); + gutenberg_register_scripts_and_styles(); + + $this->assertFalse( wp_style_is( 'wp-core-blocks-theme' ) ); + wp_enqueue_style( 'wp-edit-blocks' ); + $this->assertTrue( wp_style_is( 'wp-core-blocks-theme' ) ); + } + + function test_no_block_theme_on_front_end_without_theme_support() { + // Confirm assumption. + $this->assertFalse( current_theme_supports( 'wp-block-styles' ) ); + + gutenberg_register_scripts_and_styles(); + + $this->assertFalse( wp_style_is( 'wp-core-blocks-theme' ) ); + wp_enqueue_style( 'wp-core-blocks' ); + $this->assertFalse( wp_style_is( 'wp-core-blocks-theme' ) ); + } + + function test_block_theme_on_front_end_with_theme_support() { + add_theme_support( 'wp-block-styles' ); + + gutenberg_register_scripts_and_styles(); + + $this->assertFalse( wp_style_is( 'wp-core-blocks-theme' ) ); + wp_enqueue_style( 'wp-core-blocks' ); + $this->assertTrue( wp_style_is( 'wp-core-blocks-theme' ) ); + } +} diff --git a/webpack.config.js b/webpack.config.js index 3e4d766f0f1de..16f633102771e 100644 --- a/webpack.config.js +++ b/webpack.config.js @@ -28,6 +28,11 @@ const blocksCSSPlugin = new ExtractTextPlugin( { filename: './build/core-blocks/style.css', } ); +// CSS loader for default visual block styles. +const themeBlocksCSSPlugin = new ExtractTextPlugin( { + filename: './build/core-blocks/theme.css', +} ); + // Configuration for the ExtractTextPlugin. const extractConfig = { use: [ @@ -237,6 +242,13 @@ const config = { ], use: editBlocksCSSPlugin.extract( extractConfig ), }, + { + test: /\/theme\.s?css$/, + include: [ + /core-blocks/, + ], + use: themeBlocksCSSPlugin.extract( extractConfig ), + }, { test: /\.s?css$/, exclude: [ @@ -249,6 +261,7 @@ const config = { plugins: [ blocksCSSPlugin, editBlocksCSSPlugin, + themeBlocksCSSPlugin, mainCSSExtractTextPlugin, // Create RTL files with a -rtl suffix new WebpackRTLPlugin( { From fd2f34af49b18ac3bd7796e8183d6d0c7ce02227 Mon Sep 17 00:00:00 2001 From: Brandon Payton Date: Wed, 30 May 2018 08:29:15 -0700 Subject: [PATCH 2/3] Update docs based on code review --- docs/extensibility/theme-support.md | 4 ++-- lib/client-assets.php | 2 +- phpunit/class-core-block-theme-test.php | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/extensibility/theme-support.md b/docs/extensibility/theme-support.md index 4246d38fcbd12..ef5dfda8e8b31 100644 --- a/docs/extensibility/theme-support.md +++ b/docs/extensibility/theme-support.md @@ -152,9 +152,9 @@ You can use those editor widths to match those in your theme. You can use any CS Further reading: [Applying Styles with Stylesheets](https://wordpress.org/gutenberg/handbook/blocks/applying-styles-with-stylesheets/). -## Styling blocks +## Default block styles -Core blocks come with default styles. The styles are always enqueued for the editor but, by default, are not enqueued for the front end. If you'd like to take advantage of these styles on the front end, simply add theme support for `wp-block-styles`, and the styles will be enqueued. +Core blocks include default styles. The styles are enqueued for editing but are not enqueued for viewing unless the theme opts-in to the core styles. If you'd like to use default styles in your theme, add theme support for `wp-block-styles`: ```php add_theme_support( 'wp-block-styles' ); diff --git a/lib/client-assets.php b/lib/client-assets.php index 346e0a7543045..0b3e544ad457d 100644 --- a/lib/client-assets.php +++ b/lib/client-assets.php @@ -437,7 +437,7 @@ function gutenberg_register_scripts_and_styles() { array( 'wp-components', 'wp-editor', - // Always include theme styles to avoid appearance of a broken editor. + // Always include visual styles so the editor never appears broken. 'wp-core-blocks-theme', ), filemtime( gutenberg_dir_path() . 'build/core-blocks/edit-blocks.css' ) diff --git a/phpunit/class-core-block-theme-test.php b/phpunit/class-core-block-theme-test.php index 0074463dce364..256408d2c801d 100644 --- a/phpunit/class-core-block-theme-test.php +++ b/phpunit/class-core-block-theme-test.php @@ -43,7 +43,7 @@ function tearDown() { } function test_block_theme_in_editor_without_theme_support() { - // Confirm assumption. + // Confirm we are without theme support by default. $this->assertFalse( current_theme_supports( 'wp-block-styles' ) ); gutenberg_register_scripts_and_styles(); @@ -63,7 +63,7 @@ function test_block_theme_in_editor_with_theme_support() { } function test_no_block_theme_on_front_end_without_theme_support() { - // Confirm assumption. + // Confirm we are without theme support by default. $this->assertFalse( current_theme_supports( 'wp-block-styles' ) ); gutenberg_register_scripts_and_styles(); From 15c3cb5c24724179ba31f110679e1bdbce10e299 Mon Sep 17 00:00:00 2001 From: Brandon Payton Date: Wed, 30 May 2018 13:26:12 -0700 Subject: [PATCH 3/3] Explain the why of the tests --- phpunit/class-core-block-theme-test.php | 29 +++++++++++++++++++++---- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/phpunit/class-core-block-theme-test.php b/phpunit/class-core-block-theme-test.php index 256408d2c801d..4b3cf4ee553e8 100644 --- a/phpunit/class-core-block-theme-test.php +++ b/phpunit/class-core-block-theme-test.php @@ -42,7 +42,12 @@ function tearDown() { parent::tearDown(); } - function test_block_theme_in_editor_without_theme_support() { + /** + * Tests that visual block styles are enqueued in the editor even when there is not theme support for 'wp-block-styles'. + * + * Visual block styles should always be enqueued when editing to avoid the appearance of a broken editor. + */ + function test_block_styles_for_editing_without_theme_support() { // Confirm we are without theme support by default. $this->assertFalse( current_theme_supports( 'wp-block-styles' ) ); @@ -53,7 +58,12 @@ function test_block_theme_in_editor_without_theme_support() { $this->assertTrue( wp_style_is( 'wp-core-blocks-theme' ) ); } - function test_block_theme_in_editor_with_theme_support() { + /** + * Tests that visual block styles are enqueued when there is theme support for 'wp-block-styles'. + * + * Visual block styles should always be enqueued when editing to avoid the appearance of a broken editor. + */ + function test_block_styles_for_editing_with_theme_support() { add_theme_support( 'wp-block-styles' ); gutenberg_register_scripts_and_styles(); @@ -62,7 +72,13 @@ function test_block_theme_in_editor_with_theme_support() { $this->assertTrue( wp_style_is( 'wp-core-blocks-theme' ) ); } - function test_no_block_theme_on_front_end_without_theme_support() { + /** + * Tests that visual block styles are not enqueued for viewing when there is no theme support for 'wp-block-styles'. + * + * Visual block styles should not be enqueued unless a theme opts in. + * This way we avoid style conflicts with existing themes. + */ + function test_no_block_styles_for_viewing_without_theme_support() { // Confirm we are without theme support by default. $this->assertFalse( current_theme_supports( 'wp-block-styles' ) ); @@ -73,7 +89,12 @@ function test_no_block_theme_on_front_end_without_theme_support() { $this->assertFalse( wp_style_is( 'wp-core-blocks-theme' ) ); } - function test_block_theme_on_front_end_with_theme_support() { + /** + * Tests that visual block styles are enqueued for viewing when there is theme support for 'wp-block-styles'. + * + * Visual block styles should be enqueued when a theme opts in. + */ + function test_block_styles_for_viewing_with_theme_support() { add_theme_support( 'wp-block-styles' ); gutenberg_register_scripts_and_styles();