Block Supports: Add background image support to Group block (#53934)

* Media Block Support: Add backgroundImage support to Group block

* Add error handling for video uploads, refactor to a BackgroundImagePanelItem component

* Ensure styles are not serialized in save mode, and not duplicated on site frontend

* Fix upload issue

* Try using style engine for PHP output, too

* Try renaming block support and panel to Background

* Rename panel label to Background image, rename component for consistency

* Update block.json schema, fix issue with omitting styles

* Simplify block schema slightly, make the check for the background.backgroundImage property

* Update test, remove TODO comment

* Fix upload container classname

* Update hasBackgroundSupport to handle any case

* Update theme.json schema

* Store media title in attributes, update docs

docs/reference-guides/core-blocks.md

@@ -302,7 +302,7 @@ Gather blocks in a layout container. ([Source](https://github.com/WordPress/gute
 
 -	**Name:** core/group
 -	**Category:** design
--	**Supports:** align (full, wide), anchor, ariaLabel, color (background, button, gradients, heading, link, text), dimensions (minHeight), layout (allowSizingOnChildren), position (sticky), spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~
+-	**Supports:** align (full, wide), anchor, ariaLabel, background (backgroundImage), color (background, button, gradients, heading, link, text), dimensions (minHeight), layout (allowSizingOnChildren), position (sticky), spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~
 -	**Attributes:** allowedBlocks, tagName, templateLock
 
 ## Heading

docs/reference-guides/theme-json-reference/theme-json-living.md

@@ -31,6 +31,7 @@ Code editors can pick up the schema and can provide helpful hints and suggestion
 
 Setting that enables the following UI tools:
 
+- background: backgroundImage
 - border: color, radius, style, width
 - color: link
 - dimensions: minHeight
@@ -97,6 +98,16 @@ Settings related to colors.
 
 ---
 
+### background
+
+Settings related to background.
+
+| Property  | Type   | Default | Props  |
+| ---       | ---    | ---    |---   |
+| backgroundImage | boolean | false |  |
+
+---
+
 ### dimensions
 
 Settings related to dimensions.

lib/block-supports/background.php

@@ -0,0 +1,103 @@
+<?php
+/**
+ * Background block support flag.
+ *
+ * @package gutenberg
+ */
+
+/**
+ * Registers the style block attribute for block types that support it.
+ *
+ * @param WP_Block_Type $block_type Block Type.
+ */
+function gutenberg_register_background_support( $block_type ) {
+	// Setup attributes and styles within that if needed.
+	if ( ! $block_type->attributes ) {
+		$block_type->attributes = array();
+	}
+
+	// Check for existing style attribute definition e.g. from block.json.
+	if ( array_key_exists( 'style', $block_type->attributes ) ) {
+		return;
+	}
+
+	$has_background_support = block_has_support( $block_type, array( 'background' ), false );
+
+	if ( $has_background_support ) {
+		$block_type->attributes['style'] = array(
+			'type' => 'object',
+		);
+	}
+}
+
+/**
+ * Renders the background styles to the block wrapper.
+ * This block support uses the `render_block` hook to ensure that
+ * it is also applied to non-server-rendered blocks.
+ *
+ * @param  string $block_content Rendered block content.
+ * @param  array  $block         Block object.
+ * @return string                Filtered block content.
+ */
+function gutenberg_render_background_support( $block_content, $block ) {
+	$block_type                   = WP_Block_Type_Registry::get_instance()->get_registered( $block['blockName'] );
+	$block_attributes             = $block['attrs'];
+	$has_background_image_support = block_has_support( $block_type, array( 'background', 'backgroundImage' ), false );
+
+	if (
+		! $has_background_image_support ||
+		wp_should_skip_block_supports_serialization( $block_type, 'background', 'backgroundImage' )
+	) {
+		return $block_content;
+	}
+
+	$background_image_source = _wp_array_get( $block_attributes, array( 'style', 'background', 'backgroundImage', 'source' ), null );
+	$background_image_url    = _wp_array_get( $block_attributes, array( 'style', 'background', 'backgroundImage', 'url' ), null );
+	$background_size         = _wp_array_get( $block_attributes, array( 'style', 'background', 'backgroundSize' ), 'cover' );
+
+	$background_block_styles = array();
+
+	if (
+		'file' === $background_image_source &&
+		$background_image_url
+	) {
+		// Set file based background URL.
+		// TODO: In a follow-up, similar logic could be added to inject a featured image url.
+		$background_block_styles['backgroundImage']['url'] = $background_image_url;
+		// Only output the background size when an image url is set.
+		$background_block_styles['backgroundSize'] = $background_size;
+	}
+
+	$styles = gutenberg_style_engine_get_styles( array( 'background' => $background_block_styles ) );
+
+	if ( ! empty( $styles['css'] ) ) {
+		// Inject background styles to the first element, presuming it's the wrapper, if it exists.
+		$tags = new WP_HTML_Tag_Processor( $block_content );
+
+		if ( $tags->next_tag() ) {
+			$existing_style = $tags->get_attribute( 'style' );
+			$updated_style  = '';
+
+			if ( ! empty( $existing_style ) && ! str_ends_with( $existing_style, ';' ) ) {
+				$updated_style = $existing_style . '; ';
+			}
+
+			$updated_style .= $styles['css'];
+			$tags->set_attribute( 'style', $updated_style );
+		}
+
+		return $tags->get_updated_html();
+	}
+
+	return $block_content;
+}
+
+// Register the block support.
+WP_Block_Supports::get_instance()->register(
+	'background',
+	array(
+		'register_attribute' => 'gutenberg_register_background_support',
+	)
+);
+
+add_filter( 'render_block', 'gutenberg_render_background_support', 10, 2 );

lib/class-wp-theme-json-gutenberg.php

@@ -352,6 +352,9 @@ class WP_Theme_JSON_Gutenberg {
 	const VALID_SETTINGS = array(
 		'appearanceTools'               => null,
 		'useRootPaddingAwareAlignments' => null,
+		'background'                    => array(
+			'backgroundImage' => null,
+		),
 		'border'                        => array(
 			'color'  => null,
 			'radius' => null,
@@ -569,6 +572,7 @@ public static function get_element_class_name( $element ) {
 	 * @var array
 	 */
 	const APPEARANCE_TOOLS_OPT_INS = array(
+		array( 'background', 'backgroundImage' ),
 		array( 'border', 'color' ),
 		array( 'border', 'radius' ),
 		array( 'border', 'style' ),

lib/load.php

@@ -229,3 +229,4 @@ function gutenberg_is_experiment_enabled( $name ) {
 require __DIR__ . '/block-supports/duotone.php';
 require __DIR__ . '/block-supports/shadow.php';
 require __DIR__ . '/block-supports/behaviors.php';
+require __DIR__ . '/block-supports/background.php';

packages/block-editor/src/components/block-inspector/index.js

@@ -300,6 +300,10 @@ const BlockInspectorSingleBlock = ( { clientId, blockName } ) => {
 						label={ __( 'Border' ) }
 					/>
 					<InspectorControls.Slot group="styles" />
+					<InspectorControls.Slot
+						group="background"
+						label={ __( 'Background' ) }
+					/>
 					<PositionControls />
 					<div>
 						<AdvancedControls />

packages/block-editor/src/components/inspector-controls-tabs/styles-tab.js

@@ -32,6 +32,10 @@ const StylesTab = ( { blockName, clientId, hasBlockStyles } ) => {
 				label={ __( 'Color' ) }
 				className="color-block-support-panel__inner-wrapper"
 			/>
+			<InspectorControls.Slot
+				group="background"
+				label={ __( 'Background image' ) }
+			/>
 			<InspectorControls.Slot group="filter" />
 			<InspectorControls.Slot
 				group="typography"

packages/block-editor/src/components/inspector-controls/groups.js

@@ -5,6 +5,9 @@ import { createSlotFill } from '@wordpress/components';
 
 const InspectorControlsDefault = createSlotFill( 'InspectorControls' );
 const InspectorControlsAdvanced = createSlotFill( 'InspectorAdvancedControls' );
+const InspectorControlsBackground = createSlotFill(
+	'InspectorControlsBackground'
+);
 const InspectorControlsBorder = createSlotFill( 'InspectorControlsBorder' );
 const InspectorControlsColor = createSlotFill( 'InspectorControlsColor' );
 const InspectorControlsFilter = createSlotFill( 'InspectorControlsFilter' );
@@ -21,15 +24,16 @@ const InspectorControlsStyles = createSlotFill( 'InspectorControlsStyles' );
 const groups = {
 	default: InspectorControlsDefault,
 	advanced: InspectorControlsAdvanced,
+	background: InspectorControlsBackground,
 	border: InspectorControlsBorder,
 	color: InspectorControlsColor,
-	filter: InspectorControlsFilter,
 	dimensions: InspectorControlsDimensions,
+	filter: InspectorControlsFilter,
 	list: InspectorControlsListView,
+	position: InspectorControlsPosition,
 	settings: InspectorControlsDefault, // Alias for default.
 	styles: InspectorControlsStyles,
 	typography: InspectorControlsTypography,
-	position: InspectorControlsPosition,
 };
 
 export default groups;