[Summary view] [Print] [Text view]

   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       *
 197       * @see register_block_type()
 198       *
 199       * @param string       $block_type Block type name including namespace.
 200       * @param array|string $args       {
 201       *     Optional. Array or string of arguments for registering a block type. Any arguments may be defined,
 202       *     however the ones described below are supported by default. Default empty array.
 203       *
 204       *
 205       *     @type string        $title            Human-readable block type label.
 206       *     @type string|null   $category         Block type category classification, used in
 207       *                                           search interfaces to arrange block types by category.
 208       *     @type array|null    $parent           Setting parent lets a block require that it is only
 209       *                                           available when nested within the specified blocks.
 210       *     @type string|null   $icon             Block type icon.
 211       *     @type string        $description      A detailed block type description.
 212       *     @type array         $keywords         Additional keywords to produce block type as
 213       *                                           result in search interfaces.
 214       *     @type string|null   $textdomain       The translation textdomain.
 215       *     @type array         $styles           Alternative block styles.
 216       *     @type array|null    $supports         Supported features.
 217       *     @type array|null    $example          Structured data for the block preview.
 218       *     @type callable|null $render_callback  Block type render callback.
 219       *     @type array|null    $attributes       Block type attributes property schemas.
 220       *     @type array         $uses_context     Context values inherited by blocks of this type.
 221       *     @type array|null    $provides_context Context provided by blocks of this type.
 222       *     @type string|null   $editor_script    Block type editor script handle.
 223       *     @type string|null   $script           Block type front end script handle.
 224       *     @type string|null   $editor_style     Block type editor style handle.
 225       *     @type string|null   $style            Block type front end style handle.
 226       * }
 227       */
 228  	public function __construct( $block_type, $args = array() ) {
 229          $this->name = $block_type;
 230  
 231          $this->set_props( $args );
 232      }
 233  
 234      /**
 235       * Renders the block type output for given attributes.
 236       *
 237       * @since 5.0.0
 238       *
 239       * @param array  $attributes Optional. Block attributes. Default empty array.
 240       * @param string $content    Optional. Block content. Default empty string.
 241       * @return string Rendered block type output.
 242       */
 243  	public function render( $attributes = array(), $content = '' ) {
 244          if ( ! $this->is_dynamic() ) {
 245              return '';
 246          }
 247  
 248          $attributes = $this->prepare_attributes_for_render( $attributes );
 249  
 250          return (string) call_user_func( $this->render_callback, $attributes, $content );
 251      }
 252  
 253      /**
 254       * Returns true if the block type is dynamic, or false otherwise. A dynamic
 255       * block is one which defers its rendering to occur on-demand at runtime.
 256       *
 257       * @since 5.0.0
 258       *
 259       * @return bool Whether block type is dynamic.
 260       */
 261  	public function is_dynamic() {
 262          return is_callable( $this->render_callback );
 263      }
 264  
 265      /**
 266       * Validates attributes against the current block schema, populating
 267       * defaulted and missing values.
 268       *
 269       * @since 5.0.0
 270       *
 271       * @param array $attributes Original block attributes.
 272       * @return array Prepared block attributes.
 273       */
 274  	public function prepare_attributes_for_render( $attributes ) {
 275          // If there are no attribute definitions for the block type, skip
 276          // processing and return verbatim.
 277          if ( ! isset( $this->attributes ) ) {
 278              return $attributes;
 279          }
 280  
 281          foreach ( $attributes as $attribute_name => $value ) {
 282              // If the attribute is not defined by the block type, it cannot be
 283              // validated.
 284              if ( ! isset( $this->attributes[ $attribute_name ] ) ) {
 285                  continue;
 286              }
 287  
 288              $schema = $this->attributes[ $attribute_name ];
 289  
 290              // Validate value by JSON schema. An invalid value should revert to
 291              // its default, if one exists. This occurs by virtue of the missing
 292              // attributes loop immediately following. If there is not a default
 293              // assigned, the attribute value should remain unset.
 294              $is_valid = rest_validate_value_from_schema( $value, $schema, $attribute_name );
 295              if ( is_wp_error( $is_valid ) ) {
 296                  unset( $attributes[ $attribute_name ] );
 297              }
 298          }
 299  
 300          // Populate values of any missing attributes for which the block type
 301          // defines a default.
 302          $missing_schema_attributes = array_diff_key( $this->attributes, $attributes );
 303          foreach ( $missing_schema_attributes as $attribute_name => $schema ) {
 304              if ( isset( $schema['default'] ) ) {
 305                  $attributes[ $attribute_name ] = $schema['default'];
 306              }
 307          }
 308  
 309          return $attributes;
 310      }
 311  
 312      /**
 313       * Sets block type properties.
 314       *
 315       * @since 5.0.0
 316       *
 317       * @param array|string $args Array or string of arguments for registering a block type.
 318       *                           See WP_Block_Type::__construct() for information on accepted arguments.
 319       */
 320  	public function set_props( $args ) {
 321          $args = wp_parse_args(
 322              $args,
 323              array(
 324                  'render_callback' => null,
 325              )
 326          );
 327  
 328          $args['name'] = $this->name;
 329  
 330          /**
 331           * Filters the arguments for registering a block type.
 332           *
 333           * @since 5.5.0
 334           *
 335           * @param array  $args       Array of arguments for registering a block type.
 336           * @param string $block_type Block type name including namespace.
 337           */
 338          $args = apply_filters( 'register_block_type_args', $args, $this->name );
 339  
 340          foreach ( $args as $property_name => $property_value ) {
 341              $this->$property_name = $property_value;
 342          }
 343      }
 344  
 345      /**
 346       * Get all available block attributes including possible layout attribute from Columns block.
 347       *
 348       * @since 5.0.0
 349       *
 350       * @return array Array of attributes.
 351       */
 352  	public function get_attributes() {
 353          return is_array( $this->attributes ) ?
 354              $this->attributes :
 355              array();
 356      }
 357  }