template_include (overriding default plugin templates via current theme)

by

So the template_redirect is used for things such as canonicalisation, feeds etc. If you want to alter the template that is served template_include is preferred.

Unlike template_redirect, template_include is a filter which filters the path of the template page. This means you don’t load/include the template, but just return the template path. WordPress does a straight-forward include on whatever is returned.

Apart from being the appropriate hook, it allows allows the function to be unhooked or over-ridden – which is should be if it’ll ever be distributed.

Related question: Custom Taxonomy in plugin and template

Example of this in action (GitHub Repro): https://github.com/stephenh1988/Event-Organiser/blob/master/includes/event-organiser-templates.php

Example usage:

 function wpse51038_maybe_alter_template($template){

    // is a specific custom taxonomy being shown?
    $taxonomy_array = array('profile_categories','combination_categories','wood_types');
    foreach ($taxonomy_array as $taxonomy_single) {
        if ( is_tax($taxonomy_single) ) {
            //For plugins. You may want to check this template exists before over-riding
            $template = plugin_dir_path('path/to/my/tax-template.php', __FILE__ );
            break;
        }
    }

  return $template;

 }
 add_filter('template_include','wpse51038_maybe_alter_template');

You may want to look at the related question linked to above – this shows how to allow the theme to over-ride the plug-in (say if they have a particularly named template file in their theme/child-theme).

Leave a Comment