mirror of
https://github.com/WordPress/WordPress.git
synced 2024-09-28 15:17:42 +02:00
Docs: Some documentation improvements for WP_Theme_JSON and WP_Theme_JSON_Resolver classes:
* Make the `@since 5.9.0` notes more specific. When mentioning that parameters or values have been added or changed, it is generally also helpful to include their exact names and the nature of changes for future reference. * Update some DocBlocks per the documentation standards. Follow-up to [52049], [52306]. See #53399, #54336. Built from https://develop.svn.wordpress.org/trunk@52320 git-svn-id: http://core.svn.wordpress.org/trunk@51912 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Sergey Biryukov
parent
3d5b5f21e1
commit
7f9d7a5905
@ -56,7 +56,7 @@ class WP_Theme_JSON_Resolver {
|
||||
* that holds the user data.
|
||||
*
|
||||
* @since 5.9.0
|
||||
* @var integer
|
||||
* @var int
|
||||
*/
|
||||
private static $user_custom_post_type_id = null;
|
||||
|
||||
@ -64,7 +64,7 @@ class WP_Theme_JSON_Resolver {
|
||||
* Container to keep loaded i18n schema for `theme.json`.
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Renamed from $theme_json_i18n
|
||||
* @since 5.9.0 Renamed from `$theme_json_i18n`.
|
||||
* @var array
|
||||
*/
|
||||
private static $i18n_schema = null;
|
||||
@ -150,13 +150,14 @@ class WP_Theme_JSON_Resolver {
|
||||
* the theme.json takes precendence.
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Theme supports have been inlined and the argument removed.
|
||||
* @since 5.9.0 Theme supports have been inlined and the `$theme_support_data` argument removed.
|
||||
*
|
||||
* @param array $deprecated Deprecated. Not used.
|
||||
* @return WP_Theme_JSON Entity that holds theme data.
|
||||
*/
|
||||
public static function get_theme_data( $deprecated = array() ) {
|
||||
if ( ! empty( $deprecated ) ) {
|
||||
_deprecated_argument( __METHOD__, '5.9' );
|
||||
_deprecated_argument( __METHOD__, '5.9.0' );
|
||||
}
|
||||
if ( null === self::$theme ) {
|
||||
$theme_json_data = self::read_json_file( self::get_file_path_from_theme( 'theme.json' ) );
|
||||
@ -347,16 +348,16 @@ class WP_Theme_JSON_Resolver {
|
||||
* the user preference wins.
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Add user data and change the arguments.
|
||||
* @since 5.9.0 Added user data, removed the `$settings` parameter,
|
||||
* added the `$origin` parameter.
|
||||
*
|
||||
* @param string $origin Optional. To what level should we merge data.
|
||||
* Valid values are 'theme' or 'custom'.
|
||||
* Default is 'custom'.
|
||||
* Valid values are 'theme' or 'custom'. Default 'custom'.
|
||||
* @return WP_Theme_JSON
|
||||
*/
|
||||
public static function get_merged_data( $origin = 'custom' ) {
|
||||
if ( is_array( $origin ) ) {
|
||||
_deprecated_argument( __FUNCTION__, '5.9' );
|
||||
_deprecated_argument( __FUNCTION__, '5.9.0' );
|
||||
}
|
||||
|
||||
$result = new WP_Theme_JSON();
|
||||
@ -396,7 +397,7 @@ class WP_Theme_JSON_Resolver {
|
||||
* Whether the current theme has a theme.json file.
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Also check in the parent theme.
|
||||
* @since 5.9.0 Added a check in the parent theme.
|
||||
*
|
||||
* @return bool
|
||||
*/
|
||||
@ -417,7 +418,7 @@ class WP_Theme_JSON_Resolver {
|
||||
* If it isn't, returns an empty string, otherwise returns the whole file path.
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Adapt to work with child themes.
|
||||
* @since 5.9.0 Adapted to work with child themes, added the `$template` argument.
|
||||
*
|
||||
* @param string $file_name Name of the file.
|
||||
* @param bool $template Optional. Use template theme directory. Default false.
|
||||
@ -434,7 +435,8 @@ class WP_Theme_JSON_Resolver {
|
||||
* Cleans the cached data so it can be recalculated.
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Added new variables to reset.
|
||||
* @since 5.9.0 Added the `$user`, `$user_custom_post_type_id`,
|
||||
* and `$i18n_schema` variables to reset.
|
||||
*/
|
||||
public static function clean_cached_data() {
|
||||
self::$core = null;
|
||||
|
||||
@ -82,7 +82,8 @@ class WP_Theme_JSON {
|
||||
* the value that takes a preset as an argument
|
||||
* (either value_key or value_func should be present)
|
||||
* - css_vars => template string to use in generating the CSS Custom Property.
|
||||
* Example output: "--wp--preset--duotone--blue: <value>" will generate as many CSS Custom Properties as presets defined
|
||||
* Example output: "--wp--preset--duotone--blue: <value>" will generate
|
||||
* as many CSS Custom Properties as presets defined
|
||||
* substituting the $slug for the slug's value for each preset value.
|
||||
* - classes => array containing a structure with the classes to
|
||||
* generate for the presets, where for each array item
|
||||
@ -99,7 +100,8 @@ class WP_Theme_JSON {
|
||||
* by means of the remove_insecure_properties method.
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Added new presets and simplified the metadata structure.
|
||||
* @since 5.9.0 Added the `color/duotone` and `typography/fontFamily` presets,
|
||||
* simplified the metadata structure.
|
||||
* @var array
|
||||
*/
|
||||
const PRESETS_METADATA = array(
|
||||
@ -156,7 +158,10 @@ class WP_Theme_JSON {
|
||||
* path to the value in theme.json & block attributes.
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Added new properties and simplified the metadata structure.
|
||||
* @since 5.9.0 Added the `border-*`, `font-family`, `font-style`, `font-weight`,
|
||||
* `letter-spacing`, `margin-*`, `padding-*`, `--wp--style--block-gap`,
|
||||
* `text-decoration`, `text-transform`, and `filter` properties,
|
||||
* simplified the metadata structure.
|
||||
* @var array
|
||||
*/
|
||||
const PROPERTIES_METADATA = array(
|
||||
@ -212,7 +217,8 @@ class WP_Theme_JSON {
|
||||
* The top-level keys a theme.json can have.
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Renamed from ALLOWED_TOP_LEVEL_KEYS and added new values.
|
||||
* @since 5.9.0 Renamed from `ALLOWED_TOP_LEVEL_KEYS`,
|
||||
* added the `customTemplates` and `templateParts` values.
|
||||
* @var string[]
|
||||
*/
|
||||
const VALID_TOP_LEVEL_KEYS = array(
|
||||
@ -227,7 +233,9 @@ class WP_Theme_JSON {
|
||||
* The valid properties under the settings key.
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Renamed from ALLOWED_SETTINGS, gained new properties, and renamed others according to the new schema.
|
||||
* @since 5.9.0 Renamed from `ALLOWED_SETTINGS`, added new properties
|
||||
* for `border`, `color`, `spacing`, and `typography`,
|
||||
* and renamed others according to the new schema.
|
||||
* @var array
|
||||
*/
|
||||
const VALID_SETTINGS = array(
|
||||
@ -280,7 +288,8 @@ class WP_Theme_JSON {
|
||||
* The valid properties under the styles key.
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Renamed from ALLOWED_SETTINGS, gained new properties.
|
||||
* @since 5.9.0 Renamed from `ALLOWED_SETTINGS`, added new properties
|
||||
* for `border`, `filter`, `spacing`, and `typography`.
|
||||
* @var array
|
||||
*/
|
||||
const VALID_STYLES = array(
|
||||
@ -335,7 +344,7 @@ class WP_Theme_JSON {
|
||||
* The latest version of the schema in use.
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Changed value.
|
||||
* @since 5.9.0 Changed value from 1 to 2.
|
||||
* @var int
|
||||
*/
|
||||
const LATEST_SCHEMA = 2;
|
||||
@ -435,10 +444,10 @@ class WP_Theme_JSON {
|
||||
* Sanitizes the input according to the schemas.
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Has new parameters.
|
||||
* @since 5.9.0 Added the `$valid_block_names` and `$valid_element_name` parameters.
|
||||
*
|
||||
* @param array $input Structure to sanitize.
|
||||
* @param array $valid_block_names List of valid block names.
|
||||
* @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.
|
||||
* @return array The sanitized output.
|
||||
*/
|
||||
@ -518,7 +527,7 @@ class WP_Theme_JSON {
|
||||
* }
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Added duotone key with CSS selector.
|
||||
* @since 5.9.0 Added `duotone` key with CSS selector.
|
||||
*
|
||||
* @return array Block metadata.
|
||||
*/
|
||||
@ -632,19 +641,19 @@ class WP_Theme_JSON {
|
||||
* the theme.json structure this object represents.
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Changed the arguments passed to the function.
|
||||
* @since 5.9.0 Removed the `$type` parameter`, added the `$types` and `$origins` parameters.
|
||||
*
|
||||
* @param array $types Types of styles to load. Will load all by default. It accepts:
|
||||
* 'variables': only the CSS Custom Properties for presets & custom ones.
|
||||
* 'styles': only the styles section in theme.json.
|
||||
* 'presets': only the classes for the presets.
|
||||
* @param array $origins A list of origins to include. By default it includes self::VALID_ORIGINS.
|
||||
* @param array $types Types of styles to load. Will load all by default. It accepts:
|
||||
* - `variables`: only the CSS Custom Properties for presets & custom ones.
|
||||
* - `styles`: only the styles section in theme.json.
|
||||
* - `presets`: only the classes for the presets.
|
||||
* @param array $origins A list of origins to include. By default it includes `self::VALID_ORIGINS`.
|
||||
* @return string Stylesheet.
|
||||
*/
|
||||
public function get_stylesheet( $types = array( 'variables', 'styles', 'presets' ), $origins = self::VALID_ORIGINS ) {
|
||||
if ( is_string( $types ) ) {
|
||||
// Dispatch error and map old arguments to new ones.
|
||||
_deprecated_argument( __FUNCTION__, '5.9' );
|
||||
_deprecated_argument( __FUNCTION__, '5.9.0' );
|
||||
if ( 'block_styles' === $types ) {
|
||||
$types = array( 'styles', 'presets' );
|
||||
} elseif ( 'css_variables' === $types ) {
|
||||
@ -736,7 +745,8 @@ class WP_Theme_JSON {
|
||||
* }
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Renamed to get_block_classes and no longer returns preset classes.
|
||||
* @since 5.9.0 Renamed from `get_block_styles()` to `get_block_classes()`
|
||||
* and no longer returns preset classes.
|
||||
*
|
||||
* @param array $style_nodes Nodes with styles.
|
||||
* @return string The new stylesheet.
|
||||
@ -850,9 +860,9 @@ class WP_Theme_JSON {
|
||||
* }
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Added origins parameter.
|
||||
* @since 5.9.0 Added the `$origins` parameter.
|
||||
*
|
||||
* @param array $nodes Nodes with settings.
|
||||
* @param array $nodes Nodes with settings.
|
||||
* @param array $origins List of origins to process.
|
||||
* @return string The new stylesheet.
|
||||
*/
|
||||
@ -927,7 +937,7 @@ class WP_Theme_JSON {
|
||||
* for the preset classes.
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Added origins parameter.
|
||||
* @since 5.9.0 Added the `$origins` parameter.
|
||||
*
|
||||
* @param array $settings Settings to process.
|
||||
* @param string $selector Selector wrapping the classes.
|
||||
@ -979,7 +989,6 @@ class WP_Theme_JSON {
|
||||
*
|
||||
* @param string $scope Selector to scope to.
|
||||
* @param string $selector Original selector.
|
||||
*
|
||||
* @return string Scoped selector.
|
||||
*/
|
||||
private static function scope_selector( $scope, $selector ) {
|
||||
@ -1027,9 +1036,9 @@ class WP_Theme_JSON {
|
||||
*
|
||||
* @since 5.9.0
|
||||
*
|
||||
* @param array $settings Settings to process.
|
||||
* @param array $settings Settings to process.
|
||||
* @param array $preset_metadata One of the PRESETS_METADATA values.
|
||||
* @param array $origins List of origins to process.
|
||||
* @param array $origins List of origins to process.
|
||||
* @return array Array of presets where each key is a slug and each value is the preset value.
|
||||
*/
|
||||
private static function get_settings_values_by_slug( $settings, $preset_metadata, $origins ) {
|
||||
@ -1069,9 +1078,9 @@ class WP_Theme_JSON {
|
||||
*
|
||||
* @since 5.9.0
|
||||
*
|
||||
* @param array $settings Settings to process.
|
||||
* @param array $settings Settings to process.
|
||||
* @param array $preset_metadata One of the PRESETS_METADATA values.
|
||||
* @param array $origins List of origins to process.
|
||||
* @param array $origins List of origins to process.
|
||||
* @return array Array of presets where the key and value are both the slug.
|
||||
*/
|
||||
private static function get_settings_slugs( $settings, $preset_metadata, $origins = self::VALID_ORIGINS ) {
|
||||
@ -1098,8 +1107,8 @@ class WP_Theme_JSON {
|
||||
* @since 5.9.0
|
||||
*
|
||||
* @param string $input String to replace.
|
||||
* @param string $slug The slug value to use to generate the custom property.
|
||||
* @return string The CSS Custom Property. Something along the lines of --wp--preset--color--black.
|
||||
* @param string $slug The slug value to use to generate the custom property.
|
||||
* @return string The CSS Custom Property. Something along the lines of `--wp--preset--color--black`.
|
||||
*/
|
||||
private static function replace_slug_in_string( $input, $slug ) {
|
||||
return strtr( $input, array( '$slug' => $slug ) );
|
||||
@ -1116,6 +1125,7 @@ class WP_Theme_JSON {
|
||||
* )
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Added the `$origins` parameter.
|
||||
*
|
||||
* @param array $settings Settings to process.
|
||||
* @param array $origins List of origins to process.
|
||||
@ -1234,10 +1244,10 @@ class WP_Theme_JSON {
|
||||
* )
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Added theme setting and properties parameters.
|
||||
* @since 5.9.0 Added the `$settings` and `$properties` parameters.
|
||||
*
|
||||
* @param array $styles Styles to process.
|
||||
* @param array $settings Theme settings.
|
||||
* @param array $styles Styles to process.
|
||||
* @param array $settings Theme settings.
|
||||
* @param array $properties Properties metadata.
|
||||
* @return array Returns the modified $declarations.
|
||||
*/
|
||||
@ -1285,11 +1295,11 @@ class WP_Theme_JSON {
|
||||
* "--wp--preset--color--secondary".
|
||||
*
|
||||
* @since 5.8.0
|
||||
* @since 5.9.0 Consider $value that are arrays as well.
|
||||
* @since 5.9.0 Added support for values of array type, which are returned as is.
|
||||
*
|
||||
* @param array $styles Styles subtree.
|
||||
* @param array $path Which property to process.
|
||||
* @return string Style property value.
|
||||
* @return string|array Style property value.
|
||||
*/
|
||||
private static function get_property_value( $styles, $path ) {
|
||||
$value = _wp_array_get( $styles, $path, '' );
|
||||
@ -1532,9 +1542,8 @@ class WP_Theme_JSON {
|
||||
*
|
||||
* @since 5.9.0
|
||||
*
|
||||
* @param array $data A theme.json like structure to inspect.
|
||||
* @param array $node_path The path to inspect. It's 'settings' by default.
|
||||
*
|
||||
* @param array $data A theme.json like structure to inspect.
|
||||
* @param array $node_path The path to inspect. Default is 'settings'.
|
||||
* @return array An associative array containing the slugs for the given path.
|
||||
*/
|
||||
private static function get_slugs_not_to_override( $data, $node_path = array( 'settings' ) ) {
|
||||
@ -1568,11 +1577,10 @@ class WP_Theme_JSON {
|
||||
*
|
||||
* @since 5.9.0
|
||||
*
|
||||
* @param array $node The node with the presets to validate.
|
||||
* @param array $path The path to the preset type to inspect.
|
||||
* @param array $node The node with the presets to validate.
|
||||
* @param array $path The path to the preset type to inspect.
|
||||
* @param array $slugs The slugs that should not be overriden.
|
||||
*
|
||||
* @return array The new node
|
||||
* @return array The new node.
|
||||
*/
|
||||
private static function filter_slugs( $node, $path, $slugs ) {
|
||||
$slugs_for_preset = _wp_array_get( $slugs, $path, array() );
|
||||
@ -1739,9 +1747,9 @@ class WP_Theme_JSON {
|
||||
*
|
||||
* @since 5.9.0
|
||||
*
|
||||
* @param string $property_name Property name in a CSS declaration, i.e. the `color` in `color: red`.
|
||||
* @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`.
|
||||
* @return boolean
|
||||
* @return bool
|
||||
*/
|
||||
private static function is_safe_css_declaration( $property_name, $property_value ) {
|
||||
$style_to_validate = $property_name . ': ' . $property_value;
|
||||
|
||||
@ -16,7 +16,7 @@
|
||||
*
|
||||
* @global string $wp_version
|
||||
*/
|
||||
$wp_version = '5.9-beta1-52319';
|
||||
$wp_version = '5.9-beta1-52320';
|
||||
|
||||
/**
|
||||
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user