I'm writing a custom post type plugin. Part of it I'm outputting to the template via shortcodes. But other parts need a custom post template, and I figured out how to use the template hierarchy for CPT's. But the custom template is in the theme, and I'm thinking the plugin should be self-contained, at least to start with.

So what's the best practice here? How do we include template files in a CPT plugin? Can you point me to especially good examples of how this is done?

Thanks for your help.

  • 1
    possible duplicate of Custom Post Type Templates from Plugin Folder? Apr 21, 2013 at 15:58
  • 1
    Not sure it's a duplicate, but it's a subjective question. Best practice to me would be to let the theme handle it. Best practices to others would be to make the plugin completely self-contained. Apr 21, 2013 at 16:01
  • @JohannesPille I did search before asking. But thanks for the link. I'll be looking into it. Apr 21, 2013 at 16:04
  • 1
    @chrisguitarguy Agreed. My issue with letting the theme handle it is if we switch themes, we have to do some customization to accommodate the plugin. Otherwise, we lose the stuff the CPT brings to the party. Apr 21, 2013 at 16:06

2 Answers 2


So what's the best practice here?

I would say a combination of letting the theme handle it and providing a default with your plugin.

You can use the single_template filter to switch out the template. In your callback, see if the theme provided a template for the post type, if it did, do nothing.

add_filter('single_template', 'wpse96660_single_template');
function wpse96660_single_template($template)
    if ('your_post_type' == get_post_type(get_queried_object_id()) && !$template) {
        // if you're here, you're on a singlar page for your costum post 
        // type and WP did NOT locate a template, use your own.
        $template = dirname(__FILE__) . '/path/to/fallback/template.php';
    return $template;

I like this method the best. Combine it with providing a sound set of "template tags" (eg. the_content, the_title) that support whatever custom data that goes along with your post type and you give the end user a lot of customization power along with some sound defaults. Bbpress does this sort of thing really well: includes user templates if it finds them and provide a lot of template tags.

Alternatively, you can use a callback with the_content filter, and just change stuff in the content itself.

add_filter('the_content', 'wpse96660_the_content');

function wpse96660_the_content($content)
    if (is_singular('your_post_type') && in_the_loop()) {
        // change stuff
        $content .= '<p>here we are on my custom post type</p>';

    return $content;
  • I agree with @toscho that there is not clean solution. But I like the concept of offering a set of category tags. I suspect ultimately I'll have a theme folder in my plugin, with a sample CPT template, and recommend users adapt it to their circumstances. I also like the the_content filter, because that plugs my content within the user's layout. I may implement both, and allow the user to chose which way to go with an option toggle. Apr 21, 2013 at 17:34

You could hook into template_include and return your plugin file if the request is for your post type:

add_filter( 'template_include', 'insert_my_template' );

function insert_my_template( $template )
    if ( 'my_post_type' === get_post_type() )
        return dirname( __FILE__ ) . '/template.php';

    return $template;

But this will change the look drastically. There is still no clean solution.

  • Yeah, you're right, it would change the look, including layout, widgets and such. Too radical for my taste. But thanks. Apr 21, 2013 at 16:20

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.