This pull request has changed or added PHP files. Please confirm whether these changes need to be synced to WordPress Core, and therefore featured in the next release of WordPress.

If so, it is recommended to create a new Trac ticket and submit a pull request to the WordPress Core Github repository soon after this pull request is merged.

If you're unsure, you can always ask for help in the #core-editor channel in WordPress Slack.

Thank you! ❤️

Size Change: +9.74 kB (+1%)

Total Size: 1.53 MB

_{compressed-size-action}

Once I have uploaded an image, if I try to change it I can open the media library and select a video, which doesn't work....

• I've noticed that the styles are duplicated in the frontend.
• I like that the style engine (JS one) also supports this.
• If I'm not wrong, the cover block uses a separate div for this, so I wonder if it's possible to actually unify the cover with this behavior at some point (I prefer to avoid extra DOM nodes here)
• Any thoughts on global styles support for this?

I can't seem to make both "color background" and "image background" work at the same time? what about with gradients?

Excited to see this under way!

I know you mentioned it wont be covered in this PR, but in terms of design it would be good to understand the broader vision for this. Is the intention to replicate the Cover experience, which is quite prescriptive? Or should we aim for something more flexible with options like background-size/position/repeat (as suggested), stacked backgrounds (images and colors), and so on?

cc @WordPress/theme-team for thoughts.

I am definitely missing a lot of context and knowledge but as I have explored a supports icon idea in the Icon/Vector registration API #53510 discussion and the test plugin - Demo of WordPress Icon API - I think a media supports should not mean background styles.

Why is support media = background media? The block should decide what to do with the media. The support opts in into a standard way of picking media.

It would actually be great if we could create a standarized Media settings panel.
For media, URL (Youtube, Vimeo etc) or something else.

Having a focal picker would also be nice. Having a Media settings panel for any block that can use media.

I do see the Media settings evolve which can be used for various blocks.

Flaky tests detected in d501bd6.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/6105917677
📝 Reported issues:

• [Flaky Test] should partially select with shift + click (@webkit) #53524 in /test/e2e/specs/editor/various/multi-block-selection.spec.js

Thanks for the early reviewing and testing, everyone! There were lots of comments, so I'll reply here, a little out of sequence. Apologies if I missed anything!

I've noticed that the styles are duplicated in the frontend.

I've fixed this up — styles should only be output once, and they shouldn't be serialized to post content. This allows us to look at more dynamic behaviour in follow-ups such as setting background to Featured Image.

Any thoughts on global styles support for this?

Global styles is an interesting case. I imagine blocks that could use it could include Post Content. But personally I'd be very interested in a root-global styles control for media/background image, particularly to set site-wide patterned backgrounds (like those in https://www.transparenttextures.com/). Since there would be lots of decisions to be made about how we'd implement it, I'm leaning toward us starting with just the block level for now, and build it out in global styles in follow-ups. This is another reason to keep all styles injection dynamic, so that we can change things in the future.

I can't seem to make both "color background" and "image background" work at the same time? what about with gradients?

In contrast to Cover block, this block support doesn't do layering / overlays, so background color will only work with transparent images, but it does appear to work. There is a styling conflict with gradients, though, as gradients use the background property, which overrides background-image. If / when this PR winds up landing, I reckon adding in mixed gradient / background image support (via multiple values output within a single background-image property) would be good to explore. I'd leave mixed gradient + transparent background images to follow-ups, though. Here's a screengrab with a transparent image:

Or should we aim for something more flexible with options like background-size/position/repeat (as suggested), stacked backgrounds (images and colors), and so on?

My intention with this PR is for us to start out as simple as possible, and then add more advanced controls in follow-ups (potentially hidden by default in the ToolsPanel). I'd love to see control over background size within repeat, so that folks can scale up/down their repeating images as desired. But again, for follow-ups — would be happy to see some design explorations for how the current PR might scale, though!

I am definitely missing a lot of context and knowledge but as I have explored a supports icon idea in the Icon/Vector registration API #53510 discussion and the test plugin - Demo of WordPress Icon API - I think a media supports should not mean background styles. Why is support media = background media?

Thanks for the feedback! The intention wasn't for media === background media, but rather to create a Media block support, and for the first feature within it, to add a background image support. In follow-ups, we might create all kinds of other media controls, but I think media could make for a good and consistent bucket for it. To make the hierarchy clearer, I've refactored the code a bit, so that the background image controls are in a separate sub-component, and I've updated the button label for clarity:

I do see the Media settings evolve which can be used for various blocks.

Thanks! Yes, my hope is that if we settle on Media as a panel, it could help with consistency across blocks, too 👍

Once I have uploaded an image, if I try to change it I can open the media library and select a video, which doesn't work....

This should be fixed now, and I've added a notice for if the media type is incorrect on upload. Let me know if you're still encountering it, though:

Thanks again for all the feedback, folks! Let me know if there's other changes anyone would like to see. My objective for now is to try to focus on a decent MVP, and hopefully defer further features to follow-ups. I still have a little cleaning up to do with the PHP code, which I ran out of time to do today. Once that's done, and pending any design feedback / ideas, I'll switch this over to ready for review.

I've fixed this up — styles should only be output once, and they shouldn't be serialized to post content. This allows us to look at more dynamic behaviour in follow-ups such as setting background to Featured Image.

This is I think not the first place where we favor server rendering over post content serialization for styles. The downside of this approach is that it breaks these blocks for third-party block editors. These customization can in theory be easily supported for server less block editors but we don't have the functions that render the right HTML for that (including all these dynamic styles that are static in reality). It would be good to keep that in mind and maybe keep track of all these static/dynamic styles to implement the wp.blocks.render function properly.

This is I think not the first place where we favor server rendering over post content serialization for styles. The downside of this approach is that it breaks these blocks for third-party block editors.

Thanks for raising this! I've added a comment over on the Gutenberg as Framework issue, too (#53874 (comment)). Up until this point, I'd assumed that it was desirable for future block supports to be dynamically output via the style engine in both JS and PHP for the reasons discussed back in #37495, so I'm keen to better understand if there's been a shift in direction there (or if I've misunderstood, of course 🙂).

In the case of this PR, the main reasons for dynamic output (even of static styles) are:

• To support filterable / dynamic images in follow-ups. Examples include potentially retrieving image url via id, or switching to a featured image, or one day images that form part a theme's assets.
• To allow themes or plugins to filter or switch off output, without breaking markup.
• To allow flexibility in changing output in follow-ups without requiring deprecations.
• To ensure that dependent static rules are only output when needed (so in this case background-size is only output when background-image is output).

It would be good to keep that in mind and maybe keep track of all these static/dynamic styles to implement the wp.blocks.render function properly.

Yes, it'd be good to ensure all features can be rendered in the same way in JS or PHP contexts. For this one, since we're adding the logic to the JS version of the style engine, depending on how we might want dynamic JS injection to work in the future (possibly at block render time?), I think overall we're heading in the right direction for that? Please do let me know if I'm missing something though, as I might have missed some of the context behind the thinking in #53874.

Thank you for all the collaboration here, everyone! 🙇

I've opened up a follow-up issue for ideas for future enhancements over in #54336. Feel free to add any ideas there! I imagine most enhancements other than #54319 (add Reset option) will likely be for beyond 6.4.

I've opened a backport PR for the PHP parts of this feature over in WordPress/wordpress-develop#5209

Related to the backport PR, I've opened up a separate Gutenberg PR to add in some more PHP tests over in #54489

Re: #53934 (comment)

But I wanted to add that another benefit of skipping serialization (at least for now) is that we can easily swap out the background-image CSS for an img element that supports srcset and SVG filters.

@ajlende Another benefit of an img element is that WordPress can optimize its loading by adding the fetchpriority="high" attribute. WordPress doesn't have any such optimizations currently for background-image, although this is something I'm exploring.

Example comparing background images in Group block versus Cover block, where only latter gets fetchpriority=high correctly: https://gist.github.com/westonruter/107f0c827bbee12341441c527ea2ed70

Draft dev note:

Background image block support

In WordPress 6.4, a new background image block support has been added, with the Group block opted-in by default. For themes using the appearanceTools feature in theme.json, the control will be available in the inspector controls, under Background.

The feature allows users to set a background image for a Group block. The selected image will be output at render-time for the block via an inline style applied to the block's wrapper. When a background image is set, the rule background-size: cover is output along with the background-image property. This ensures that any background images adequately cover the block. Ideas for enhancements in future releases are being tracked in this Github issue: #54336

How to add backgroundImage support to a theme

There are two ways to add support for backgroundImage to a block theme. The simplest is to opt in to the appearanceTools setting, which automatically enables a number of design tools (read more in the developer handbook).

For themes that wish to have more granular control over which UI tools are enabled, the backgroundImage support can be opted into by setting settings.background.backgroundImage to true in theme.json. For example:

{
	"settings": {
		"background": {
			"backgroundImage": true

Note that as of WP 6.4, the backgroundImage support is only available at the individual block level, and not in global styles or at the site root. These features will be explored in subsequent releases, with progress tracked in this Github issue: #54336.

This is I think not the first place where we favor server rendering over post content serialization for styles. The downside of this approach is that it breaks these blocks for third-party block editors.

In the case of this PR, the main reasons for dynamic output (even of static styles) are:

To allow flexibility in changing output in follow-ups without requiring deprecations.

I'm looking at trying to prevent color.gradient, which outputs its value using the background shorthand CSS property, from overwriting all background-* CSS properties in #60739.

Gutenberg has backed itself into a pretty tight corner by using background in this way. Ideally background-image should be used for images and linear gradients and combined where both exist.

Because we're skipping serialization for background block supports however, to achieve the above means that some
complicated deduplication and string manipulation needs to occur on the server where a block has both a gradient and background image:

1. When the incoming block has a background gradient applied in the inline CSS - here I want to remove that CSS and use background-image only.
2. Where a background gradient preset is applied via classname (which all have !important in the corresponding CSS rule) - the classname should be removed in favour of a combined background-image value.

Just flagging that changing output is not as flexible or convenient as it one might assume.

To ensure that dependent static rules are only output when needed (so in this case background-size is only output when background-image is output).

Relative to background-image, is this such a bad thing? If an image has been reset in the editor, Gutenberg can remove the style properties at that point. If background-size is set elsewhere, e.g., in theme.json and there's not image, I don't see why Gutenberg should care.