lzb/include_template
Filters the theme template file a block is about to include, and is the last filter to run on that path.
Source marks this one DEPRECATED. It is not an alias of lzb/block_render/include_template: it takes three arguments where that one takes five, and it fires after it. Write new code against the longer name and reach for this one only to read what an existing handler does.
The two names do not line up argument by argument either. lzb/block_render/include_template never receives $template_name, its second argument is the block attributes, so a callback cannot be moved between the two filters unchanged.
Attributes
| Name | Type | Description |
|---|---|---|
$template | String | absolute path resolved so far, empty when locate_template() found nothing |
$template_name | String | theme relative path being looked up, /blocks/lazyblock-my-block/block.php |
$args | Array | render arguments, see below |
$args has exactly four keys:
| Name | Type | Description |
|---|---|---|
attributes | Array | block attributes |
block | Array | block data |
render_location | String | editor or frontend |
context | WP_Block | null | block context provided by parent blocks |
The editor asks for /blocks/BLOCK_SLUG/editor.php first and falls back to /blocks/BLOCK_SLUG/block.php, with the slash in the slug replaced by a dash. Both file names arrive here as $template_name.
Usage
function my_lzb_include_template( $template, $template_name, $args ) {
// Keep the block templates of a plugin in the plugin, not in the theme.
if ( 0 !== strpos( $args['block']['slug'], 'lazyblock/acme-' ) ) {
return $template;
}
$plugin_template = plugin_dir_path( __FILE__ ) . 'templates' . $template_name;
return file_exists( $plugin_template ) ? $plugin_template : $template;
}
add_filter( 'lzb/include_template', 'my_lzb_include_template', 10, 3 );This filter runs after lzb/block_render/include_template and after both per-slug variants, so whatever it returns is the path that gets included. The include only happens when file_exists() passes, so returning a path that is not there renders the block as an empty string rather than raising a warning. Pair it with lzb/template_exists, which decides whether the file is looked for at all.
$args is also expanded into $attributes, $block, $render_location and $context variables inside the included template, which is how the Theme Template output method reads block values.