HowTo: WordPress Plugin Supplied Templates for Custom Post Types

While prototyping a WordPress plugin I’m writing, I experimented with supplying default templates to display pages related to a custom post type. This is accomplished using the template_redirect action API.  If the following technique is not used, any special templates a plugin provides would need to be copied to the active theme, making plugin installation more complex than necessary.

The first step in building the template_redirect action is to determine if the page being displayed is either a single page or archive of the custom post type. WordPress supplies the functions is_singular() and is_post_type_archive() for this purpose. If it’s a page that does not have a plugin supplied template, the function should return allowing WordPress core to select the correct template to use.

if (is_singular($my_post_type)) {
  $template_name = 'single-';
} elseif (is_post_type_archive($my_post_type)) {
  $template_name = 'archive-';
} else {
  return;
}

Next, I build the full name for the template file that will be used and attempt to locate one supplied by the active theme. The WordPress function locate_template() will return the path to a matching template if one is present.

$template_name .= get_post_type($post) . '.php';
// Look for theme provided template
$template = locate_template(array($template_name), true);

Finally, if the theme does not supply a template, the plugin supplied default template is used. When the template_redirect action does use an alternate template, it is expected to exit and no further processing should be done by WordPress core.

if (empty($template)) {
  include(WP_PLUGIN_DIR . '/my-plugin-dir/template/' . $template_name);
}
exit();

Putting this all together, here’s the entire code snippet:

function my_template_redirect()
{
  global $post;
  global $my_post_type;
  if (is_singular($my_post_type)) {
    $template_name = 'single-';
  } elseif (is_post_type_archive($my_post_type)) {
    $template_name = 'archive-';
  } else {
    return;
  }
  $template_name .= get_post_type($post) . '.php';
  // Look for available templates
  $template = locate_template(array($template_name), true);
  if (empty($template)) {
    include(WP_PLUGIN_DIR . '/my-plugin-dir/template/' . $template_name);
  }
  exit();
}
add_action('template_redirect', 'my_template_redirect');