[ Index ]

PHP Cross Reference of WordPress

title

Body

[close]

/wp-includes/ -> class-wp-theme-json.php (summary)

WP_Theme_JSON class

File Size: 1970 lines (61 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class

WP_Theme_JSON:: (38 methods):
  __construct()
  maybe_opt_in_into_settings()
  do_opt_in_into_settings()
  sanitize()
  get_blocks_metadata()
  remove_keys_not_in_schema()
  get_settings()
  get_stylesheet()
  get_custom_templates()
  get_template_parts()
  get_block_classes()
  get_preset_classes()
  get_css_variables()
  to_ruleset()
  append_to_selector()
  compute_preset_classes()
  scope_selector()
  get_settings_values_by_slug()
  get_settings_slugs()
  replace_slug_in_string()
  compute_preset_vars()
  compute_theme_vars()
  flatten_tree()
  compute_style_properties()
  get_property_value()
  get_setting_nodes()
  get_style_nodes()
  merge()
  should_override_preset()
  get_default_slugs()
  get_name_from_defaults()
  filter_slugs()
  remove_insecure_properties()
  remove_insecure_settings()
  remove_insecure_styles()
  is_safe_css_declaration()
  get_raw_data()
  get_from_editor_settings()


Class: WP_Theme_JSON  - X-Ref

Class that encapsulates the processing of structures that adhere to the theme.json spec.

This class is for internal core usage and is not supposed to be used by extenders (plugins and/or themes).
This is a low-level API that may need to do breaking changes. Please,
use get_global_settings, get_global_styles, and get_global_stylesheet instead.

__construct( $theme_json = array()   X-Ref
Constructor.

param: array  $theme_json A structure that follows the theme.json schema.
param: string $origin     Optional. What source of data this object represents.
since: 5.8.0

maybe_opt_in_into_settings( $theme_json )   X-Ref
Enables some opt-in settings if theme declared support.

param: array $theme_json A theme.json structure to modify.
since: 5.9.0
return: array The modified theme.json structure.

do_opt_in_into_settings( &$context )   X-Ref
Enables some settings.

param: array $context The context to which the settings belong.
since: 5.9.0

sanitize( $input, $valid_block_names, $valid_element_names )   X-Ref
Sanitizes the input according to the schemas.

param: array $input               Structure to sanitize.
param: array $valid_block_names   List of valid block names.
param: array $valid_element_names List of valid element names.
since: 5.8.0
since: 5.9.0 Added the `$valid_block_names` and `$valid_element_name` parameters.
return: array The sanitized output.

get_blocks_metadata()   X-Ref
Returns the metadata for each block.

Example:

{
'core/paragraph': {
'selector': 'p',
'elements': {
'link' => 'link selector',
'etc'  => 'element selector'
}
},
'core/heading': {
'selector': 'h1',
'elements': {}
},
'core/image': {
'selector': '.wp-block-image',
'duotone': 'img',
'elements': {}
}
}

since: 5.8.0
since: 5.9.0 Added `duotone` key with CSS selector.
return: array Block metadata.

remove_keys_not_in_schema( $tree, $schema )   X-Ref
Given a tree, removes the keys that are not present in the schema.

It is recursive and modifies the input in-place.

param: array $tree   Input to process.
param: array $schema Schema to adhere to.
since: 5.8.0
return: array Returns the modified $tree.

get_settings()   X-Ref
Returns the existing settings for each block.

Example:

{
'root': {
'color': {
'custom': true
}
},
'core/paragraph': {
'spacing': {
'customPadding': true
}
}
}

since: 5.8.0
return: array Settings per block.

get_stylesheet( $types = array( 'variables', 'styles', 'presets' )   X-Ref
Returns the stylesheet that results of processing
the theme.json structure this object represents.

param: array $types   Types of styles to load. Will load all by default. It accepts:
param: array $origins A list of origins to include. By default it includes `self::VALID_ORIGINS`.
since: 5.8.0
since: 5.9.0 Removed the `$type` parameter`, added the `$types` and `$origins` parameters.
return: string Stylesheet.

get_custom_templates()   X-Ref
Returns the page templates of the current theme.

since: 5.9.0
return: array

get_template_parts()   X-Ref
Returns the template part data of current theme.

since: 5.9.0
return: array

get_block_classes( $style_nodes )   X-Ref
Converts each style section into a list of rulesets
containing the block styles to be appended to the stylesheet.

See glossary at https://developer.mozilla.org/en-US/docs/Web/CSS/Syntax

For each section this creates a new ruleset such as:

block-selector {
style-property-one: value;
}

param: array $style_nodes Nodes with styles.
since: 5.8.0 As `get_block_styles()`.
since: 5.9.0 Renamed from `get_block_styles()` to `get_block_classes()`
return: string The new stylesheet.

get_preset_classes( $setting_nodes, $origins )   X-Ref
Creates new rulesets as classes for each preset value such as:

.has-value-color {
color: value;
}

.has-value-background-color {
background-color: value;
}

.has-value-font-size {
font-size: value;
}

.has-value-gradient-background {
background: value;
}

p.has-value-gradient-background {
background: value;
}

param: array $setting_nodes Nodes with settings.
param: array $origins       List of origins to process presets from.
since: 5.9.0
return: string The new stylesheet.

get_css_variables( $nodes, $origins )   X-Ref
Converts each styles section into a list of rulesets
to be appended to the stylesheet.
These rulesets contain all the css variables (custom variables and preset variables).

See glossary at https://developer.mozilla.org/en-US/docs/Web/CSS/Syntax

For each section this creates a new ruleset such as:

block-selector {
--wp--preset--category--slug: value;
--wp--custom--variable: value;
}

param: array $nodes   Nodes with settings.
param: array $origins List of origins to process.
since: 5.8.0
since: 5.9.0 Added the `$origins` parameter.
return: string The new stylesheet.

to_ruleset( $selector, $declarations )   X-Ref
Given a selector and a declaration list,
creates the corresponding ruleset.

param: string $selector     CSS selector.
param: array  $declarations List of declarations.
since: 5.8.0
return: string CSS ruleset.

append_to_selector( $selector, $to_append )   X-Ref
No description

compute_preset_classes( $settings, $selector, $origins )   X-Ref
Given a settings array, it returns the generated rulesets
for the preset classes.

param: array  $settings Settings to process.
param: string $selector Selector wrapping the classes.
param: array  $origins  List of origins to process.
since: 5.8.0
since: 5.9.0 Added the `$origins` parameter.
return: string The result of processing the presets.

scope_selector( $scope, $selector )   X-Ref
Function that scopes a selector with another one. This works a bit like
SCSS nesting except the `&` operator isn't supported.

<code>
$scope = '.a, .b .c';
$selector = '> .x, .y';
$merged = scope_selector( $scope, $selector );
// $merged is '.a > .x, .a .y, .b .c > .x, .b .c .y'
</code>

param: string $scope    Selector to scope to.
param: string $selector Original selector.
since: 5.9.0
return: string Scoped selector.

get_settings_values_by_slug( $settings, $preset_metadata, $origins )   X-Ref
Gets preset values keyed by slugs based on settings and metadata.

<code>
$settings = array(
'typography' => array(
'fontFamilies' => array(
array(
'slug'       => 'sansSerif',
'fontFamily' => '"Helvetica Neue", sans-serif',
),
array(
'slug'   => 'serif',
'colors' => 'Georgia, serif',
)
),
),
);
$meta = array(
'path'      => array( 'typography', 'fontFamilies' ),
'value_key' => 'fontFamily',
);
$values_by_slug = get_settings_values_by_slug();
// $values_by_slug === array(
//   'sans-serif' => '"Helvetica Neue", sans-serif',
//   'serif'      => 'Georgia, serif',
// );
</code>

param: array $settings        Settings to process.
param: array $preset_metadata One of the PRESETS_METADATA values.
param: array $origins         List of origins to process.
since: 5.9.0
return: array Array of presets where each key is a slug and each value is the preset value.

get_settings_slugs( $settings, $preset_metadata, $origins = self::VALID_ORIGINS )   X-Ref
Similar to get_settings_values_by_slug, but doesn't compute the value.

param: array $settings        Settings to process.
param: array $preset_metadata One of the PRESETS_METADATA values.
param: array $origins         List of origins to process.
since: 5.9.0
return: array Array of presets where the key and value are both the slug.

replace_slug_in_string( $input, $slug )   X-Ref
Transform a slug into a CSS Custom Property.

param: string $input String to replace.
param: string $slug  The slug value to use to generate the custom property.
since: 5.9.0
return: string The CSS Custom Property. Something along the lines of `--wp--preset--color--black`.

compute_preset_vars( $settings, $origins )   X-Ref
Given the block settings, it extracts the CSS Custom Properties
for the presets and adds them to the $declarations array
following the format:

array(
'name'  => 'property_name',
'value' => 'property_value,
)

param: array $settings Settings to process.
param: array $origins  List of origins to process.
since: 5.8.0
since: 5.9.0 Added the `$origins` parameter.
return: array Returns the modified $declarations.

compute_theme_vars( $settings )   X-Ref
Given an array of settings, it extracts the CSS Custom Properties
for the custom values and adds them to the $declarations
array following the format:

array(
'name'  => 'property_name',
'value' => 'property_value,
)

param: array $settings Settings to process.
since: 5.8.0
return: array Returns the modified $declarations.

flatten_tree( $tree, $prefix = '', $token = '--' )   X-Ref
Given a tree, it creates a flattened one
by merging the keys and binding the leaf values
to the new keys.

It also transforms camelCase names into kebab-case
and substitutes '/' by '-'.

This is thought to be useful to generate
CSS Custom Properties from a tree,
although there's nothing in the implementation
of this function that requires that format.

For example, assuming the given prefix is '--wp'
and the token is '--', for this input tree:

{
'some/property': 'value',
'nestedProperty': {
'sub-property': 'value'
}
}

it'll return this output:

{
'--wp--some-property': 'value',
'--wp--nested-property--sub-property': 'value'
}

param: array  $tree   Input tree to process.
param: string $prefix Optional. Prefix to prepend to each variable. Default empty string.
param: string $token  Optional. Token to use between levels. Default '--'.
since: 5.8.0
return: array The flattened tree.

compute_style_properties( $styles, $settings = array()   X-Ref
Given a styles array, it extracts the style properties
and adds them to the $declarations array following the format:

array(
'name'  => 'property_name',
'value' => 'property_value,
)

param: array $styles    Styles to process.
param: array $settings  Theme settings.
param: array $properties Properties metadata.
since: 5.8.0
since: 5.9.0 Added the `$settings` and `$properties` parameters.
return: array Returns the modified $declarations.

get_property_value( $styles, $path )   X-Ref
Returns the style property for the given path.

It also converts CSS Custom Property stored as
"var:preset|color|secondary" to the form
"--wp--preset--color--secondary".

param: array $styles Styles subtree.
param: array $path   Which property to process.
since: 5.8.0
since: 5.9.0 Added support for values of array type, which are returned as is.
return: string|array Style property value.

get_setting_nodes( $theme_json, $selectors = array()   X-Ref
Builds metadata for the setting nodes, which returns in the form of:

[
[
'path'     => ['path', 'to', 'some', 'node' ],
'selector' => 'CSS selector for some node'
],
[
'path'     => [ 'path', 'to', 'other', 'node' ],
'selector' => 'CSS selector for other node'
],
]

param: array $theme_json The tree to extract setting nodes from.
param: array $selectors  List of selectors per block.
since: 5.8.0
return: array

get_style_nodes( $theme_json, $selectors = array()   X-Ref
Builds metadata for the style nodes, which returns in the form of:

[
[
'path'     => [ 'path', 'to', 'some', 'node' ],
'selector' => 'CSS selector for some node',
'duotone'  => 'CSS selector for duotone for some node'
],
[
'path'     => ['path', 'to', 'other', 'node' ],
'selector' => 'CSS selector for other node',
'duotone'  => null
],
]

param: array $theme_json The tree to extract style nodes from.
param: array $selectors  List of selectors per block.
since: 5.8.0
return: array

merge( $incoming )   X-Ref
Merge new incoming data.

param: WP_Theme_JSON $incoming Data to merge.
since: 5.8.0
since: 5.9.0 Duotone preset also has origins.

should_override_preset( $theme_json, $path, $override )   X-Ref
Returns whether a presets should be overriden or not.

param: array      $theme_json The theme.json like structure to inspect.
param: array      $path Path to inspect.
param: bool|array $override Data to compute whether to override the preset.
since: 5.9.0
return: boolean

get_default_slugs( $data, $node_path )   X-Ref
Returns the default slugs for all the presets in an associative array
whose keys are the preset paths and the leafs is the list of slugs.

For example:

array(
'color' => array(
'palette'   => array( 'slug-1', 'slug-2' ),
'gradients' => array( 'slug-3', 'slug-4' ),
),
)

param: array $data      A theme.json like structure.
param: array $node_path The path to inspect. It's 'settings' by default.
since: 5.9.0
return: array

get_name_from_defaults( $slug, $base_path )   X-Ref
No description

filter_slugs( $node, $slugs )   X-Ref
Removes the preset values whose slug is equal to any of given slugs.

param: array $node  The node with the presets to validate.
param: array $slugs The slugs that should not be overriden.
since: 5.9.0
return: array The new node.

remove_insecure_properties( $theme_json )   X-Ref
Removes insecure data from theme.json.

param: array $theme_json Structure to sanitize.
since: 5.9.0
return: array Sanitized structure.

remove_insecure_settings( $input )   X-Ref
Processes a setting node and returns the same node
without the insecure settings.

param: array $input Node to process.
since: 5.9.0
return: array

remove_insecure_styles( $input )   X-Ref
Processes a style node and returns the same node
without the insecure styles.

param: array $input Node to process.
since: 5.9.0
return: array

is_safe_css_declaration( $property_name, $property_value )   X-Ref
Checks that a declaration provided by the user is safe.

param: string $property_name  Property name in a CSS declaration, i.e. the `color` in `color: red`.
param: string $property_value Value in a CSS declaration, i.e. the `red` in `color: red`.
since: 5.9.0
return: bool

get_raw_data()   X-Ref
Returns the raw data.

since: 5.8.0
return: array Raw data.

get_from_editor_settings( $settings )   X-Ref
Transforms the given editor settings according the
add_theme_support format to the theme.json format.

param: array $settings Existing editor settings.
since: 5.8.0
return: array Config that adheres to the theme.json schema.



Generated: Tue Jan 18 01:00:03 2022 Cross-referenced by PHPXref 0.7.1