Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Style engine: allow CSS var output for fontSize and fontFamily and update docs #56528

Merged
merged 3 commits into from
Nov 27, 2023
Merged

Style engine: allow CSS var output for fontSize and fontFamily and update docs #56528

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5e9d8f8
- Loading style engine files that use utils classes after the utils c…
ramonjd Nov 26, 2023
a84dc33
Apply suggestions from code review
ramonjd Nov 27, 2023
7a5198e
Replacing spacing indents with tabs. Disclaimer: This commit does not…
ramonjd Nov 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions lib/load.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -224,12 +224,12 @@ function () {

// Copied package PHP files.
if ( is_dir( __DIR__ . '/../build/style-engine' ) ) {
require_once __DIR__ . '/../build/style-engine/style-engine-gutenberg.php';
require_once __DIR__ . '/../build/style-engine/class-wp-style-engine-gutenberg.php';
require_once __DIR__ . '/../build/style-engine/class-wp-style-engine-css-declarations-gutenberg.php';
require_once __DIR__ . '/../build/style-engine/class-wp-style-engine-css-rule-gutenberg.php';
require_once __DIR__ . '/../build/style-engine/class-wp-style-engine-css-rules-store-gutenberg.php';
require_once __DIR__ . '/../build/style-engine/class-wp-style-engine-processor-gutenberg.php';
require_once __DIR__ . '/../build/style-engine/class-wp-style-engine-gutenberg.php';
require_once __DIR__ . '/../build/style-engine/style-engine-gutenberg.php';
}

// Block supports overrides.
Expand Down
6 changes: 6 additions & 0 deletions packages/style-engine/class-wp-style-engine.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,9 @@ final class WP_Style_Engine {
'property_keys' => array(
'default' => 'font-size',
),
'css_vars' => array(
'font-size' => '--wp--preset--font-size--$slug',
),
'path' => array( 'typography', 'fontSize' ),
'classnames' => array(
'has-$slug-font-size' => 'font-size',
Expand All @@ -219,6 +222,9 @@ final class WP_Style_Engine {
'property_keys' => array(
'default' => 'font-family',
),
'css_vars' => array(
'font-family' => '--wp--preset--font-family--$slug',
),
'path' => array( 'typography', 'fontFamily' ),
'classnames' => array(
'has-$slug-font-family' => 'font-family',
Expand Down
57 changes: 37 additions & 20 deletions packages/style-engine/docs/using-the-style-engine-with-block-supports.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,11 @@ The global function `wp_style_engine_get_styles` accepts a style object as its f

```php
$block_styles = array(
'spacing' => array( 'padding' => '10px', 'margin' => array( 'top' => '1em') ),
'typography' => array( 'fontSize' => '2.2rem' ),
'spacing' => array( 'padding' => '10px', 'margin' => array( 'top' => '1em') ),
'typography' => array( 'fontSize' => '2.2rem' ),
);
$styles = wp_style_engine_get_styles(
$block_styles
$block_styles
);
print_r( $styles );

Expand All @@ -51,7 +51,7 @@ When [registering a block support](https://developer.wordpress.org/reference/cla

If a block has opted into the block support, the values of "class" and "style" will be applied to the block element's "class" and "style" attributes accordingly when rendered in the frontend HTML. Note, this applies only to server-side rendered blocks, for example, the [Site Title block](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/#site-title).

The callback receives `$block_type` and `$block_attributes` as arguments. The `style` attribute within `$block_attributes` only contains the raw style object, if any styles have been set for the block, and not any CSS or classnames to be applied to the block's HTML elements.
The callback receives `$block_type` and `$block_attributes` as arguments. The `style` attribute within `$block_attributes` only contains the raw style object, if any styles have been set for the block, and not any CSS or classnames to be applied to the block's HTML elements.

Here is where `wp_style_engine_get_styles` comes in handy: it will generate CSS and, if appropriate, classnames to be added to the "style" and "class" HTML attributes in the final rendered block markup.

Expand Down Expand Up @@ -100,32 +100,32 @@ Before passing the block style object to the Style Engine, you'll need to take i

If a block either:

- has no support for a style, or
- has no support for a style, or
- skips serialization of that style

it's likely that you'll want to remove those style values from the style object before passing it to the Style Engine with help of two functions:

- wp_should_skip_block_supports_serialization()
- block_has_support()

We can now update the apply callback code above so that we'll only return "style" and "class", where a block has support and it doesn't skip serialization:
We can now update the "apply" callback code above so that we'll only return "style" and "class", where a block has support, and it doesn't skip serialization:

```php
function gutenberg_apply_colors_support( $block_type, $block_attributes ) {
// The return value.
$attributes = array();

// Return early if the block skips all serialization for block supports.
if ( gutenberg_should_skip_block_supports_serialization( $block_type, 'color' ) ) {
return $attributes;
}

// Checks for support and skip serialization.
$has_text_support = block_has_support( $block_type, array( 'color', 'text' ), false );
$has_text_support = block_has_support( $block_type, array( 'color', 'text' ), false );
$has_background_support = block_has_support( $block_type, array( 'color', 'background' ), false );
$skips_serialization_of_color_text = wp_should_skip_block_supports_serialization( $block_type, 'color', 'text' );
$skips_serialization_of_color_background = wp_should_skip_block_supports_serialization( $block_type, 'color', 'background' );
$skips_serialization_of_color_text = wp_should_skip_block_supports_serialization( $block_type, 'color', 'text' );
$skips_serialization_of_color_background = wp_should_skip_block_supports_serialization( $block_type, 'color', 'background' );

// Get the color styles from the style object.
$block_color_styles = isset( $block_attributes['style']['color'] ) ? $block_attributes['style']['color'] : null;

Expand Down Expand Up @@ -161,7 +161,7 @@ Styling a block using these presets normally involves adding the selector to the

For styles that can have preset values, such as text color and font family, the Style Engine knows how to construct the classnames using the preset slug.

To discern CSS values from preset values however, the Style Engine expects a special format.
To discern CSS values from preset values, the Style Engine expects a special format.

Preset values must follow the pattern `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`.

Expand All @@ -171,13 +171,16 @@ Example:

```php
// Let's say the block attributes styles contain a fontSize preset slug of "small".
// $block_attributes['fontSize'] = 'var:preset|font-size|small';
$preset_font_size = "var:preset|font-size|{$block_attributes['fontSize']}";
// Now let's say the block attributes styles contain a backgroundColor preset slug of "blue".
// $block_attributes['backgroundColor'] = 'var:preset|color|blue';
$preset_background_color = "var:preset|color|{$block_attributes['backgroundColor']}";

$block_styles = array(
'typography' => array( 'fontSize' => $preset_font_size ),
'color' => array( 'background' => $preset_background_color )
'color' => array( 'background' => $preset_background_color ),
'spacing' => array( 'padding' => '10px', 'margin' => array( 'top' => '1em') ),
);

$styles = wp_style_engine_get_styles(
Expand All @@ -187,19 +190,29 @@ print_r( $styles );

/*
array(
'css' => 'background-color:var(--wp--preset--color--blue);font-size:var(--wp--preset--font-size--small);',
'classnames' => 'has-background-color has-blue-background-color has-small-font-size',
'css' => 'background-color:var(--wp--preset--color--blue);padding:10px;margin-top:1em;font-size:var(--wp--preset--font-size--small);',
'declarations' => array(
'background-color' => 'var(--wp--preset--color--blue)',
'padding' => '10px',
'margin-top' => '1em',
'font-size' => 'var(--wp--preset--font-size--small)',
),
'classnames' => 'has-background has-blue-background-color has-small-font-size',
)
*/
```

If you don't want the Style Engine to output the CSS custom vars as well, which you might not if you're applying both the CSS and classnames to the block element, you can pass `'convert_vars_to_classnames' => true` in the options array.
If you don't want the Style Engine to output the CSS custom vars in the generated CSS string as well, which you might not if you're applying both the CSS rules and classnames to the block element, you can pass `'convert_vars_to_classnames' => true` in the options array.

This flag means "convert the vars to classnames and don't output the vars to the CSS". The Style Engine will therefore **only** generate the required classnames and omit the CSS custom vars in the CSS.

Using the above example code, observe the different output when we pass the option:

```php
$options = array(
// Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is `false`.
'convert_vars_to_classnames' => 'true',
'convert_vars_to_classnames' => true,
);

$styles = wp_style_engine_get_styles(
$block_styles,
$options
Expand All @@ -208,8 +221,12 @@ print_r( $styles );

/*
array(
'css' => 'letter-spacing:12px;', // non-preset-based CSS will still be compiled.
'classnames' => 'has-background-color has-blue-background-color has-small-font-size',
'css' => 'padding:10px;margin-top:1em;',
'declarations' => array(
'padding' => '10px',
'margin-top' => '1em',
),
'classnames' => 'has-background has-blue-background-color has-small-font-size',
)
*/
```
Expand Down
15 changes: 11 additions & 4 deletions phpunit/style-engine/style-engine-test.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -238,19 +238,26 @@ public function data_wp_style_engine_get_styles() {

'elements_with_css_var_value' => array(
'block_styles' => array(
'color' => array(
'color' => array(
'text' => 'var:preset|color|my-little-pony',
),
'typography' => array(
'fontSize' => 'var:preset|font-size|cabbage-patch',
'fontFamily' => 'var:preset|font-family|transformers',
),
),
'options' => array(
'selector' => '.wp-selector',
),
'expected_output' => array(
'css' => '.wp-selector{color:var(--wp--preset--color--my-little-pony);}',
'css' => '.wp-selector{color:var(--wp--preset--color--my-little-pony);font-size:var(--wp--preset--font-size--cabbage-patch);font-family:var(--wp--preset--font-family--transformers);}',
'declarations' => array(
'color' => 'var(--wp--preset--color--my-little-pony)',
'color' => 'var(--wp--preset--color--my-little-pony)',
'font-size' => 'var(--wp--preset--font-size--cabbage-patch)',
'font-family' => 'var(--wp--preset--font-family--transformers)',

),
'classnames' => 'has-text-color has-my-little-pony-color',
'classnames' => 'has-text-color has-my-little-pony-color has-cabbage-patch-font-size has-transformers-font-family',
),
),

Expand Down
Loading