Following the introduction of a theme.json API in WordPress 5.8 and its corresponding JavaScript API, WordPress 5.9 comes with a PHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher public API An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. to read data from theme.json.
Access to settings & styles
The following new functions give access to the settings and styles keys found in a theme.json:
wp_get_global_settings( $path = array() , $context = array() );
wp_get_global_styles( $path = array(), $context = array() );
where:
$path is a list with the path to the speciffic setting, e.g.: array( 'color', 'link' ) returns the setting stored at settings.color.link. If no path is provided, all settings are returned.$context is a named array through which consumers can have a finer-grained control of the data returned:- using the
block_name key, consumers can access the settings of a particular block Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.. For example, array( 'block_name' => 'core/paragraph' ) returns only the settings of the paragraph block. - using the
origin key, consumers can decide to ignore custom data coming from the user by setting it to base. Otherwise, the data returned will be the result of merging defaults, theme, and custom data.
Some examples:
// Returns all settings
// after merging defaults, theme, and user data.
wp_get_global_settings();
// Returns the blockGap setting
// after merging defaults, theme, and user data.
wp_get_global_settings( array( 'spacing', 'blockGap' ) );
// Returns the borderRadius style for the group block
// after merging default, theme, and user data.
wp_get_global_styles(
array( 'border', 'radius' ),
array( 'block_name' => 'core/group' )
);
// Returns the background color for the block paragraph
// after merging defaults and theme data (ignoring user data).
wp_get_global_styles(
array( 'color', 'background' ),
array(
'block_name' => 'core/paragraph',
'origin' => 'base',
)
);
Access to the resulting stylesheet
Additionally, there’s a function to generate the stylesheet resulting of merging defaults, theme, and custom settings and styles:
wp_get_global_stylesheet( $types = array() );
where $types is a list of the styles to generate. Valid values are:
presets, the classes coming from the presets, e.g.: .has-black-color { ... }.styles, the classes coming from the styles section of the theme.json JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML., e.g.: .wp-block-group {...}.variables, the CSS Cascading Style Sheets. Custom Properties coming from the presets and the custom section of the theme.json, e.g.: --wp--preset--duotone--dark-grayscale.
This function also considers whether the theme has theme.json support or not, abstracting that implementation detail from the consumers. By default, all styles are returned if the theme supports theme.json; if it doesn’t, only styles for variables and presets are returned.
Note that this function only takes care of generating the stylesheet string, it doesn’t actually enqueue any styles.
Props to @oandregal for creating this dev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include a description of the change, the decision that led to this change, and a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase., it was review and published by me (@mkaz).
#5-9, #dev-notes
