Skip to content

Commit 3e80bc4

Browse files
Background: Add a PHP helper for block support classes and styles
1 parent b8ba6ea commit 3e80bc4

5 files changed

Lines changed: 258 additions & 46 deletions

File tree

‎lib/block-supports/background.php‎

Lines changed: 65 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,62 @@ function gutenberg_register_background_support( $block_type ) {
3030
}
3131
}
3232

33+
/**
34+
* Gets the background classes and styles for a block's attributes.
35+
*
36+
* @since 7.2.0
37+
*
38+
* @param array $block_attributes Block attributes.
39+
* @return array Background `class` and `style` strings, each present only when non-empty.
40+
*/
41+
function gutenberg_get_background_classes_and_styles( $block_attributes ) {
42+
$background = $block_attributes['style']['background'] ?? null;
43+
44+
if ( ! is_array( $background ) ) {
45+
return array();
46+
}
47+
48+
$background_styles = array(
49+
'backgroundImage' => $background['backgroundImage'] ?? null,
50+
'backgroundSize' => $background['backgroundSize'] ?? null,
51+
'backgroundPosition' => $background['backgroundPosition'] ?? null,
52+
'backgroundRepeat' => $background['backgroundRepeat'] ?? null,
53+
'backgroundAttachment' => $background['backgroundAttachment'] ?? null,
54+
'gradient' => $background['gradient'] ?? null,
55+
'backgroundClip' => $background['backgroundClip'] ?? null,
56+
);
57+
58+
if ( ! empty( $background_styles['backgroundImage'] ) ) {
59+
$background_styles['backgroundSize'] = $background_styles['backgroundSize'] ?? 'cover';
60+
// If the background size is set to `contain` and no position is set, set the position to `center`.
61+
if ( 'contain' === $background_styles['backgroundSize'] && ! $background_styles['backgroundPosition'] ) {
62+
$background_styles['backgroundPosition'] = '50% 50%';
63+
}
64+
}
65+
66+
$styles = gutenberg_style_engine_get_styles( array( 'background' => $background_styles ) );
67+
68+
if ( empty( $styles['css'] ) ) {
69+
return array();
70+
}
71+
72+
$attributes = array();
73+
74+
/*
75+
* A background clipped to the text paints the glyphs rather than the
76+
* block's box, so there is no block background to announce.
77+
*/
78+
$has_background = ! empty( $background_styles['backgroundImage'] ) || ! empty( $background_styles['gradient'] );
79+
80+
if ( $has_background && 'text' !== $background_styles['backgroundClip'] ) {
81+
$attributes['class'] = 'has-background';
82+
}
83+
84+
$attributes['style'] = $styles['css'];
85+
86+
return $attributes;
87+
}
88+
3389
/**
3490
* Renders the background styles to the block wrapper.
3591
* This block support uses the `render_block` hook to ensure that
@@ -70,13 +126,6 @@ function gutenberg_render_background_support( $block_content, $block ) {
70126
$background_styles['backgroundPosition'] = $block_attributes['style']['background']['backgroundPosition'] ?? null;
71127
$background_styles['backgroundRepeat'] = $block_attributes['style']['background']['backgroundRepeat'] ?? null;
72128
$background_styles['backgroundAttachment'] = $block_attributes['style']['background']['backgroundAttachment'] ?? null;
73-
if ( ! empty( $background_styles['backgroundImage'] ) ) {
74-
$background_styles['backgroundSize'] = $background_styles['backgroundSize'] ?? 'cover';
75-
// If the background size is set to `contain` and no position is set, set the position to `center`.
76-
if ( 'contain' === $background_styles['backgroundSize'] && ! $background_styles['backgroundPosition'] ) {
77-
$background_styles['backgroundPosition'] = '50% 50%';
78-
}
79-
}
80129
}
81130

82131
if ( ! $skip_background_gradient ) {
@@ -87,34 +136,28 @@ function gutenberg_render_background_support( $block_content, $block ) {
87136
$background_styles['backgroundClip'] = $block_attributes['style']['background']['backgroundClip'] ?? null;
88137
}
89138

90-
$styles = gutenberg_style_engine_get_styles( array( 'background' => $background_styles ) );
139+
// Pass only serialized values, so a skipped or unsupported clip cannot suppress `has-background`.
140+
$styles = gutenberg_get_background_classes_and_styles(
141+
array( 'style' => array( 'background' => $background_styles ) )
142+
);
91143

92-
if ( ! empty( $styles['css'] ) ) {
144+
if ( ! empty( $styles['style'] ) ) {
93145
// Inject background styles to the first element, presuming it's the wrapper, if it exists.
94146
$tags = new WP_HTML_Tag_Processor( $block_content );
95147

96148
if ( $tags->next_tag() ) {
97149
$existing_style = $tags->get_attribute( 'style' );
98150
if ( is_string( $existing_style ) && '' !== $existing_style ) {
99151
$separator = str_ends_with( $existing_style, ';' ) ? '' : ';';
100-
$updated_style = "{$existing_style}{$separator}{$styles['css']}";
152+
$updated_style = "{$existing_style}{$separator}{$styles['style']}";
101153
} else {
102-
$updated_style = $styles['css'];
154+
$updated_style = $styles['style'];
103155
}
104156

105157
$tags->set_attribute( 'style', $updated_style );
106158

107-
/*
108-
* A background clipped to the text paints the glyphs rather than the
109-
* block's box, so there is no block background to announce. Read the
110-
* clip from the serialized styles so an unsupported or skipped value
111-
* left in the block's attributes cannot suppress the class.
112-
*/
113-
$background_clip = $background_styles['backgroundClip'] ?? null;
114-
$has_background = ! empty( $background_styles['backgroundImage'] ) || ! empty( $background_styles['gradient'] );
115-
116-
if ( $has_background && 'text' !== $background_clip ) {
117-
$tags->add_class( 'has-background' );
159+
if ( ! empty( $styles['class'] ) ) {
160+
$tags->add_class( $styles['class'] );
118161
}
119162
}
120163

‎packages/block-library/package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,8 @@
7373
"wp_get_typography_font_size_value",
7474
"wp_style_engine_get_styles",
7575
"wp_get_global_styles",
76-
"wp_get_global_settings"
76+
"wp_get_global_settings",
77+
"wp_get_background_classes_and_styles"
7778
],
7879
"suffixClasses": [
7980
"WP_Navigation_Block_Renderer"

‎packages/block-library/src/button/index.php‎

Lines changed: 8 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -64,26 +64,11 @@ function render_block_core_button( $attributes, $content ) {
6464
$background = $attributes['style']['background'] ?? null;
6565

6666
if ( is_array( $background ) ) {
67-
$background_styles = array(
68-
'backgroundImage' => $background['backgroundImage'] ?? null,
69-
'backgroundSize' => $background['backgroundSize'] ?? null,
70-
'backgroundPosition' => $background['backgroundPosition'] ?? null,
71-
'backgroundRepeat' => $background['backgroundRepeat'] ?? null,
72-
'backgroundAttachment' => $background['backgroundAttachment'] ?? null,
73-
'gradient' => $background['gradient'] ?? null,
74-
);
75-
76-
// Mirror the background block support defaults.
77-
if ( ! empty( $background_styles['backgroundImage'] ) ) {
78-
$background_styles['backgroundSize'] = $background_styles['backgroundSize'] ?? 'cover';
79-
if ( 'contain' === $background_styles['backgroundSize'] && ! $background_styles['backgroundPosition'] ) {
80-
$background_styles['backgroundPosition'] = '50% 50%';
81-
}
82-
}
83-
84-
$styles = wp_style_engine_get_styles( array( 'background' => $background_styles ) );
67+
// Button does not support the clip.
68+
unset( $background['backgroundClip'] );
69+
$styles = wp_get_background_classes_and_styles( array( 'style' => array( 'background' => $background ) ) );
8570

86-
if ( ! empty( $styles['css'] ) ) {
71+
if ( ! empty( $styles['style'] ) ) {
8772
$processor = new WP_HTML_Tag_Processor( $content );
8873
while ( $processor->next_tag() ) {
8974
if ( $tag !== $processor->get_tag() ) {
@@ -93,13 +78,13 @@ function render_block_core_button( $attributes, $content ) {
9378
$existing_style = $processor->get_attribute( 'style' );
9479
if ( is_string( $existing_style ) && '' !== $existing_style ) {
9580
$separator = str_ends_with( $existing_style, ';' ) ? '' : ';';
96-
$processor->set_attribute( 'style', $existing_style . $separator . $styles['css'] );
81+
$processor->set_attribute( 'style', $existing_style . $separator . $styles['style'] );
9782
} else {
98-
$processor->set_attribute( 'style', $styles['css'] );
83+
$processor->set_attribute( 'style', $styles['style'] );
9984
}
10085

101-
if ( ! empty( $background_styles['backgroundImage'] ) || ! empty( $background_styles['gradient'] ) ) {
102-
$processor->add_class( 'has-background' );
86+
if ( ! empty( $styles['class'] ) ) {
87+
$processor->add_class( $styles['class'] );
10388
}
10489
break;
10590
}

‎phpunit/block-supports/background-test.php‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -390,6 +390,145 @@ public function data_background_block_support() {
390390
);
391391
}
392392

393+
/**
394+
* Tests that the background helper returns classes and styles for block attributes.
395+
*
396+
* @covers ::gutenberg_get_background_classes_and_styles
397+
*
398+
* @dataProvider data_get_background_classes_and_styles
399+
*
400+
* @param mixed $block_attributes Block attributes.
401+
* @param array $expected Expected classes and styles.
402+
*/
403+
public function test_get_background_classes_and_styles( $block_attributes, $expected ) {
404+
$this->assertSame( $expected, gutenberg_get_background_classes_and_styles( $block_attributes ) );
405+
}
406+
407+
/**
408+
* Data provider for the background helper.
409+
*
410+
* @return array[]
411+
*/
412+
public function data_get_background_classes_and_styles() {
413+
return array(
414+
'custom image gets default size' => array(
415+
'block_attributes' => array(
416+
'style' => array(
417+
'background' => array(
418+
'backgroundImage' => array( 'url' => 'https://example.com/image.jpg' ),
419+
),
420+
),
421+
),
422+
'expected' => array(
423+
'class' => 'has-background',
424+
'style' => "background-image:url('https://example.com/image.jpg');background-size:cover;",
425+
),
426+
),
427+
'contain without position is centered' => array(
428+
'block_attributes' => array(
429+
'style' => array(
430+
'background' => array(
431+
'backgroundImage' => array( 'url' => 'https://example.com/image.jpg' ),
432+
'backgroundSize' => 'contain',
433+
'backgroundRepeat' => 'no-repeat',
434+
'backgroundAttachment' => 'fixed',
435+
),
436+
),
437+
),
438+
'expected' => array(
439+
'class' => 'has-background',
440+
'style' => "background-image:url('https://example.com/image.jpg');background-position:50% 50%;background-repeat:no-repeat;background-size:contain;background-attachment:fixed;",
441+
),
442+
),
443+
'preset gradient' => array(
444+
'block_attributes' => array(
445+
'style' => array(
446+
'background' => array(
447+
'gradient' => 'var:preset|gradient|vivid-cyan-blue-to-vivid-purple',
448+
),
449+
),
450+
),
451+
'expected' => array(
452+
'class' => 'has-background',
453+
'style' => 'background-image:var(--wp--preset--gradient--vivid-cyan-blue-to-vivid-purple);',
454+
),
455+
),
456+
'gradient clipped to text has no class' => array(
457+
'block_attributes' => array(
458+
'style' => array(
459+
'background' => array(
460+
'gradient' => 'linear-gradient(red, blue)',
461+
'backgroundClip' => 'text',
462+
),
463+
),
464+
),
465+
'expected' => array(
466+
'style' => 'background-image:linear-gradient(red, blue);background-clip:text;-webkit-background-clip:text;-webkit-text-fill-color:transparent;',
467+
),
468+
),
469+
'clip alone has no class' => array(
470+
'block_attributes' => array(
471+
'style' => array(
472+
'background' => array(
473+
'backgroundClip' => 'padding-box',
474+
),
475+
),
476+
),
477+
'expected' => array(
478+
'style' => 'background-clip:padding-box;-webkit-text-fill-color:currentColor;',
479+
),
480+
),
481+
'numeric position is not output' => array(
482+
'block_attributes' => array(
483+
'style' => array(
484+
'background' => array(
485+
'backgroundImage' => array( 'url' => 'https://example.com/image.jpg' ),
486+
'backgroundPosition' => 50,
487+
),
488+
),
489+
),
490+
'expected' => array(
491+
'class' => 'has-background',
492+
'style' => "background-image:url('https://example.com/image.jpg');background-size:cover;",
493+
),
494+
),
495+
'zero gradient outputs nothing' => array(
496+
'block_attributes' => array(
497+
'style' => array(
498+
'background' => array(
499+
'gradient' => 0,
500+
),
501+
),
502+
),
503+
'expected' => array(),
504+
),
505+
'empty background' => array(
506+
'block_attributes' => array(
507+
'style' => array(
508+
'background' => array(),
509+
),
510+
),
511+
'expected' => array(),
512+
),
513+
'no style attribute' => array(
514+
'block_attributes' => array(),
515+
'expected' => array(),
516+
),
517+
'background is not an array' => array(
518+
'block_attributes' => array(
519+
'style' => array(
520+
'background' => 'linear-gradient(red, blue)',
521+
),
522+
),
523+
'expected' => array(),
524+
),
525+
'attributes are not an array' => array(
526+
'block_attributes' => 'style',
527+
'expected' => array(),
528+
),
529+
);
530+
}
531+
393532
/**
394533
* Tests that background gradients using functions beyond rgb()/rgba(), and
395534
* gradients combined with a url() image, survive KSES sanitization.

‎phpunit/blocks/render-block-button-test.php‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -199,4 +199,48 @@ public function test_background_gradient_preset_applies_to_link() {
199199
$this->assertSame( 'background-image:var(--wp--preset--gradient--purple-to-yellow);', $processor->get_attribute( 'style' ) );
200200
$this->assertTrue( $processor->has_class( 'has-background' ) );
201201
}
202+
203+
/**
204+
* @covers ::gutenberg_render_block_core_button
205+
*/
206+
public function test_background_image_and_gradient_full_markup() {
207+
$attributes = array(
208+
'style' => array(
209+
'background' => array(
210+
'backgroundImage' => array(
211+
'url' => 'https://example.com/image.jpg',
212+
),
213+
'backgroundSize' => 'contain',
214+
'backgroundRepeat' => 'no-repeat',
215+
'backgroundAttachment' => 'fixed',
216+
'gradient' => 'linear-gradient(red, blue)',
217+
'backgroundClip' => 'text',
218+
),
219+
),
220+
);
221+
222+
$result = gutenberg_render_block_core_button( $attributes, self::$button_content );
223+
// WP 6.9+ encodes the apostrophe as ', earlier versions as '.
224+
$apostrophe = function_exists( 'get_block_bindings_supported_attributes' ) ? ''' : ''';
225+
226+
$this->assertSame(
227+
'<div class="wp-block-button"><a style="background-image:linear-gradient(red, blue), url(' . $apostrophe . 'https://example.com/image.jpg' . $apostrophe . ');background-position:50% 50%;background-repeat:no-repeat;background-size:contain;background-attachment:fixed;" class="wp-block-button__link wp-element-button has-background">Click me</a></div>',
228+
$result
229+
);
230+
}
231+
232+
/**
233+
* @covers ::gutenberg_render_block_core_button
234+
*/
235+
public function test_malformed_background_returns_content_unchanged() {
236+
$attributes = array(
237+
'style' => array(
238+
'background' => 'linear-gradient(red, blue)',
239+
),
240+
);
241+
242+
$result = gutenberg_render_block_core_button( $attributes, self::$button_content );
243+
244+
$this->assertSame( self::$button_content, $result );
245+
}
202246
}

0 commit comments

Comments
 (0)