Using WordPress ‘pre_get_block_template’ PHP filter

by

pre_get_block_template is a WordPress PHP filter that allows you to modify the block template object before the query takes place. You can return a non-null value to bypass the default WordPress queries.

Usage

add_filter( 'pre_get_block_template', 'your_custom_function', 10, 3 );

function your_custom_function( $block_template, $id, $template_type ) {
    // your custom code here

    return $block_template;
}

Parameters

  • $block_template (WP_Block_Template|null) – Return a block template object to short-circuit the default query, or null to let WordPress run its normal queries.
  • $id (string) – The template’s unique identifier (e.g., theme_slug//template_slug).
  • $template_type (string) – The template type, either 'wp_template' or 'wp_template_part'.

More information

See WordPress Developer Resources: pre_get_block_template

Examples

Bypass default query for a specific template

This example bypasses the default query for a specific template and returns a custom WP_Block_Template object.

add_filter( 'pre_get_block_template', 'bypass_query_for_specific_template', 10, 3 );

function bypass_query_for_specific_template( $block_template, $id, $template_type ) {
    if ( $id === 'your-theme-slug//your-template-slug' ) {
        // Create a custom WP_Block_Template object
        $custom_template = new WP_Block_Template();
        $custom_template->id = $id;
        $custom_template->template_type = $template_type;

        return $custom_template;
    }

    return $block_template;
}

Change template type for a specific template

This example changes the template type for a specific template.

add_filter( 'pre_get_block_template', 'change_template_type_for_specific_template', 10, 3 );

function change_template_type_for_specific_template( $block_template, $id, $template_type ) {
    if ( $id === 'your-theme-slug//your-template-slug' ) {
        $block_template->template_type = 'wp_template_part';
    }

    return $block_template;
}

Log template details before query

This example logs the template details before the query takes place.

add_filter( 'pre_get_block_template', 'log_template_details', 10, 3 );

function log_template_details( $block_template, $id, $template_type ) {
    error_log( "Template ID: " . $id );
    error_log( "Template Type: " . $template_type );

    return $block_template;
}

Filter templates based on user roles

This example filters templates based on user roles, showing a different template for admins.

add_filter( 'pre_get_block_template', 'filter_templates_based_on_user_role', 10, 3 );

function filter_templates_based_on_user_role( $block_template, $id, $template_type ) {
    if ( current_user_can( 'administrator' ) && $id === 'your-theme-slug//non-admin-template-slug' ) {
        return get_block_template( 'your-theme-slug//admin-template-slug', $template_type );
    }

    return $block_template;
}

Apply custom CSS class to a specific template

This example applies a custom CSS class to a specific template.

add_filter( 'pre_get_block_template', 'apply_custom_css_class_to_specific_template', 10, 3 );
function apply_custom_css_class_to_specific_template( $block_template, $id, $template_type ) { 
    if ( $id === 'your-theme-slug//your-template-slug' ) { 
        $block_template->content = '<div class="custom-css-class">' . $block_template->content . '</div>'; 
    }
    return $block_template;
}