Support adding opt-in visual styles for core blocks #6947

brandonpayton · 2018-05-24T21:00:33Z

Description

This PR enables separating visual block styles from those required for block function and provides a way for themes to opt into those styles. The purpose is to offer default visual styles for themes that want them without interfering with existing themes that provide their own.

Contributes to #5360.

How has this been tested?

This has been tested manually on the front and back end by adding and removing theme support for wp-block-styles and observing the presence or absence of build/core-blocks/theme.css in the Chrome dev tools Network tab.

I am working on some simple unit tests.

Types of changes

This PR enables separating visual block styles from structural styles on the front end. Core blocks may include a theme.scss file containing visual styles, and those styles will be built into build/core-blocks/theme.css. By default, theme.css will be enqueued for the editor but not on the front end. To include it on the front end, themes may add theme support for wp-block-styles.

add_theme_support( 'wp-block-styles' );

Checklist:

My code is tested.
My code follows the WordPress code style.
My code follows the accessibility standards.
My code has proper inline documentation.

mtias · 2018-05-26T18:24:46Z

Thanks for separating this. We should not be removing theme styles from the editor itself — we should always show them there. Themes can unhook and overwrite, but without them the editor appears broken. That means theme-editor should not be a thing.

What we end up with is:

style
editor
theme

All are used in the editor by default. Only style is used on the front-end by default. If you opt-in, style and theme are used on the front-end. Does that make sense?

brandonpayton · 2018-05-29T02:19:15Z

Thanks for your feedback and explanation, @mtias. I will rework this to remove theme-editor.

How will themes unhook these editor styles, by deregistering the wp-edit-blocks style and registering one to replace it?

mtias · 2018-05-29T11:20:43Z

by deregistering the wp-edit-blocks style and registering one to replace it?

Yes, any of our styles should be easy to unregister in the usual fashion. Given that it's not trivial to overwrite some styles within the editor, I don't expect this to be used much — it can lead to bugs.

mtias · 2018-05-29T11:21:10Z

core-blocks/button/edit.js

@@ -30,6 +30,7 @@ import {
 * Internal dependencies
 */
 import './editor.scss';
+import './theme-editor.scss';


Still a theme editor here.

mtias · 2018-05-29T11:22:19Z

core-blocks/button/theme-editor.scss

@@ -0,0 +1,53 @@
+.wp-block-button {


This file is theme-editor.

mtias

Some of these styles should be kept in style (like alignments for the categories block) asd they ar emore structural rather than visual design. The cover-image block should also be considered mostly style.

In general, I wouldn't move anything to theme just yet, as we have removed most of the opinionated styles already.

mtias · 2018-05-29T11:25:02Z

core-blocks/cover-image/theme-editor.scss

@@ -0,0 +1,7 @@
+.wp-block-cover-image {


This file should be just editor?

brandonpayton · 2018-05-29T23:51:15Z

Hi @mtias, thanks for your feedback. I made updates in response to your review and added unit tests. The unit test setup and teardown to save and restore global script and style dependencies are pretty heavy, so I'm not sure the tests are worth that. But they are there if we want them.

tofumatt

Seems good (and I'm always for tests, I get that slow tests are bad but I still think they're better than no tests), just some documentation tweaks I'd like to see before this ships.

tofumatt · 2018-05-30T10:48:34Z

docs/extensibility/theme-support.md

+
+## 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.


I think we can tweak this and cut it down to improve readability:

**Core blocks include default styles.** The styles are enqueued for the editor but are not enqueued for a theme 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`:

If I'm wrong about "theme" support versus "front-end" support let me know, but I think that's what these docs are trying to say.

Thanks, @tofumatt. That is definitely an improvement. I made some small adjustments to the text above based on my understanding. I felt like "theme" was too general in "not enqueued for a theme" since the theme is always a factor, even in editing. What do you think of the latest?

tofumatt · 2018-05-30T10:52:00Z

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


Maybe this should be "Default Block Styles" or something more obvious. If it were, you could omit the bolding I did in my tweaks below.

Agreed. I updated to your suggestion. The title should have been more focused but was leftover from an earlier PR that documented more than just default styles.

tofumatt · 2018-05-30T10:55:51Z

lib/client-assets.php

+		array(
+			'wp-components',
+			'wp-editor',
+			// Always include theme styles to avoid appearance of a broken editor.


Nitpick, how about: // Always include block styles so the editor never appears broken

tofumatt · 2018-05-30T10:56:25Z

phpunit/class-core-block-theme-test.php

+	}
+
+	function test_block_theme_in_editor_without_theme_support() {
+		// Confirm assumption.


What does this comment mean?

Yeah, that's pretty vague. My intent was to say we're asserting to confirm test conditions prior to the actual test. Does the updated comment work for you?

Update works for me, but as mentioned in the review the overall tests could use a bit of contextualisation.

tofumatt

Changes made to comments and documentation are good to me.

I feel like the tests could explain things a bit better with some comments, so I've added some notes, but after those changes are made I'd say this is good to go.

tofumatt · 2018-05-30T15:54:48Z

phpunit/class-core-block-theme-test.php

+		parent::tearDown();
+	}
+
+	function test_block_theme_in_editor_without_theme_support() {


I think you could add a comment to (at least) this test (and maybe the next) stating default block styles are always loaded for the editor and why. I know you've explained it elsewhere in this PR but that documentation won't be obvious to someone reading this test/just this file, so it bears repeating.

It's reasonably obvious what these tests are doing but not obvious why. I think a bit more explanation would make them clearer.

Agreed. I'll make the update.

tofumatt · 2018-05-30T15:55:46Z

phpunit/class-core-block-theme-test.php

+		$this->assertTrue( wp_style_is( 'wp-core-blocks-theme' ) );
+	}
+
+	function test_no_block_theme_on_front_end_without_theme_support() {


I'd rename this from test_no_block_theme_on_front_end_without_theme_support to test_no_block_styles_in_theme_without_theme_support or something like that. Same for the next test.

brandonpayton · 2018-05-30T20:35:12Z

I added a few more comments to the tests explaining why.

brandonpayton · 2018-05-30T22:38:09Z

My last comment should have included:
This looks ready to go.

tofumatt · 2018-05-31T05:15:41Z

New changes are 👍

mtias · 2018-05-31T15:14:23Z

Thanks!

See #6947.

This option was added to Gutenberg via WordPress/gutenberg#6947

…#7062) See #6947.

This option was added to Gutenberg via WordPress/gutenberg#6947

brandonpayton added [Feature] Block API API that allows to express the block paradigm. Customization Issues related to Phase 2: Customization efforts labels May 24, 2018

brandonpayton self-assigned this May 24, 2018

brandonpayton requested a review from mtias May 24, 2018 21:00

brandonpayton mentioned this pull request May 24, 2018

WIP Give themes control of visual styles for core blocks #6721

Closed

12 tasks

mtias reviewed May 29, 2018

View reviewed changes

core-blocks/button/theme-editor.scss Outdated

@@ -0,0 +1,53 @@

.wp-block-button {

Copy link

Member

mtias May 29, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file is theme-editor.

mtias requested changes May 29, 2018

View reviewed changes

mtias reviewed May 29, 2018

View reviewed changes

core-blocks/cover-image/theme-editor.scss Outdated

@@ -0,0 +1,7 @@

.wp-block-cover-image {

Copy link

Member

mtias May 29, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file should be just editor?

brandonpayton force-pushed the add/opt-in-default-block-styles branch 3 times, most recently from ec3d91c to 936ec09 Compare May 29, 2018 23:49

brandonpayton changed the title ~~Make default core block styles opt-in~~ Support adding opt-in visual styles for core blocks May 30, 2018

brandonpayton force-pushed the add/opt-in-default-block-styles branch from 936ec09 to 351e2b1 Compare May 30, 2018 00:40

tofumatt requested changes May 30, 2018

View reviewed changes

mtias added this to the 3.0 milestone May 30, 2018

brandonpayton added 2 commits May 30, 2018 08:23

Support opt-in visual styles for core blocks

2dfafa9

Update docs based on code review

fd2f34a

brandonpayton force-pushed the add/opt-in-default-block-styles branch from 351e2b1 to fd2f34a Compare May 30, 2018 15:33

tofumatt approved these changes May 30, 2018

View reviewed changes

Explain the why of the tests

15c3cb5

mtias approved these changes May 31, 2018

View reviewed changes

brandonpayton merged commit 6728906 into master May 31, 2018

brandonpayton deleted the add/opt-in-default-block-styles branch May 31, 2018 15:10

mtias added a commit that referenced this pull request May 31, 2018

Use new "theme" style mechanism to restore Quote styles on the front.

8f3e609

See #6947.

mtias mentioned this pull request May 31, 2018

Use new "theme" style mechanism to restore Quote styles on the front. #7062

Merged

kjellr added a commit to kjellr/gutenberg-starter-theme-dark that referenced this pull request Jun 1, 2018

Add theme support for wp-block-styles

2857b44

This option was added to Gutenberg via WordPress/gutenberg#6947

kjellr mentioned this pull request Jun 1, 2018

Add theme support for wp-block-styles WordPress/gutenberg-starter-theme#46

Merged

mtias added a commit that referenced this pull request Jun 4, 2018

Use new "theme" style mechanism to restore Quote styles on the front. (…

b763387

…#7062) See #6947.

karmatosed pushed a commit to WordPress/gutenberg-starter-theme that referenced this pull request Jun 4, 2018

Add theme support for wp-block-styles (#46)

5d9d923

This option was added to Gutenberg via WordPress/gutenberg#6947

BinaryMoon mentioned this pull request Jun 6, 2018

Move opinionated styles to theme.css #7172

Closed

jasmussen mentioned this pull request Jul 30, 2018

Block styles in the editor.scss #8094

Closed

colorful-tones mentioned this pull request Nov 9, 2018

Should we include any Gutenberg Theme settings by default? 10up/theme-scaffold#87

Closed

goldentroll added a commit to goldentroll/gutenberg-starter-theme that referenced this pull request Mar 13, 2023

Add theme support for wp-block-styles (#46)

0b00edb

This option was added to Gutenberg via WordPress/gutenberg#6947

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Support adding opt-in visual styles for core blocks #6947

Support adding opt-in visual styles for core blocks #6947

brandonpayton commented May 24, 2018 •

edited

Loading

mtias commented May 26, 2018

brandonpayton commented May 29, 2018

mtias commented May 29, 2018

mtias May 29, 2018

mtias May 29, 2018

mtias left a comment •

edited

Loading

mtias May 29, 2018

brandonpayton commented May 29, 2018

tofumatt left a comment

tofumatt May 30, 2018

brandonpayton May 30, 2018

tofumatt May 30, 2018

brandonpayton May 30, 2018

tofumatt May 30, 2018

tofumatt May 30, 2018

brandonpayton May 30, 2018

tofumatt May 30, 2018

tofumatt left a comment

tofumatt May 30, 2018

brandonpayton May 30, 2018

tofumatt May 30, 2018

brandonpayton commented May 30, 2018

brandonpayton commented May 30, 2018 •

edited

Loading

tofumatt commented May 31, 2018

mtias commented May 31, 2018


		## 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.

Support adding opt-in visual styles for core blocks #6947

Support adding opt-in visual styles for core blocks #6947

Conversation

brandonpayton commented May 24, 2018 • edited Loading

Description

How has this been tested?

Types of changes

Checklist:

mtias commented May 26, 2018

brandonpayton commented May 29, 2018

mtias commented May 29, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mtias left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brandonpayton commented May 29, 2018

tofumatt left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tofumatt left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brandonpayton commented May 30, 2018

brandonpayton commented May 30, 2018 • edited Loading

tofumatt commented May 31, 2018

mtias commented May 31, 2018

brandonpayton commented May 24, 2018 •

edited

Loading

mtias left a comment •

edited

Loading

brandonpayton commented May 30, 2018 •

edited

Loading