gutenberg / build / style-engine / style-engine-gutenberg.php

style-engine-gutenberg.php in Gutenberg 17.2.4, at build/style-engine/style-engine-gutenberg.php

155 lines 6.4 KB

Raw Download Zip

1	<?php
2	/**
3	* Style engine: Public functions
4	*
5	* This file contains a variety of public functions developers can use to interact with
6	* the Style Engine API.
7	*
8	* @package Gutenberg
9	*/
10
11	/**
12	* Global public interface method to generate styles from a single style object, e.g.,
13	* the value of a block's attributes.style object or the top level styles in theme.json.
14	* See: https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/#styles and
15	* https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/
16	*
17	* Example usage:
18	*
19	* $styles = gutenberg_style_engine_get_styles( array( 'color' => array( 'text' => '#cccccc' ) ) );
20	* // Returns `array( 'css' => 'color: #cccccc', 'declarations' => array( 'color' => '#cccccc' ), 'classnames' => 'has-color' )`.
21	*
22	* @since 6.1.0
23	*
24	* @param array $block_styles The style object.
25	* @param array $options {
26	* Optional. An array of options. Default empty array.
27	*
28	* @type string\|null $context An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is `null`.
29	* When set, the Style Engine will attempt to store the CSS rules, where a selector is also passed.
30	* @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset\|<PRESET_TYPE>\|<PRESET_SLUG>`, to var( --wp--preset--* ) values. Default `false`.
31	* @type string $selector Optional. When a selector is passed, the value of `$css` in the return value will comprise a full CSS rule `$selector { ...$css_declarations }`,
32	* otherwise, the value will be a concatenated string of CSS declarations.
33	* }
34	*
35	* @return array {
36	* @type string $css A CSS ruleset or declarations block formatted to be placed in an HTML `style` attribute or tag.
37	* @type string[] $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
38	* @type string $classnames Classnames separated by a space.
39	* }
40	*/
41	function gutenberg_style_engine_get_styles( $block_styles, $options = array() ) {
42	$options = wp_parse_args(
43	$options,
44	array(
45	'selector' => null,
46	'context' => null,
47	'convert_vars_to_classnames' => false,
48	)
49	);
50
51	$parsed_styles = WP_Style_Engine_Gutenberg::parse_block_styles( $block_styles, $options );
52
53	// Output.
54	$styles_output = array();
55
56	if ( ! empty( $parsed_styles['declarations'] ) ) {
57	$styles_output['css'] = WP_Style_Engine_Gutenberg::compile_css( $parsed_styles['declarations'], $options['selector'] );
58	$styles_output['declarations'] = $parsed_styles['declarations'];
59	if ( ! empty( $options['context'] ) ) {
60	WP_Style_Engine_Gutenberg::store_css_rule( $options['context'], $options['selector'], $parsed_styles['declarations'] );
61	}
62	}
63
64	if ( ! empty( $parsed_styles['classnames'] ) ) {
65	$styles_output['classnames'] = implode( ' ', array_unique( $parsed_styles['classnames'] ) );
66	}
67
68	return array_filter( $styles_output );
69	}
70
71	/**
72	* Returns compiled CSS from a collection of selectors and declarations.
73	* Useful for returning a compiled stylesheet from any collection of CSS selector + declarations.
74	*
75	* Example usage:
76	* $css_rules = array( array( 'selector' => '.elephant-are-cool', 'declarations' => array( 'color' => 'gray', 'width' => '3em' ) ) );
77	* $css = gutenberg_style_engine_get_stylesheet_from_css_rules( $css_rules );
78	* // Returns `.elephant-are-cool{color:gray;width:3em}`.
79	*
80	* @since 6.1.0
81	*
82	* @param array $css_rules {
83	* Required. A collection of CSS rules.
84	*
85	* @type array ...$0 {
86	* @type string $selector A CSS selector.
87	* @type string[] $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
88	* }
89	* }
90	* @param array $options {
91	* Optional. An array of options. Default empty array.
92	*
93	* @type string\|null $context An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'.
94	* When set, the Style Engine will attempt to store the CSS rules.
95	* @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
96	* @type bool $prettify Whether to add new lines and indents to output. Default is to inherit the value of the global constant `SCRIPT_DEBUG`, if it is defined.
97	* }
98	*
99	* @return string A string of compiled CSS declarations, or empty string.
100	*/
101	function gutenberg_style_engine_get_stylesheet_from_css_rules( $css_rules, $options = array() ) {
102	if ( empty( $css_rules ) ) {
103	return '';
104	}
105
106	$options = wp_parse_args(
107	$options,
108	array(
109	'context' => null,
110	)
111	);
112
113	$css_rule_objects = array();
114	foreach ( $css_rules as $css_rule ) {
115	if ( empty( $css_rule['selector'] ) \|\| empty( $css_rule['declarations'] ) \|\| ! is_array( $css_rule['declarations'] ) ) {
116	continue;
117	}
118
119	if ( ! empty( $options['context'] ) ) {
120	WP_Style_Engine_Gutenberg::store_css_rule( $options['context'], $css_rule['selector'], $css_rule['declarations'] );
121	}
122
123	$css_rule_objects[] = new WP_Style_Engine_CSS_Rule_Gutenberg( $css_rule['selector'], $css_rule['declarations'] );
124	}
125
126	if ( empty( $css_rule_objects ) ) {
127	return '';
128	}
129
130	return WP_Style_Engine_Gutenberg::compile_stylesheet_from_css_rules( $css_rule_objects, $options );
131	}
132
133	/**
134	* Returns compiled CSS from a store, if found.
135	*
136	* @since 6.1.0
137	*
138	* @param string $context A valid context name, corresponding to an existing store key.
139	* @param array $options {
140	* Optional. An array of options. Default empty array.
141	*
142	* @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
143	* @type bool $prettify Whether to add new lines and indents to output. Default is to inherit the value of the global constant `SCRIPT_DEBUG`, if it is defined.
144	* }
145	*
146	* @return string A compiled CSS string.
147	*/
148	function gutenberg_style_engine_get_stylesheet_from_context( $context, $options = array() ) {
149	if ( empty( $context ) ) {
150	return '';
151	}
152
153	return WP_Style_Engine_Gutenberg::compile_stylesheet_from_css_rules( WP_Style_Engine_Gutenberg::get_store( $context )->get_all_rules(), $options );
154	}
155