Using WordPress ‘pre_get_block_templates’ PHP filter

by

pre_get_block_templates is a WordPress PHP filter that allows you to modify the block templates array before the query takes place. By returning a non-null value, you can bypass the default WordPress queries.

Usage

add_filter('pre_get_block_templates', 'your_custom_function', 10, 2);

function your_custom_function($block_templates, $query) {
    // your custom code here
    return $block_templates;
}

Parameters

  • $block_templates (WP_Block_Template[]|null): Return an array of block templates to short-circuit the default query, or null to allow WordPress to run its normal queries.
  • $query (array): Arguments to retrieve templates. It includes:
    • slug__in (array): List of slugs to include.
    • wp_id (int): Post ID of the customized template.
    • post_type (string): Post type to get the templates for.
  • template_type (string): Either ‘wp_template’ or ‘wp_template_part’.

More information

See WordPress Developer Resources: pre_get_block_templates

Examples

Filter templates by specific slugs

Filter the templates to only include those with specific slugs.

add_filter('pre_get_block_templates', 'filter_templates_by_slug', 10, 2);

function filter_templates_by_slug($block_templates, $query) {
    $allowed_slugs = array('header', 'footer');
    $filtered_templates = array();

    foreach ($block_templates as $template) {
        if (in_array($template->slug, $allowed_slugs)) {
            $filtered_templates[] = $template;
        }
    }

    return $filtered_templates;
}

Exclude templates by ID

Exclude templates with specific IDs from the query.

add_filter('pre_get_block_templates', 'exclude_templates_by_id', 10, 2);

function exclude_templates_by_id($block_templates, $query) {
    $exclude_ids = array(10, 20, 30);
    $filtered_templates = array();

    foreach ($block_templates as $template) {
        if (!in_array($template->wp_id, $exclude_ids)) {
            $filtered_templates[] = $template;
        }
    }

    return $filtered_templates;
}

Limit templates to a specific post type

Only return templates for a specific post type.

add_filter('pre_get_block_templates', 'filter_templates_by_post_type', 10, 2);

function filter_templates_by_post_type($block_templates, $query) {
    $allowed_post_type = 'page';
    $filtered_templates = array();

    foreach ($block_templates as $template) {
        if ($template->post_type == $allowed_post_type) {
            $filtered_templates[] = $template;
        }
    }

    return $filtered_templates;
}

Filter templates by template type

Filter the templates to only include ‘wp_template’ or ‘wp_template_part’.

add_filter('pre_get_block_templates', 'filter_templates_by_type', 10, 2);

function filter_templates_by_type($block_templates, $query) {
    $allowed_template_type = 'wp_template';
    $filtered_templates = array();

    foreach ($block_templates as $template) {
        if ($template->template_type == $allowed_template_type) {
            $filtered_templates[] = $template;
        }
    }

    return $filtered_templates;
}

Bypass default query

Bypass the default WordPress query and provide a custom array of block templates.

add_filter('pre_get_block_templates', 'bypass_default_query', 10, 2);

function bypass_default_query($block_templates, $query) {
    // Create custom block templates array
    $custom_templates = array(
        new WP_Block_Template(array(
            'slug' => 'custom-header',
            'post_type' => 'page',
            'template_type' => 'wp_template'
        )),
        new WP_Block_Template(array(
            'slug' => 'custom-footer',
            'post_type' => 'page',
            'template_type' => 'wp_template'
        )),
    );

    return $custom_templates;
}

In this example, the filter bypasses the default WordPress query and returns a custom array of block templates that include a custom header and a custom footer for the ‘page’ post type.