[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       * Block type key.
  20       *
  21       * @since 5.0.0
  22       * @var string
  23       */
  24      public $name;
  25  
  26      /**
  27       * Block type render callback.
  28       *
  29       * @since 5.0.0
  30       * @var callable
  31       */
  32      public $render_callback;
  33  
  34      /**
  35       * Block type attributes property schemas.
  36       *
  37       * @since 5.0.0
  38       * @var array
  39       */
  40      public $attributes;
  41  
  42      /**
  43       * Block type editor script handle.
  44       *
  45       * @since 5.0.0
  46       * @var string
  47       */
  48      public $editor_script;
  49  
  50      /**
  51       * Block type front end script handle.
  52       *
  53       * @since 5.0.0
  54       * @var string
  55       */
  56      public $script;
  57  
  58      /**
  59       * Block type editor style handle.
  60       *
  61       * @since 5.0.0
  62       * @var string
  63       */
  64      public $editor_style;
  65  
  66      /**
  67       * Block type front end style handle.
  68       *
  69       * @since 5.0.0
  70       * @var string
  71       */
  72      public $style;
  73  
  74      /**
  75       * Constructor.
  76       *
  77       * Will populate object properties from the provided arguments.
  78       *
  79       * @since 5.0.0
  80       *
  81       * @see register_block_type()
  82       *
  83       * @param string       $block_type Block type name including namespace.
  84       * @param array|string $args       Optional. Array or string of arguments for registering a block type.
  85       *                                 Default empty array.
  86       */
  87  	public function __construct( $block_type, $args = array() ) {
  88          $this->name = $block_type;
  89  
  90          $this->set_props( $args );
  91      }
  92  
  93      /**
  94       * Renders the block type output for given attributes.
  95       *
  96       * @since 5.0.0
  97       *
  98       * @param array  $attributes Optional. Block attributes. Default empty array.
  99       * @param string $content    Optional. Block content. Default empty string.
 100       * @return string Rendered block type output.
 101       */
 102  	public function render( $attributes = array(), $content = '' ) {
 103          if ( ! $this->is_dynamic() ) {
 104              return '';
 105          }
 106  
 107          $attributes = $this->prepare_attributes_for_render( $attributes );
 108  
 109          return (string) call_user_func( $this->render_callback, $attributes, $content );
 110      }
 111  
 112      /**
 113       * Returns true if the block type is dynamic, or false otherwise. A dynamic
 114       * block is one which defers its rendering to occur on-demand at runtime.
 115       *
 116       * @since 5.0.0
 117       *
 118       * @return boolean Whether block type is dynamic.
 119       */
 120  	public function is_dynamic() {
 121          return is_callable( $this->render_callback );
 122      }
 123  
 124      /**
 125       * Validates attributes against the current block schema, populating
 126       * defaulted and missing values.
 127       *
 128       * @since 5.0.0
 129       *
 130       * @param  array $attributes Original block attributes.
 131       * @return array             Prepared block attributes.
 132       */
 133  	public function prepare_attributes_for_render( $attributes ) {
 134          // If there are no attribute definitions for the block type, skip
 135          // processing and return vebatim.
 136          if ( ! isset( $this->attributes ) ) {
 137              return $attributes;
 138          }
 139  
 140          foreach ( $attributes as $attribute_name => $value ) {
 141              // If the attribute is not defined by the block type, it cannot be
 142              // validated.
 143              if ( ! isset( $this->attributes[ $attribute_name ] ) ) {
 144                  continue;
 145              }
 146  
 147              $schema = $this->attributes[ $attribute_name ];
 148  
 149              // Validate value by JSON schema. An invalid value should revert to
 150              // its default, if one exists. This occurs by virtue of the missing
 151              // attributes loop immediately following. If there is not a default
 152              // assigned, the attribute value should remain unset.
 153              $is_valid = rest_validate_value_from_schema( $value, $schema );
 154              if ( is_wp_error( $is_valid ) ) {
 155                  unset( $attributes[ $attribute_name ] );
 156              }
 157          }
 158  
 159          // Populate values of any missing attributes for which the block type
 160          // defines a default.
 161          $missing_schema_attributes = array_diff_key( $this->attributes, $attributes );
 162          foreach ( $missing_schema_attributes as $attribute_name => $schema ) {
 163              if ( isset( $schema['default'] ) ) {
 164                  $attributes[ $attribute_name ] = $schema['default'];
 165              }
 166          }
 167  
 168          return $attributes;
 169      }
 170  
 171      /**
 172       * Sets block type properties.
 173       *
 174       * @since 5.0.0
 175       *
 176       * @param array|string $args Array or string of arguments for registering a block type.
 177       */
 178  	public function set_props( $args ) {
 179          $args = wp_parse_args(
 180              $args,
 181              array(
 182                  'render_callback' => null,
 183              )
 184          );
 185  
 186          $args['name'] = $this->name;
 187  
 188          foreach ( $args as $property_name => $property_value ) {
 189              $this->$property_name = $property_value;
 190          }
 191      }
 192  
 193      /**
 194       * Get all available block attributes including possible layout attribute from Columns block.
 195       *
 196       * @since 5.0.0
 197       *
 198       * @return array Array of attributes.
 199       */
 200  	public function get_attributes() {
 201          return is_array( $this->attributes ) ?
 202              array_merge(
 203                  $this->attributes,
 204                  array(
 205                      'layout' => array(
 206                          'type' => 'string',
 207                      ),
 208                  )
 209              ) :
 210              array(
 211                  'layout' => array(
 212                      'type' => 'string',
 213                  ),
 214              );
 215      }
 216  }