638 lines
17 KiB
PHP
638 lines
17 KiB
PHP
<?php
|
|
/**
|
|
* Blocks API: WP_Block_Type class
|
|
*
|
|
* @package WordPress
|
|
* @subpackage Blocks
|
|
* @since 5.0.0
|
|
*/
|
|
|
|
/**
|
|
* Core class representing a block type.
|
|
*
|
|
* @since 5.0.0
|
|
*
|
|
* @see register_block_type()
|
|
*/
|
|
#[AllowDynamicProperties]
|
|
class WP_Block_Type {
|
|
|
|
/**
|
|
* Block API version.
|
|
*
|
|
* @since 5.6.0
|
|
* @var int
|
|
*/
|
|
public $api_version = 1;
|
|
|
|
/**
|
|
* Block type key.
|
|
*
|
|
* @since 5.0.0
|
|
* @var string
|
|
*/
|
|
public $name;
|
|
|
|
/**
|
|
* Human-readable block type label.
|
|
*
|
|
* @since 5.5.0
|
|
* @var string
|
|
*/
|
|
public $title = '';
|
|
|
|
/**
|
|
* Block type category classification, used in search interfaces
|
|
* to arrange block types by category.
|
|
*
|
|
* @since 5.5.0
|
|
* @var string|null
|
|
*/
|
|
public $category = null;
|
|
|
|
/**
|
|
* Setting parent lets a block require that it is only available
|
|
* when nested within the specified blocks.
|
|
*
|
|
* @since 5.5.0
|
|
* @var string[]|null
|
|
*/
|
|
public $parent = null;
|
|
|
|
/**
|
|
* Setting ancestor makes a block available only inside the specified
|
|
* block types at any position of the ancestor's block subtree.
|
|
*
|
|
* @since 6.0.0
|
|
* @var string[]|null
|
|
*/
|
|
public $ancestor = null;
|
|
|
|
/**
|
|
* Limits which block types can be inserted as children of this block type.
|
|
*
|
|
* @since 6.5.0
|
|
* @var string[]|null
|
|
*/
|
|
public $allowed_blocks = null;
|
|
|
|
/**
|
|
* Block type icon.
|
|
*
|
|
* @since 5.5.0
|
|
* @var string|null
|
|
*/
|
|
public $icon = null;
|
|
|
|
/**
|
|
* A detailed block type description.
|
|
*
|
|
* @since 5.5.0
|
|
* @var string
|
|
*/
|
|
public $description = '';
|
|
|
|
/**
|
|
* Additional keywords to produce block type as result
|
|
* in search interfaces.
|
|
*
|
|
* @since 5.5.0
|
|
* @var string[]
|
|
*/
|
|
public $keywords = array();
|
|
|
|
/**
|
|
* The translation textdomain.
|
|
*
|
|
* @since 5.5.0
|
|
* @var string|null
|
|
*/
|
|
public $textdomain = null;
|
|
|
|
/**
|
|
* Alternative block styles.
|
|
*
|
|
* @since 5.5.0
|
|
* @var array
|
|
*/
|
|
public $styles = array();
|
|
|
|
/**
|
|
* Block variations.
|
|
*
|
|
* @since 5.8.0
|
|
* @since 6.5.0 Only accessible through magic getter. null by default.
|
|
* @var array[]|null
|
|
*/
|
|
private $variations = null;
|
|
|
|
/**
|
|
* Block variations callback.
|
|
*
|
|
* @since 6.5.0
|
|
* @var callable|null
|
|
*/
|
|
public $variation_callback = null;
|
|
|
|
/**
|
|
* Custom CSS selectors for theme.json style generation.
|
|
*
|
|
* @since 6.3.0
|
|
* @var array
|
|
*/
|
|
public $selectors = array();
|
|
|
|
/**
|
|
* Supported features.
|
|
*
|
|
* @since 5.5.0
|
|
* @var array|null
|
|
*/
|
|
public $supports = null;
|
|
|
|
/**
|
|
* Structured data for the block preview.
|
|
*
|
|
* @since 5.5.0
|
|
* @var array|null
|
|
*/
|
|
public $example = null;
|
|
|
|
/**
|
|
* Block type render callback.
|
|
*
|
|
* @since 5.0.0
|
|
* @var callable
|
|
*/
|
|
public $render_callback = null;
|
|
|
|
/**
|
|
* Block type attributes property schemas.
|
|
*
|
|
* @since 5.0.0
|
|
* @var array|null
|
|
*/
|
|
public $attributes = null;
|
|
|
|
/**
|
|
* Context values inherited by blocks of this type.
|
|
*
|
|
* @since 5.5.0
|
|
* @var string[]
|
|
*/
|
|
private $uses_context = array();
|
|
|
|
/**
|
|
* Context provided by blocks of this type.
|
|
*
|
|
* @since 5.5.0
|
|
* @var string[]|null
|
|
*/
|
|
public $provides_context = null;
|
|
|
|
/**
|
|
* Block hooks for this block type.
|
|
*
|
|
* A block hook is specified by a block type and a relative position.
|
|
* The hooked block will be automatically inserted in the given position
|
|
* next to the "anchor" block whenever the latter is encountered.
|
|
*
|
|
* @since 6.4.0
|
|
* @var string[]
|
|
*/
|
|
public $block_hooks = array();
|
|
|
|
/**
|
|
* Block type editor only script handles.
|
|
*
|
|
* @since 6.1.0
|
|
* @var string[]
|
|
*/
|
|
public $editor_script_handles = array();
|
|
|
|
/**
|
|
* Block type front end and editor script handles.
|
|
*
|
|
* @since 6.1.0
|
|
* @var string[]
|
|
*/
|
|
public $script_handles = array();
|
|
|
|
/**
|
|
* Block type front end only script handles.
|
|
*
|
|
* @since 6.1.0
|
|
* @var string[]
|
|
*/
|
|
public $view_script_handles = array();
|
|
|
|
/**
|
|
* Block type front end only script module IDs.
|
|
*
|
|
* @since 6.5.0
|
|
* @var string[]
|
|
*/
|
|
public $view_script_module_ids = array();
|
|
|
|
/**
|
|
* Block type editor only style handles.
|
|
*
|
|
* @since 6.1.0
|
|
* @var string[]
|
|
*/
|
|
public $editor_style_handles = array();
|
|
|
|
/**
|
|
* Block type front end and editor style handles.
|
|
*
|
|
* @since 6.1.0
|
|
* @var string[]
|
|
*/
|
|
public $style_handles = array();
|
|
|
|
/**
|
|
* Block type front end only style handles.
|
|
*
|
|
* @since 6.5.0
|
|
* @var string[]
|
|
*/
|
|
public $view_style_handles = array();
|
|
|
|
/**
|
|
* Deprecated block type properties for script and style handles.
|
|
*
|
|
* @since 6.1.0
|
|
* @var string[]
|
|
*/
|
|
private $deprecated_properties = array(
|
|
'editor_script',
|
|
'script',
|
|
'view_script',
|
|
'editor_style',
|
|
'style',
|
|
);
|
|
|
|
/**
|
|
* Attributes supported by every block.
|
|
*
|
|
* @since 6.0.0 Added `lock`.
|
|
* @since 6.5.0 Added `metadata`.
|
|
* @var array
|
|
*/
|
|
const GLOBAL_ATTRIBUTES = array(
|
|
'lock' => array( 'type' => 'object' ),
|
|
'metadata' => array( 'type' => 'object' ),
|
|
);
|
|
|
|
/**
|
|
* Constructor.
|
|
*
|
|
* Will populate object properties from the provided arguments.
|
|
*
|
|
* @since 5.0.0
|
|
* @since 5.5.0 Added the `title`, `category`, `parent`, `icon`, `description`,
|
|
* `keywords`, `textdomain`, `styles`, `supports`, `example`,
|
|
* `uses_context`, and `provides_context` properties.
|
|
* @since 5.6.0 Added the `api_version` property.
|
|
* @since 5.8.0 Added the `variations` property.
|
|
* @since 5.9.0 Added the `view_script` property.
|
|
* @since 6.0.0 Added the `ancestor` property.
|
|
* @since 6.1.0 Added the `editor_script_handles`, `script_handles`, `view_script_handles`,
|
|
* `editor_style_handles`, and `style_handles` properties.
|
|
* Deprecated the `editor_script`, `script`, `view_script`, `editor_style`, and `style` properties.
|
|
* @since 6.3.0 Added the `selectors` property.
|
|
* @since 6.4.0 Added the `block_hooks` property.
|
|
* @since 6.5.0 Added the `allowed_blocks`, `variation_callback`, and `view_style_handles` properties.
|
|
*
|
|
* @see register_block_type()
|
|
*
|
|
* @param string $block_type Block type name including namespace.
|
|
* @param array|string $args {
|
|
* Optional. Array or string of arguments for registering a block type. Any arguments may be defined,
|
|
* however the ones described below are supported by default. Default empty array.
|
|
*
|
|
* @type string $api_version Block API version.
|
|
* @type string $title Human-readable block type label.
|
|
* @type string|null $category Block type category classification, used in
|
|
* search interfaces to arrange block types by category.
|
|
* @type string[]|null $parent Setting parent lets a block require that it is only
|
|
* available when nested within the specified blocks.
|
|
* @type string[]|null $ancestor Setting ancestor makes a block available only inside the specified
|
|
* block types at any position of the ancestor's block subtree.
|
|
* @type string[]|null $allowed_blocks Limits which block types can be inserted as children of this block type.
|
|
* @type string|null $icon Block type icon.
|
|
* @type string $description A detailed block type description.
|
|
* @type string[] $keywords Additional keywords to produce block type as
|
|
* result in search interfaces.
|
|
* @type string|null $textdomain The translation textdomain.
|
|
* @type array[] $styles Alternative block styles.
|
|
* @type array[] $variations Block variations.
|
|
* @type array $selectors Custom CSS selectors for theme.json style generation.
|
|
* @type array|null $supports Supported features.
|
|
* @type array|null $example Structured data for the block preview.
|
|
* @type callable|null $render_callback Block type render callback.
|
|
* @type callable|null $variation_callback Block type variations callback.
|
|
* @type array|null $attributes Block type attributes property schemas.
|
|
* @type string[] $uses_context Context values inherited by blocks of this type.
|
|
* @type string[]|null $provides_context Context provided by blocks of this type.
|
|
* @type string[] $block_hooks Block hooks.
|
|
* @type string[] $editor_script_handles Block type editor only script handles.
|
|
* @type string[] $script_handles Block type front end and editor script handles.
|
|
* @type string[] $view_script_handles Block type front end only script handles.
|
|
* @type string[] $editor_style_handles Block type editor only style handles.
|
|
* @type string[] $style_handles Block type front end and editor style handles.
|
|
* @type string[] $view_style_handles Block type front end only style handles.
|
|
* }
|
|
*/
|
|
public function __construct( $block_type, $args = array() ) {
|
|
$this->name = $block_type;
|
|
|
|
$this->set_props( $args );
|
|
}
|
|
|
|
/**
|
|
* Proxies getting values for deprecated properties for script and style handles for backward compatibility.
|
|
* Gets the value for the corresponding new property if the first item in the array provided.
|
|
*
|
|
* @since 6.1.0
|
|
*
|
|
* @param string $name Deprecated property name.
|
|
*
|
|
* @return string|string[]|null|void The value read from the new property if the first item in the array provided,
|
|
* null when value not found, or void when unknown property name provided.
|
|
*/
|
|
public function __get( $name ) {
|
|
if ( 'variations' === $name ) {
|
|
return $this->get_variations();
|
|
}
|
|
|
|
if ( 'uses_context' === $name ) {
|
|
return $this->get_uses_context();
|
|
}
|
|
|
|
if ( ! in_array( $name, $this->deprecated_properties, true ) ) {
|
|
return;
|
|
}
|
|
|
|
$new_name = $name . '_handles';
|
|
|
|
if ( ! property_exists( $this, $new_name ) || ! is_array( $this->{$new_name} ) ) {
|
|
return null;
|
|
}
|
|
|
|
if ( count( $this->{$new_name} ) > 1 ) {
|
|
return $this->{$new_name};
|
|
}
|
|
return isset( $this->{$new_name}[0] ) ? $this->{$new_name}[0] : null;
|
|
}
|
|
|
|
/**
|
|
* Proxies checking for deprecated properties for script and style handles for backward compatibility.
|
|
* Checks whether the corresponding new property has the first item in the array provided.
|
|
*
|
|
* @since 6.1.0
|
|
*
|
|
* @param string $name Deprecated property name.
|
|
*
|
|
* @return bool Returns true when for the new property the first item in the array exists,
|
|
* or false otherwise.
|
|
*/
|
|
public function __isset( $name ) {
|
|
if ( in_array( $name, array( 'variations', 'uses_context' ), true ) ) {
|
|
return true;
|
|
}
|
|
|
|
if ( ! in_array( $name, $this->deprecated_properties, true ) ) {
|
|
return false;
|
|
}
|
|
|
|
$new_name = $name . '_handles';
|
|
return isset( $this->{$new_name}[0] );
|
|
}
|
|
|
|
/**
|
|
* Proxies setting values for deprecated properties for script and style handles for backward compatibility.
|
|
* Sets the value for the corresponding new property as the first item in the array.
|
|
* It also allows setting custom properties for backward compatibility.
|
|
*
|
|
* @since 6.1.0
|
|
*
|
|
* @param string $name Property name.
|
|
* @param mixed $value Property value.
|
|
*/
|
|
public function __set( $name, $value ) {
|
|
if ( ! in_array( $name, $this->deprecated_properties, true ) ) {
|
|
$this->{$name} = $value;
|
|
return;
|
|
}
|
|
|
|
$new_name = $name . '_handles';
|
|
|
|
if ( is_array( $value ) ) {
|
|
$filtered = array_filter( $value, 'is_string' );
|
|
|
|
if ( count( $filtered ) !== count( $value ) ) {
|
|
_doing_it_wrong(
|
|
__METHOD__,
|
|
sprintf(
|
|
/* translators: %s: The '$value' argument. */
|
|
__( 'The %s argument must be a string or a string array.' ),
|
|
'<code>$value</code>'
|
|
),
|
|
'6.1.0'
|
|
);
|
|
}
|
|
|
|
$this->{$new_name} = array_values( $filtered );
|
|
return;
|
|
}
|
|
|
|
if ( ! is_string( $value ) ) {
|
|
return;
|
|
}
|
|
|
|
$this->{$new_name} = array( $value );
|
|
}
|
|
|
|
/**
|
|
* Renders the block type output for given attributes.
|
|
*
|
|
* @since 5.0.0
|
|
*
|
|
* @param array $attributes Optional. Block attributes. Default empty array.
|
|
* @param string $content Optional. Block content. Default empty string.
|
|
* @return string Rendered block type output.
|
|
*/
|
|
public function render( $attributes = array(), $content = '' ) {
|
|
if ( ! $this->is_dynamic() ) {
|
|
return '';
|
|
}
|
|
|
|
$attributes = $this->prepare_attributes_for_render( $attributes );
|
|
|
|
return (string) call_user_func( $this->render_callback, $attributes, $content );
|
|
}
|
|
|
|
/**
|
|
* Returns true if the block type is dynamic, or false otherwise. A dynamic
|
|
* block is one which defers its rendering to occur on-demand at runtime.
|
|
*
|
|
* @since 5.0.0
|
|
*
|
|
* @return bool Whether block type is dynamic.
|
|
*/
|
|
public function is_dynamic() {
|
|
return is_callable( $this->render_callback );
|
|
}
|
|
|
|
/**
|
|
* Validates attributes against the current block schema, populating
|
|
* defaulted and missing values.
|
|
*
|
|
* @since 5.0.0
|
|
*
|
|
* @param array $attributes Original block attributes.
|
|
* @return array Prepared block attributes.
|
|
*/
|
|
public function prepare_attributes_for_render( $attributes ) {
|
|
// If there are no attribute definitions for the block type, skip
|
|
// processing and return verbatim.
|
|
if ( ! isset( $this->attributes ) ) {
|
|
return $attributes;
|
|
}
|
|
|
|
foreach ( $attributes as $attribute_name => $value ) {
|
|
// If the attribute is not defined by the block type, it cannot be
|
|
// validated.
|
|
if ( ! isset( $this->attributes[ $attribute_name ] ) ) {
|
|
continue;
|
|
}
|
|
|
|
$schema = $this->attributes[ $attribute_name ];
|
|
|
|
// Validate value by JSON schema. An invalid value should revert to
|
|
// its default, if one exists. This occurs by virtue of the missing
|
|
// attributes loop immediately following. If there is not a default
|
|
// assigned, the attribute value should remain unset.
|
|
$is_valid = rest_validate_value_from_schema( $value, $schema, $attribute_name );
|
|
if ( is_wp_error( $is_valid ) ) {
|
|
unset( $attributes[ $attribute_name ] );
|
|
}
|
|
}
|
|
|
|
// Populate values of any missing attributes for which the block type
|
|
// defines a default.
|
|
$missing_schema_attributes = array_diff_key( $this->attributes, $attributes );
|
|
foreach ( $missing_schema_attributes as $attribute_name => $schema ) {
|
|
if ( isset( $schema['default'] ) ) {
|
|
$attributes[ $attribute_name ] = $schema['default'];
|
|
}
|
|
}
|
|
|
|
return $attributes;
|
|
}
|
|
|
|
/**
|
|
* Sets block type properties.
|
|
*
|
|
* @since 5.0.0
|
|
*
|
|
* @param array|string $args Array or string of arguments for registering a block type.
|
|
* See WP_Block_Type::__construct() for information on accepted arguments.
|
|
*/
|
|
public function set_props( $args ) {
|
|
$args = wp_parse_args(
|
|
$args,
|
|
array(
|
|
'render_callback' => null,
|
|
)
|
|
);
|
|
|
|
$args['name'] = $this->name;
|
|
|
|
// Setup attributes if needed.
|
|
if ( ! isset( $args['attributes'] ) || ! is_array( $args['attributes'] ) ) {
|
|
$args['attributes'] = array();
|
|
}
|
|
|
|
// Register core attributes.
|
|
foreach ( static::GLOBAL_ATTRIBUTES as $attr_key => $attr_schema ) {
|
|
if ( ! array_key_exists( $attr_key, $args['attributes'] ) ) {
|
|
$args['attributes'][ $attr_key ] = $attr_schema;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Filters the arguments for registering a block type.
|
|
*
|
|
* @since 5.5.0
|
|
*
|
|
* @param array $args Array of arguments for registering a block type.
|
|
* @param string $block_type Block type name including namespace.
|
|
*/
|
|
$args = apply_filters( 'register_block_type_args', $args, $this->name );
|
|
|
|
foreach ( $args as $property_name => $property_value ) {
|
|
$this->$property_name = $property_value;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Get all available block attributes including possible layout attribute from Columns block.
|
|
*
|
|
* @since 5.0.0
|
|
*
|
|
* @return array Array of attributes.
|
|
*/
|
|
public function get_attributes() {
|
|
return is_array( $this->attributes ) ?
|
|
$this->attributes :
|
|
array();
|
|
}
|
|
|
|
/**
|
|
* Get block variations.
|
|
*
|
|
* @since 6.5.0
|
|
*
|
|
* @return array[]
|
|
*/
|
|
public function get_variations() {
|
|
if ( ! isset( $this->variations ) ) {
|
|
$this->variations = array();
|
|
if ( is_callable( $this->variation_callback ) ) {
|
|
$this->variations = call_user_func( $this->variation_callback );
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Filters the registered variations for a block type.
|
|
*
|
|
* @since 6.5.0
|
|
*
|
|
* @param array $variations Array of registered variations for a block type.
|
|
* @param WP_Block_Type $block_type The full block type object.
|
|
*/
|
|
return apply_filters( 'get_block_type_variations', $this->variations, $this );
|
|
}
|
|
|
|
/**
|
|
* Get block uses context.
|
|
*
|
|
* @since 6.5.0
|
|
*
|
|
* @return string[]
|
|
*/
|
|
public function get_uses_context() {
|
|
/**
|
|
* Filters the registered uses context for a block type.
|
|
*
|
|
* @since 6.5.0
|
|
*
|
|
* @param string[] $uses_context Array of registered uses context for a block type.
|
|
* @param WP_Block_Type $block_type The full block type object.
|
|
*/
|
|
return apply_filters( 'get_block_type_uses_context', $this->uses_context, $this );
|
|
}
|
|
}
|