[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Server-side rendering of the `core/template-part` block.
   4   *
   5   * @package WordPress
   6   */
   7  
   8  /**
   9   * Renders the `core/template-part` block on the server.
  10   *
  11   * @since 5.9.0
  12   *
  13   * @global WP_Embed $wp_embed WordPress Embed object.
  14   *
  15   * @param array $attributes The block attributes.
  16   *
  17   * @return string The render.
  18   */
  19  function render_block_core_template_part( $attributes ) {
  20      static $seen_ids = array();
  21  
  22      $template_part_id = null;
  23      $content          = null;
  24      $area             = WP_TEMPLATE_PART_AREA_UNCATEGORIZED;
  25      $theme            = $attributes['theme'] ?? get_stylesheet();
  26  
  27      if ( isset( $attributes['slug'] ) && get_stylesheet() === $theme ) {
  28          $template_part_id    = $theme . '//' . $attributes['slug'];
  29          $template_part_query = new WP_Query(
  30              array(
  31                  'post_type'           => 'wp_template_part',
  32                  'post_status'         => 'publish',
  33                  'post_name__in'       => array( $attributes['slug'] ),
  34                  'tax_query'           => array(
  35                      array(
  36                          'taxonomy' => 'wp_theme',
  37                          'field'    => 'name',
  38                          'terms'    => $theme,
  39                      ),
  40                  ),
  41                  'posts_per_page'      => 1,
  42                  'no_found_rows'       => true,
  43                  'lazy_load_term_meta' => false, // Do not lazy load term meta, as template parts only have one term.
  44              )
  45          );
  46          $template_part_post  = $template_part_query->have_posts() ? $template_part_query->next_post() : null;
  47          if ( $template_part_post ) {
  48              // A published post might already exist if this template part was customized elsewhere
  49              // or if it's part of a customized template.
  50              $block_template = _build_block_template_result_from_post( $template_part_post );
  51              $content        = $block_template->content;
  52              if ( isset( $block_template->area ) ) {
  53                  $area = $block_template->area;
  54              }
  55              /**
  56               * Fires when a block template part is loaded from a template post stored in the database.
  57               *
  58               * @since 5.9.0
  59               *
  60               * @param string  $template_part_id   The requested template part namespaced to the theme.
  61               * @param array   $attributes         The block attributes.
  62               * @param WP_Post $template_part_post The template part post object.
  63               * @param string  $content            The template part content.
  64               */
  65              do_action( 'render_block_core_template_part_post', $template_part_id, $attributes, $template_part_post, $content );
  66          } else {
  67              $template_part_file_path = '';
  68              // Else, if the template part was provided by the active theme,
  69              // render the corresponding file content.
  70              if ( 0 === validate_file( $attributes['slug'] ) ) {
  71                  $block_template = get_block_file_template( $template_part_id, 'wp_template_part' );
  72  
  73                  if ( isset( $block_template->content ) ) {
  74                      $content = $block_template->content;
  75                  }
  76                  if ( isset( $block_template->area ) ) {
  77                      $area = $block_template->area;
  78                  }
  79  
  80                  // Needed for the `render_block_core_template_part_file` and `render_block_core_template_part_none` actions below.
  81                  $block_template_file = _get_block_template_file( 'wp_template_part', $attributes['slug'] );
  82                  if ( $block_template_file ) {
  83                      $template_part_file_path = $block_template_file['path'];
  84                  }
  85              }
  86  
  87              if ( '' !== $content && null !== $content ) {
  88                  /**
  89                   * Fires when a block template part is loaded from a template part in the theme.
  90                   *
  91                   * @since 5.9.0
  92                   *
  93                   * @param string $template_part_id        The requested template part namespaced to the theme.
  94                   * @param array  $attributes              The block attributes.
  95                   * @param string $template_part_file_path Absolute path to the template path.
  96                   * @param string $content                 The template part content.
  97                   */
  98                  do_action( 'render_block_core_template_part_file', $template_part_id, $attributes, $template_part_file_path, $content );
  99              } else {
 100                  /**
 101                   * Fires when a requested block template part does not exist in the database nor in the theme.
 102                   *
 103                   * @since 5.9.0
 104                   *
 105                   * @param string $template_part_id        The requested template part namespaced to the theme.
 106                   * @param array  $attributes              The block attributes.
 107                   * @param string $template_part_file_path Absolute path to the not found template path.
 108                   */
 109                  do_action( 'render_block_core_template_part_none', $template_part_id, $attributes, $template_part_file_path );
 110              }
 111          }
 112      }
 113  
 114      // WP_DEBUG_DISPLAY must only be honored when WP_DEBUG. This precedent
 115      // is set in `wp_debug_mode()`.
 116      $is_debug = WP_DEBUG && WP_DEBUG_DISPLAY;
 117  
 118      if ( is_null( $content ) ) {
 119          if ( $is_debug && isset( $attributes['slug'] ) ) {
 120              return sprintf(
 121                  /* translators: %s: Template part slug. */
 122                  __( 'Template part has been deleted or is unavailable: %s' ),
 123                  $attributes['slug']
 124              );
 125          }
 126  
 127          return '';
 128      }
 129  
 130      if ( isset( $seen_ids[ $template_part_id ] ) ) {
 131          return $is_debug ?
 132              // translators: Visible only in the front end, this warning takes the place of a faulty block.
 133              __( '[block rendering halted]' ) :
 134              '';
 135      }
 136  
 137      // Look up area definition.
 138      $area_definition = null;
 139      $defined_areas   = get_allowed_block_template_part_areas();
 140      foreach ( $defined_areas as $defined_area ) {
 141          if ( $defined_area['area'] === $area ) {
 142              $area_definition = $defined_area;
 143              break;
 144          }
 145      }
 146  
 147      // If $area is not allowed, set it back to the uncategorized default.
 148      if ( ! $area_definition ) {
 149          $area = WP_TEMPLATE_PART_AREA_UNCATEGORIZED;
 150      }
 151  
 152      // Run through the actions that are typically taken on the_content.
 153      $content = _wp_apply_block_content_filters( $content, "template_part_{$area}", $seen_ids, $template_part_id );
 154  
 155      if ( empty( $attributes['tagName'] ) || tag_escape( $attributes['tagName'] ) !== $attributes['tagName'] ) {
 156          $area_tag = 'div';
 157          if ( $area_definition && isset( $area_definition['area_tag'] ) ) {
 158              $area_tag = $area_definition['area_tag'];
 159          }
 160          $html_tag = $area_tag;
 161      } else {
 162          $html_tag = esc_attr( $attributes['tagName'] );
 163      }
 164      $wrapper_attributes = get_block_wrapper_attributes();
 165  
 166      return "<$html_tag $wrapper_attributes>" . str_replace( ']]>', ']]&gt;', $content ) . "</$html_tag>";
 167  }
 168  
 169  /**
 170   * Returns an array of area variation objects for the template part block.
 171   *
 172   * @since 6.1.0
 173   *
 174   * @param array $instance_variations The variations for instances.
 175   *
 176   * @return array Array containing the block variation objects.
 177   */
 178  function build_template_part_block_area_variations( $instance_variations ) {
 179      $variations    = array();
 180      $defined_areas = get_allowed_block_template_part_areas();
 181  
 182      foreach ( $defined_areas as $area ) {
 183          if ( 'uncategorized' !== $area['area'] && 'navigation-overlay' !== $area['area'] ) {
 184              $has_instance_for_area = false;
 185              foreach ( $instance_variations as $variation ) {
 186                  if ( $variation['attributes']['area'] === $area['area'] ) {
 187                      $has_instance_for_area = true;
 188                      break;
 189                  }
 190              }
 191  
 192              $scope = $has_instance_for_area ? array() : array( 'inserter' );
 193  
 194              $variations[] = array(
 195                  'name'        => 'area_' . $area['area'],
 196                  'title'       => $area['label'],
 197                  'description' => $area['description'],
 198                  'attributes'  => array(
 199                      'area' => $area['area'],
 200                  ),
 201                  'scope'       => $scope,
 202                  'icon'        => $area['icon'],
 203              );
 204          }
 205      }
 206      return $variations;
 207  }
 208  
 209  /**
 210   * Returns an array of instance variation objects for the template part block
 211   *
 212   * @since 6.1.0
 213   *
 214   * @return array Array containing the block variation objects.
 215   */
 216  function build_template_part_block_instance_variations() {
 217      // Block themes are unavailable during installation.
 218      if ( wp_installing() ) {
 219          return array();
 220      }
 221  
 222      if ( ! current_theme_supports( 'block-templates' ) && ! current_theme_supports( 'block-template-parts' ) ) {
 223          return array();
 224      }
 225  
 226      $variations     = array();
 227      $template_parts = get_block_templates(
 228          array(
 229              'post_type' => 'wp_template_part',
 230          ),
 231          'wp_template_part'
 232      );
 233  
 234      $defined_areas = get_allowed_block_template_part_areas();
 235      $icon_by_area  = array_combine( array_column( $defined_areas, 'area' ), array_column( $defined_areas, 'icon' ) );
 236  
 237      foreach ( $template_parts as $template_part ) {
 238          // Navigation overlay template parts should not appear in the
 239          // general inserter. They are managed through the Navigation
 240          // block's overlay template part selector.
 241          $scope = ( 'navigation-overlay' === $template_part->area )
 242              ? array()
 243              : array( 'inserter' );
 244  
 245          $variations[] = array(
 246              'name'        => 'instance_' . sanitize_title( $template_part->slug ),
 247              'title'       => $template_part->title,
 248              // If there's no description for the template part don't show the
 249              // block description. This is a bit hacky, but prevent the fallback
 250              // by using a non-breaking space so that the value of description
 251              // isn't falsey.
 252              'description' => $template_part->description || '&nbsp;',
 253              'attributes'  => array(
 254                  'slug'  => $template_part->slug,
 255                  'theme' => $template_part->theme,
 256                  'area'  => $template_part->area,
 257              ),
 258              'scope'       => $scope,
 259              'icon'        => $icon_by_area[ $template_part->area ] ?? null,
 260              'example'     => array(
 261                  'attributes' => array(
 262                      'slug'  => $template_part->slug,
 263                      'theme' => $template_part->theme,
 264                      'area'  => $template_part->area,
 265                  ),
 266              ),
 267          );
 268      }
 269      return $variations;
 270  }
 271  
 272  /**
 273   * Returns an array of all template part block variations.
 274   *
 275   * @since 5.9.0
 276   *
 277   * @return array Array containing the block variation objects.
 278   */
 279  function build_template_part_block_variations() {
 280      $instance_variations = build_template_part_block_instance_variations();
 281      $area_variations     = build_template_part_block_area_variations( $instance_variations );
 282      return array_merge( $area_variations, $instance_variations );
 283  }
 284  
 285  /**
 286   * Registers the `core/template-part` block on the server.
 287   *
 288   * @since 5.9.0
 289   */
 290  function register_block_core_template_part() {
 291      register_block_type_from_metadata(
 292          __DIR__ . '/template-part',
 293          array(
 294              'render_callback'    => 'render_block_core_template_part',
 295              'variation_callback' => 'build_template_part_block_variations',
 296          )
 297      );
 298  }
 299  add_action( 'init', 'register_block_core_template_part' );