template_include │ filter-hook │ WP 3.0.0

Allows changing the path to the selected template file used to display the current page, such as single.php or page.php.

Fires before the selected theme template file is included. This filter is used to change the path to that file.

Usage

add_filter( 'template_include', 'wp_kama_template_include_filter' );

/**
 * Function for `template_include` filter-hook.
 * 
 * @param string $template The path of the template to include.
 *
 * @return string
 */
function wp_kama_template_include_filter( $template ){

	// filter...
	return $template;
}

$template(string)

The full path to the file that will be included as the template. Example: home/example.com/wp-content/themes/publisher/page.php.

Examples

#1 The template_include filter

A third way to create a separate template file for a page with the portfolio slug is to use the template_include filter:

add_filter( 'template_include', 'portfolio_page_template', 99 );
function portfolio_page_template( $template ) {

	if( is_page('portfolio') ){

		$new_template = locate_template( array( 'portfolio-page-template.php' ) );

		if ( $new_template ){
			$template = $new_template ;
		}
	}

	return $template;
}

#2 Template for all child pages

Suppose we have a page template and that page has child pages. Let us assign a custom page template to the parent and all its child pages.

add_filter( 'template_include', 'wp_kama_template_include_filter' );

function wp_kama_template_include_filter( $template ) {

	$parent_page_id = 25;
	$post = get_queried_object();

	if( is_page( $parent_page_id ) || $parent_page_id === $post->post_parent ){
		return get_theme_file_path( 'templates/page-myname.php' );
	}

	return $template;
}

#3 A file in the theme directory

A template for a static page can be defined by creating a file in the theme directory and adding a PHP comment at the beginning of the file:

<?php
/**
 * Template Name: Portfolio
 */

Then select the newly created template from the drop-down list when creating the page.

Theme file with an exact name

Alternatively, create a page-portfolio.php file in the theme. In this case, the page slug must be portfolio.

#4 Find which template file is currently being used

## Which template is used at the current moment
add_filter( 'template_include', 'echo_cur_tplfile', 99 );
function echo_cur_tplfile( $template ){

	echo '<span style="color:red">'. wp_basename( $template ) .'</span>';

	return $template;
}

#5 Use a PHP function as a template file

Sometimes it is convenient to create a PHP function containing the template code instead of creating a separate file. To run such a function as a template file, call it from the template_include hook:

<?php
// Include the page template
add_filter('template_include', 'book_archive_tpl_include');
function book_archive_tpl_include( $template ){
	if( ! is_post_type_archive('book') )
		return $template;

	book_archive_tpl();
}

// Page template
function book_archive_tpl(){
	get_header();
	get_sidebar();
	?>

	<div>
		<h1>Heading</h1>
		<p>Some text</p>
	</div>

	<?php
	get_footer();
}

Keep in mind:

Technically, this is an incorrect solution, but it works. Here the filter is used as an event. Because this filter is called last among filters unrelated to template selection, the required template code can be output when it runs.

In general, this approach is not recommended. Use it only when absolutely necessary.