class-wp-block-type.php (9163B)
1 <?php 2 /** 3 * Blocks API: WP_Block_Type class 4 * 5 * @package WordPress 6 * @subpackage Blocks 7 * @since 5.0.0 8 */ 9 10 /** 11 * Core class representing a block type. 12 * 13 * @since 5.0.0 14 * 15 * @see register_block_type() 16 */ 17 class WP_Block_Type { 18 19 /** 20 * Block API version. 21 * 22 * @since 5.6.0 23 * @var int 24 */ 25 public $api_version = 1; 26 27 /** 28 * Block type key. 29 * 30 * @since 5.0.0 31 * @var string 32 */ 33 public $name; 34 35 /** 36 * Human-readable block type label. 37 * 38 * @since 5.5.0 39 * @var string 40 */ 41 public $title = ''; 42 43 /** 44 * Block type category classification, used in search interfaces 45 * to arrange block types by category. 46 * 47 * @since 5.5.0 48 * @var string|null 49 */ 50 public $category = null; 51 52 /** 53 * Setting parent lets a block require that it is only available 54 * when nested within the specified blocks. 55 * 56 * @since 5.5.0 57 * @var array|null 58 */ 59 public $parent = null; 60 61 /** 62 * Block type icon. 63 * 64 * @since 5.5.0 65 * @var string|null 66 */ 67 public $icon = null; 68 69 /** 70 * A detailed block type description. 71 * 72 * @since 5.5.0 73 * @var string 74 */ 75 public $description = ''; 76 77 /** 78 * Additional keywords to produce block type as result 79 * in search interfaces. 80 * 81 * @since 5.5.0 82 * @var array 83 */ 84 public $keywords = array(); 85 86 /** 87 * The translation textdomain. 88 * 89 * @since 5.5.0 90 * @var string|null 91 */ 92 public $textdomain = null; 93 94 /** 95 * Alternative block styles. 96 * 97 * @since 5.5.0 98 * @var array 99 */ 100 public $styles = array(); 101 102 /** 103 * Block variations. 104 * 105 * @since 5.8.0 106 * @var array 107 */ 108 public $variations = array(); 109 110 /** 111 * Supported features. 112 * 113 * @since 5.5.0 114 * @var array|null 115 */ 116 public $supports = null; 117 118 /** 119 * Structured data for the block preview. 120 * 121 * @since 5.5.0 122 * @var array|null 123 */ 124 public $example = null; 125 126 /** 127 * Block type render callback. 128 * 129 * @since 5.0.0 130 * @var callable 131 */ 132 public $render_callback = null; 133 134 /** 135 * Block type attributes property schemas. 136 * 137 * @since 5.0.0 138 * @var array|null 139 */ 140 public $attributes = null; 141 142 /** 143 * Context values inherited by blocks of this type. 144 * 145 * @since 5.5.0 146 * @var array 147 */ 148 public $uses_context = array(); 149 150 /** 151 * Context provided by blocks of this type. 152 * 153 * @since 5.5.0 154 * @var array|null 155 */ 156 public $provides_context = null; 157 158 /** 159 * Block type editor script handle. 160 * 161 * @since 5.0.0 162 * @var string|null 163 */ 164 public $editor_script = null; 165 166 /** 167 * Block type front end script handle. 168 * 169 * @since 5.0.0 170 * @var string|null 171 */ 172 public $script = null; 173 174 /** 175 * Block type editor style handle. 176 * 177 * @since 5.0.0 178 * @var string|null 179 */ 180 public $editor_style = null; 181 182 /** 183 * Block type front end style handle. 184 * 185 * @since 5.0.0 186 * @var string|null 187 */ 188 public $style = null; 189 190 /** 191 * Constructor. 192 * 193 * Will populate object properties from the provided arguments. 194 * 195 * @since 5.0.0 196 * @since 5.5.0 Added the `title`, `category`, `parent`, `icon`, `description`, 197 * `keywords`, `textdomain`, `styles`, `supports`, `example`, 198 * `uses_context`, and `provides_context` properties. 199 * @since 5.6.0 Added the `api_version` property. 200 * @since 5.8.0 Added the `variations` property. 201 * 202 * @see register_block_type() 203 * 204 * @param string $block_type Block type name including namespace. 205 * @param array|string $args { 206 * Optional. Array or string of arguments for registering a block type. Any arguments may be defined, 207 * however the ones described below are supported by default. Default empty array. 208 * 209 * @type string $api_version Block API version. 210 * @type string $title Human-readable block type label. 211 * @type string|null $category Block type category classification, used in 212 * search interfaces to arrange block types by category. 213 * @type array|null $parent Setting parent lets a block require that it is only 214 * available when nested within the specified blocks. 215 * @type string|null $icon Block type icon. 216 * @type string $description A detailed block type description. 217 * @type array $keywords Additional keywords to produce block type as 218 * result in search interfaces. 219 * @type string|null $textdomain The translation textdomain. 220 * @type array $styles Alternative block styles. 221 * @type array $variations Block variations. 222 * @type array|null $supports Supported features. 223 * @type array|null $example Structured data for the block preview. 224 * @type callable|null $render_callback Block type render callback. 225 * @type array|null $attributes Block type attributes property schemas. 226 * @type array $uses_context Context values inherited by blocks of this type. 227 * @type array|null $provides_context Context provided by blocks of this type. 228 * @type string|null $editor_script Block type editor script handle. 229 * @type string|null $script Block type front end script handle. 230 * @type string|null $editor_style Block type editor style handle. 231 * @type string|null $style Block type front end style handle. 232 * } 233 */ 234 public function __construct( $block_type, $args = array() ) { 235 $this->name = $block_type; 236 237 $this->set_props( $args ); 238 } 239 240 /** 241 * Renders the block type output for given attributes. 242 * 243 * @since 5.0.0 244 * 245 * @param array $attributes Optional. Block attributes. Default empty array. 246 * @param string $content Optional. Block content. Default empty string. 247 * @return string Rendered block type output. 248 */ 249 public function render( $attributes = array(), $content = '' ) { 250 if ( ! $this->is_dynamic() ) { 251 return ''; 252 } 253 254 $attributes = $this->prepare_attributes_for_render( $attributes ); 255 256 return (string) call_user_func( $this->render_callback, $attributes, $content ); 257 } 258 259 /** 260 * Returns true if the block type is dynamic, or false otherwise. A dynamic 261 * block is one which defers its rendering to occur on-demand at runtime. 262 * 263 * @since 5.0.0 264 * 265 * @return bool Whether block type is dynamic. 266 */ 267 public function is_dynamic() { 268 return is_callable( $this->render_callback ); 269 } 270 271 /** 272 * Validates attributes against the current block schema, populating 273 * defaulted and missing values. 274 * 275 * @since 5.0.0 276 * 277 * @param array $attributes Original block attributes. 278 * @return array Prepared block attributes. 279 */ 280 public function prepare_attributes_for_render( $attributes ) { 281 // If there are no attribute definitions for the block type, skip 282 // processing and return verbatim. 283 if ( ! isset( $this->attributes ) ) { 284 return $attributes; 285 } 286 287 foreach ( $attributes as $attribute_name => $value ) { 288 // If the attribute is not defined by the block type, it cannot be 289 // validated. 290 if ( ! isset( $this->attributes[ $attribute_name ] ) ) { 291 continue; 292 } 293 294 $schema = $this->attributes[ $attribute_name ]; 295 296 // Validate value by JSON schema. An invalid value should revert to 297 // its default, if one exists. This occurs by virtue of the missing 298 // attributes loop immediately following. If there is not a default 299 // assigned, the attribute value should remain unset. 300 $is_valid = rest_validate_value_from_schema( $value, $schema, $attribute_name ); 301 if ( is_wp_error( $is_valid ) ) { 302 unset( $attributes[ $attribute_name ] ); 303 } 304 } 305 306 // Populate values of any missing attributes for which the block type 307 // defines a default. 308 $missing_schema_attributes = array_diff_key( $this->attributes, $attributes ); 309 foreach ( $missing_schema_attributes as $attribute_name => $schema ) { 310 if ( isset( $schema['default'] ) ) { 311 $attributes[ $attribute_name ] = $schema['default']; 312 } 313 } 314 315 return $attributes; 316 } 317 318 /** 319 * Sets block type properties. 320 * 321 * @since 5.0.0 322 * 323 * @param array|string $args Array or string of arguments for registering a block type. 324 * See WP_Block_Type::__construct() for information on accepted arguments. 325 */ 326 public function set_props( $args ) { 327 $args = wp_parse_args( 328 $args, 329 array( 330 'render_callback' => null, 331 ) 332 ); 333 334 $args['name'] = $this->name; 335 336 /** 337 * Filters the arguments for registering a block type. 338 * 339 * @since 5.5.0 340 * 341 * @param array $args Array of arguments for registering a block type. 342 * @param string $block_type Block type name including namespace. 343 */ 344 $args = apply_filters( 'register_block_type_args', $args, $this->name ); 345 346 foreach ( $args as $property_name => $property_value ) { 347 $this->$property_name = $property_value; 348 } 349 } 350 351 /** 352 * Get all available block attributes including possible layout attribute from Columns block. 353 * 354 * @since 5.0.0 355 * 356 * @return array Array of attributes. 357 */ 358 public function get_attributes() { 359 return is_array( $this->attributes ) ? 360 $this->attributes : 361 array(); 362 } 363 }