get_block_templates( array $query = array(), string $template_type = 'wp_template' ): array

Retrieves a list of unified template objects based on a query.


Parameters

$query array Optional
Arguments to retrieve templates.
  • slug__in array
    List of slugs to include.
  • wp_id int
    Post ID of customized template.
  • area string
    A 'wp_template_part_area' taxonomy value to filter by (for wp_template_part template type only).
  • post_type string
    Post type to get the templates for.

Default: array()

$template_type string Optional
'wp_template' or 'wp_template_part'.

Default: 'wp_template'


Top ↑

Return

array Templates.


Top ↑

Source

File: wp-includes/block-template-utils.php. View all references

function get_block_templates( $query = array(), $template_type = 'wp_template' ) {
	/**
	 * Filters the block templates array before the query takes place.
	 *
	 * Return a non-null value to bypass the WordPress queries.
	 *
	 * @since 5.9.0
	 *
	 * @param WP_Block_Template[]|null $block_templates Return an array of block templates to short-circuit the default query,
	 *                                                  or null to allow WP to run it's normal queries.
	 * @param array  $query {
	 *     Optional. Arguments to retrieve templates.
	 *
	 *     @type array  $slug__in List of slugs to include.
	 *     @type int    $wp_id Post ID of customized template.
	 *     @type string $post_type Post type to get the templates for.
	 * }
	 * @param string $template_type wp_template or wp_template_part.
	 */
	$templates = apply_filters( 'pre_get_block_templates', null, $query, $template_type );
	if ( ! is_null( $templates ) ) {
		return $templates;
	}

	$post_type     = isset( $query['post_type'] ) ? $query['post_type'] : '';
	$wp_query_args = array(
		'post_status'    => array( 'auto-draft', 'draft', 'publish' ),
		'post_type'      => $template_type,
		'posts_per_page' => -1,
		'no_found_rows'  => true,
		'tax_query'      => array(
			array(
				'taxonomy' => 'wp_theme',
				'field'    => 'name',
				'terms'    => get_stylesheet(),
			),
		),
	);

	if ( 'wp_template_part' === $template_type && isset( $query['area'] ) ) {
		$wp_query_args['tax_query'][]           = array(
			'taxonomy' => 'wp_template_part_area',
			'field'    => 'name',
			'terms'    => $query['area'],
		);
		$wp_query_args['tax_query']['relation'] = 'AND';
	}

	if ( isset( $query['slug__in'] ) ) {
		$wp_query_args['post_name__in'] = $query['slug__in'];
	}

	// This is only needed for the regular templates/template parts post type listing and editor.
	if ( isset( $query['wp_id'] ) ) {
		$wp_query_args['p'] = $query['wp_id'];
	} else {
		$wp_query_args['post_status'] = 'publish';
	}

	$template_query = new WP_Query( $wp_query_args );
	$query_result   = array();
	foreach ( $template_query->posts as $post ) {
		$template = _build_block_template_result_from_post( $post );

		if ( is_wp_error( $template ) ) {
			continue;
		}

		if ( $post_type && ! $template->is_custom ) {
			continue;
		}

		if (
			$post_type &&
			isset( $template->post_types ) &&
			! in_array( $post_type, $template->post_types, true )
		) {
			continue;
		}

		$query_result[] = $template;
	}

	if ( ! isset( $query['wp_id'] ) ) {
		$template_files = _get_block_templates_files( $template_type );
		foreach ( $template_files as $template_file ) {
			$template = _build_block_template_result_from_file( $template_file, $template_type );

			if ( $post_type && ! $template->is_custom ) {
				continue;
			}

			if ( $post_type &&
				isset( $template->post_types ) &&
				! in_array( $post_type, $template->post_types, true )
			) {
				continue;
			}

			$is_not_custom   = false === array_search(
				get_stylesheet() . '//' . $template_file['slug'],
				wp_list_pluck( $query_result, 'id' ),
				true
			);
			$fits_slug_query =
				! isset( $query['slug__in'] ) || in_array( $template_file['slug'], $query['slug__in'], true );
			$fits_area_query =
				! isset( $query['area'] ) || $template_file['area'] === $query['area'];
			$should_include  = $is_not_custom && $fits_slug_query && $fits_area_query;
			if ( $should_include ) {
				$query_result[] = $template;
			}
		}
	}

	/**
	 * Filters the array of queried block templates array after they've been fetched.
	 *
	 * @since 5.9.0
	 *
	 * @param WP_Block_Template[] $query_result Array of found block templates.
	 * @param array  $query {
	 *     Optional. Arguments to retrieve templates.
	 *
	 *     @type array  $slug__in List of slugs to include.
	 *     @type int    $wp_id Post ID of customized template.
	 * }
	 * @param string $template_type wp_template or wp_template_part.
	 */
	return apply_filters( 'get_block_templates', $query_result, $query, $template_type );
}

Top ↑

Hooks



Top ↑

Changelog

Changelog
Version Description
5.8.0 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    Contributed by Bastien Ho

    Setting default templates by a plugin can be done like this:

    add_filter('get_block_templates', function($query_result, $query, $template_type){
      // Check if query is not altered
      if( isset($query['theme']) && isset($query['slug__in']) && isset($query['slug__in'][1])){
          // Check if a template exists for each slug
          foreach($query['slug__in'] as $slug){
            $template_file_path = plugin_dir_path(__FILE__).'/templates/' . $slug . '.html';
            if(file_exists($template_file_path)){
    			// Append a fake template to query results
                $html = file_get_contents($template_file_path);
                array_push($query_result, (object) [
                    'title' => sprintf(__('Default %s', 'textdomain'), $slug),
                    'slug' => $slug,
                    'status' => 'publish',
                    'type' => 'wp_template',
                    'description' => sprintf(__('Default %s template', 'textdomain'), $slug),
                    'content' => $html,
                    'source' => 'plugin',
                    'is_custom' => false,
                    'is_customized' => false,
                    'is_reusable' => false,
                    'is_reserved' => false,
                    'is_published' => true,
                    'is_wp_template_part' => false,
                ]);
            }
          }
      }
      return $query_result;
    }, 10, 3);

    Template files created in the `templates` directory will be low level templates. They’ll be overridden by templates from the Theme, and from the Editor.

You must log in before being able to contribute a note or feedback.