![(please configure the [header_logo] section in trac.ini)](/chrome/site/your_project_logo.png){kind=logo}
- Timestamp:
- 05/17/2023 11:56:47 AM (3 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/src/wp-includes/style-engine/class-wp-style-engine.php
r55733 r55819 11 11 * The main class integrating all other WP_Style_Engine_* classes. 12 12 * 13 * The Style Engine aims to provide a consistent API for rendering styling for blocks across both client-side and server-side applications. 13 * The Style Engine aims to provide a consistent API for rendering styling for blocks 14 * across both client-side and server-side applications. 14 15 * 15 16 * This class is final and should not be extended. 16 * This class is for internal Core usage and is not supposed to be used by extenders (plugins and/or themes). 17 * This is a low-level API that may need to do breaking changes. Please, use wp_style_engine_get_styles() instead. 17 * 18 * This class is for internal Core usage and is not supposed to be used by extenders 19 * (plugins and/or themes). This is a low-level API that may need to do breaking changes. 20 * Please, use wp_style_engine_get_styles() instead. 18 21 * 19 22 * @access private … … 25 28 * Style definitions that contain the instructions to 26 29 * parse/output valid Gutenberg styles from a block's attributes. 27 * For every style definition, the follow properties are valid: 28 * - classnames => (array) an array of classnames to be returned for block styles. The key is a classname or pattern. 29 * A value of `true` means the classname should be applied always. Otherwise, a valid CSS property (string) 30 * to match the incoming value, e.g., "color" to match var:preset|color|somePresetSlug. 31 * - css_vars => (array) an array of key value pairs used to generate CSS var values. The key is a CSS var pattern, whose `$slug` fragment will be replaced with a preset slug. 32 * The value should be a valid CSS property (string) to match the incoming value, e.g., "color" to match var:preset|color|somePresetSlug. 33 * - property_keys => (array) array of keys whose values represent a valid CSS property, e.g., "margin" or "border". 34 * - path => (array) a path that accesses the corresponding style value in the block style object. 35 * - value_func => (string) the name of a function to generate a CSS definition array for a particular style object. The output of this function should be `array( "$property" => "$value", ... )`. 30 * 31 * For every style definition, the following properties are valid: 32 * 33 * - classnames => (array) An array of classnames to be returned for block styles. 34 * The key is a classname or pattern. 35 * A value of `true` means the classname should be applied always. 36 * Otherwise, a valid CSS property (string) to match the incoming value, 37 * e.g. "color" to match var:preset|color|somePresetSlug. 38 * - css_vars => (array) An array of key value pairs used to generate CSS var values. 39 * The key is a CSS var pattern, whose `$slug` fragment will be replaced with a preset slug. 40 * The value should be a valid CSS property (string) to match the incoming value, 41 * e.g. "color" to match var:preset|color|somePresetSlug. 42 * - property_keys => (array) An array of keys whose values represent a valid CSS property, 43 * e.g. "margin" or "border". 44 * - path => (array) A path that accesses the corresponding style value in the block style object. 45 * - value_func => (string) The name of a function to generate a CSS definition array 46 * for a particular style object. The output of this function should be 47 * `array( "$property" => "$value", ... )`. 36 48 * 37 49 * @since 6.1.0 … … 228 240 229 241 /** 230 * Util: Extracts the slug in kebab case from a preset string, e.g., `heavenly-blue` from `var:preset|color|heavenlyBlue`. 242 * Util: Extracts the slug in kebab case from a preset string, 243 * e.g. `heavenly-blue` from `var:preset|color|heavenlyBlue`. 231 244 * 232 245 * @since 6.1.0 233 246 * 234 247 * @param string $style_value A single CSS preset value. 235 * @param string $property_key The CSS property that is the second element of the preset string. Used for matching. 248 * @param string $property_key The CSS property that is the second element of the preset string. 249 * Used for matching. 236 250 * @return string The slug, or empty string if not found. 237 251 */ 238 252 protected static function get_slug_from_preset_value( $style_value, $property_key ) { 239 if ( is_string( $style_value ) && is_string( $property_key ) && str_contains( $style_value, "var:preset|{$property_key}|" ) ) { 253 if ( is_string( $style_value ) && is_string( $property_key ) 254 && str_contains( $style_value, "var:preset|{$property_key}|" ) 255 ) { 240 256 $index_to_splice = strrpos( $style_value, '|' ) + 1; 241 257 return _wp_to_kebab_case( substr( $style_value, $index_to_splice ) ); … … 245 261 246 262 /** 247 * Util: Generates a CSS var string, e.g., `var(--wp--preset--color--background)` from a preset string such as `var:preset|space|50`. 263 * Util: Generates a CSS var string, e.g. `var(--wp--preset--color--background)` 264 * from a preset string such as `var:preset|space|50`. 248 265 * 249 266 * @since 6.1.0 250 267 * 251 268 * @param string $style_value A single CSS preset value. 252 * @param string[] $css_vars An associate array of CSS var patterns used to generate the var string. 269 * @param string[] $css_vars An associate array of CSS var patterns 270 * used to generate the var string. 253 271 * @return string The CSS var, or an empty string if no match for slug found. 254 272 */ … … 285 303 * 286 304 * @param string $store_name A valid store key. 287 * @param string $css_selector When a selector is passed, the function will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values. 288 * @param string[] $css_declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. 305 * @param string $css_selector When a selector is passed, the function will return 306 * a full CSS rule `$selector { ...rules }` 307 * otherwise a concatenated string of properties and values. 308 * @param string[] $css_declarations An associative array of CSS definitions, 309 * e.g. `array( "$property" => "$value", "$property" => "$value" )`. 289 310 */ 290 311 public static function store_css_rule( $store_name, $css_selector, $css_declarations ) { … … 309 330 /** 310 331 * Returns classnames and CSS based on the values in a styles object. 332 * 311 333 * Return values are parsed based on the instructions in BLOCK_STYLE_DEFINITIONS_METADATA. 312 334 * … … 317 339 * Optional. An array of options. Default empty array. 318 340 * 319 * @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. 320 * @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 }`, 321 * otherwise, the value will be a concatenated string of CSS declarations. 341 * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, 342 * e.g. `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, 343 * to `var( --wp--preset--* )` values. Default false. 344 * @type string $selector Optional. When a selector is passed, 345 * the value of `$css` in the return value will comprise 346 * a full CSS rule `$selector { ...$css_declarations }`, 347 * otherwise, the value will be a concatenated string 348 * of CSS declarations. 322 349 * } 323 350 * @return array { 324 351 * @type string[] $classnames Array of class names. 325 * @type string[] $declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. 352 * @type string[] $declarations An associative array of CSS definitions, 353 * e.g. `array( "$property" => "$value", "$property" => "$value" )`. 326 354 * } 327 355 */ … … 356 384 357 385 /** 358 * Returns classnames, and generates classname(s) from a CSS preset property pattern, e.g., `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`. 359 * 360 * @since 6.1.0 361 * 362 * @param string $style_value A single raw style value or CSS preset property from the `$block_styles` array. 386 * Returns classnames, and generates classname(s) from a CSS preset property pattern, 387 * e.g. `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`. 388 * 389 * @since 6.1.0 390 * 391 * @param string $style_value A single raw style value or CSS preset property 392 * from the `$block_styles` array. 363 393 * @param array $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA. 364 394 * @return string[] An array of CSS classnames, or empty array if there are none. … … 403 433 * Optional. An array of options. Default empty array. 404 434 * 405 * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g.,406 * `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, to `var( --wp--preset--* )` values.407 * Default false.435 * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, 436 * e.g. `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, 437 * to `var( --wp--preset--* )` values. Default false. 408 438 * } 409 * @return string[] An associative array of CSS definitions, e.g. ,`array( "$property" => "$value", "$property" => "$value" )`.439 * @return string[] An associative array of CSS definitions, e.g. `array( "$property" => "$value", "$property" => "$value" )`. 410 440 */ 411 441 protected static function get_css_declarations( $style_value, $style_definition, $options = array() ) { … … 481 511 * 482 512 * @param array $style_value A single raw style value from `$block_styles` array. 483 * @param array $individual_property_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA representing an individual property of a CSS property, e.g., 'top' in 'border-top'. 513 * @param array $individual_property_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA 514 * representing an individual property of a CSS property, 515 * e.g. 'top' in 'border-top'. 484 516 * @param array $options { 485 517 * Optional. An array of options. Default empty array. 486 518 * 487 * @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. 519 * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, 520 * e.g. `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, 521 * to `var( --wp--preset--* )` values. Default false. 488 522 * } 489 * @return string[] An associative array of CSS definitions, e.g. ,`array( "$property" => "$value", "$property" => "$value" )`.523 * @return string[] An associative array of CSS definitions, e.g. `array( "$property" => "$value", "$property" => "$value" )`. 490 524 */ 491 525 protected static function get_individual_property_css_declarations( $style_value, $individual_property_definition, $options = array() ) { … … 495 529 496 530 /* 497 * The first item in $individual_property_definition['path'] array tells us the style property, e.g., "border". 498 * We use this to get a corresponding CSS style definition such as "color" or "width" from the same group. 499 * The second item in $individual_property_definition['path'] array refers to the individual property marker, e.g., "top". 531 * The first item in $individual_property_definition['path'] array 532 * tells us the style property, e.g. "border". We use this to get a corresponding 533 * CSS style definition such as "color" or "width" from the same group. 534 * 535 * The second item in $individual_property_definition['path'] array 536 * refers to the individual property marker, e.g. "top". 500 537 */ 501 538 $definition_group_key = $individual_property_definition['path'][0]; … … 515 552 if ( $style_definition && isset( $style_definition['property_keys']['individual'] ) ) { 516 553 // Set a CSS var if there is a valid preset value. 517 if ( is_string( $value ) && str_contains( $value, 'var:' ) && ! $should_skip_css_vars && ! empty( $individual_property_definition['css_vars'] ) ) { 554 if ( is_string( $value ) && str_contains( $value, 'var:' ) 555 && ! $should_skip_css_vars && ! empty( $individual_property_definition['css_vars'] ) 556 ) { 518 557 $value = static::get_css_var_value( $value, $individual_property_definition['css_vars'] ); 519 558 } 520 $individual_css_property = sprintf( $style_definition['property_keys']['individual'], $individual_property_key ); 559 560 $individual_css_property = sprintf( $style_definition['property_keys']['individual'], $individual_property_key ); 561 521 562 $css_declarations[ $individual_css_property ] = $value; 522 563 } … … 530 571 * @since 6.1.0 531 572 * 532 * @param string[] $css_declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. 533 * @param string $css_selector When a selector is passed, the function will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values. 573 * @param string[] $css_declarations An associative array of CSS definitions, 574 * e.g. `array( "$property" => "$value", "$property" => "$value" )`. 575 * @param string $css_selector When a selector is passed, the function will return 576 * a full CSS rule `$selector { ...rules }`, 577 * otherwise a concatenated string of properties and values. 534 578 * @return string A compiled CSS string. 535 579 */ … … 554 598 * @since 6.1.0 555 599 * 556 * @param WP_Style_Engine_CSS_Rule[] $css_rules An array of WP_Style_Engine_CSS_Rule objects from a store or otherwise. 600 * @param WP_Style_Engine_CSS_Rule[] $css_rules An array of WP_Style_Engine_CSS_Rule objects 601 * from a store or otherwise. 557 602 * @param array $options { 558 603 * Optional. An array of options. Default empty array. 559 604 * 560 * @type string|null $context An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'. 605 * @type string|null $context An identifier describing the origin of the style object, 606 * e.g. 'block-supports' or 'global-styles'. Default 'block-supports'. 561 607 * When set, the style engine will attempt to store the CSS rules. 562 * @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`. 563 * @type bool $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined. 608 * @type bool $optimize Whether to optimize the CSS output, e.g. combine rules. 609 * Default false. 610 * @type bool $prettify Whether to add new lines and indents to output. 611 * Defaults to whether the `SCRIPT_DEBUG` constant is defined. 564 612 * } 565 613 * @return string A compiled stylesheet from stored CSS rules.
Note:
See TracChangeset
for help on using the changeset viewer.
