Themes use the add_theme_support
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 declare support for a particular theme feature. For instance, add_theme_support( 'align-wide' )
declares that a theme supports the wide alignment feature.
When the Themes REST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. controller was introduced in WordPress 5.0 , a minimal set of theme features were exposed (see #45016). In WordPress 5.4, this was expanded to all WordPress Core Core is the set of software required to run WordPress. The Core Development Team builds WordPress. theme features (see #49037). Support for custom theme features was not included because there was not a safe way to validate their shape and ensure the associated data was not private.
In [48171] the new register_theme_feature()
API was introduced to declare the format of a theme feature. This does not indicate that the current theme supports that feature, merely that it is available to be supported.
Features that are registered with show_in_rest
enabled will have the add_theme_support()
value exposed in the REST API themes endpoint. This allows for plugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party developers to access the theme support values over the REST API. Currently, the REST API is the only consumer of the registered theme features.
WordPress Core registers the list of built-in theme features in the create_initial_theme_features()
function.
The API
The register_theme_feature()
function takes two arguments. The first, $feature
, is the name uniquely identifying the feature. The second, $args
, is a list of arguments detailing the feature. If the feature is successfully registered, the function will return true
. Otherwise, a WP_Error
instance is returned.
Type
The type
argument specifies the 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. Schema type of the value that should be passed to add_theme_support()
. The acceptable values are string
, boolean
, integer
, number
, object
and array
.
The object
type refers to a PHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher associative array (an array of key, value pairs). The array
type refers to a PHP numerical array, in other words a list of values without specific keys.
Variadic
The variadic
argument specifies whether the feature utilizes the variadic argument support of add_theme_support()
, or if the feature is entirely described by the first argument. Theme features in Core aren’t variadic.
add_theme_support( 'html5', array(
'search-form',
'comment-form',
) );
If the html5
feature was variadic, add_theme_support()
would be used like this.
add_theme_support( 'html5', 'search-form', 'comment-form' );
Description
The description
argument is meant to be a short description of the feature intended for developers. The REST API surfaces this description in the schema for the Themes API.
Show in REST
By default, theme features are not included in the REST API. To opt-in to this behavior, the show_in_rest
flag can be set to true
or an array
with additional arguments to describe the feature.
Schema
The show_in_rest.schema
argument specifies the JSON schema describing the format of the feature. If the feature type
is an object
or array
specifying a schema is mandatory.
For an array
type, the schema should contain an items
definition that describes the format of each entry in the array. For example, the html5
theme feature is described with the following schema.
array(
'items' => array(
'type' => 'string',
'enum' => array(
'search-form',
'comment-form',
'comment-list',
'gallery',
'caption',
'script',
'style',
),
),
)
For an object
type, the schema should define each of the properties
of the object that should appear in the REST API. This isn’t always every field that can be registered. For instance, the custom-header
omits the various callback flags because they aren’t safe to include in the REST API.
array(
'properties' => array(
'default-image' => array(
'type' => 'string',
'format' => 'uri',
),
'random-default' => array(
'type' => 'boolean',
),
'width' => array(
'type' => 'integer',
),
'height' => array(
'type' => 'integer',
),
'flex-height' => array(
'type' => 'boolean',
),
'flex-width' => array(
'type' => 'boolean',
),
'default-text-color' => array(
'type' => 'string',
),
'header-text' => array(
'type' => 'boolean',
),
'uploads' => array(
'type' => 'boolean',
),
'video' => array(
'type' => 'boolean',
),
),
)
Default
The show_in_rest.schema.default
argument can be used to specify an alternate default value to be shown in the REST API if the current theme does not support the registered feature. By default, the feature will have a value of false
. The post-formats
feature declares a default
of [ 'standard' ]
.
Name
The show_in_rest.name
argument can be used to specify an alternate property name for the feature when it is displayed in the REST API. For example, the post-formats
feature declares a name
of formats
.
Prepare callback
The show_in_rest.prepare_callback
argument can be used to customize how the feature is formatted in the REST API. By default, the REST API sanitizes the raw value from get_theme_support
according to the specified schema.
The post-formats
feature uses a custom prepare_callback
to ensure that standard
is always included as a supported post format.
function ( $formats ) {
$formats = is_array( $formats ) ? array_values( $formats[0] ) : array();
$formats = array_merge( array( 'standard' ), $formats );
return $formats;
}
The prepare_callback
function receives the following parameters.
- The raw feature value from
add_theme_support()
. - The args describing the feature from
register_theme_feature()
. - The feature name.
- The
WP_REST_Request
object being responded to by the REST API.
Example
This example registers the editor-color-palette
theme feature. Theme features should be registered on the setup_theme
action.
function myplugin_setup_theme() {
register_theme_feature( 'editor-color-palette', array(
'type' => 'array',
'description' => __( 'Custom color palette if defined by the theme.' ),
'show_in_rest' => array(
'schema' => array(
'items' => array(
'type' => 'object',
'properties' => array(
'name' => array(
'type' => 'string',
),
'slug' => array(
'type' => 'string',
),
'color' => array(
'type' => 'string',
),
),
),
),
),
) );
}
add_action( 'setup_theme', 'myplugin_setup_theme' );
For more information, refer to the related ticket Created for both bug reports and feature development on the bug tracker. on Trac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. (#49406).
Props @desrosj and @justinahinon for reviewing.
#5-5, #dev-notes, #rest-api, #themes