WordPress Development Stack Exchange is a question and answer site for WordPress developers and administrators. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

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.

share|improve this question
possible duplicate of Custom Post Type Templates from Plugin Folder? – Johannes Pille Apr 21 '13 at 15:58
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. – chrisguitarguy Apr 21 '13 at 16:01
@JohannesPille I did search before asking. But thanks for the link. I'll be looking into it. – NotoriousWebmaster Apr 21 '13 at 16:04
@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. – NotoriousWebmaster Apr 21 '13 at 16:06
up vote 5 down vote accepted

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;
share|improve this answer
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. – NotoriousWebmaster Apr 21 '13 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.

share|improve this answer
Yeah, you're right, it would change the look, including layout, widgets and such. Too radical for my taste. But thanks. – NotoriousWebmaster Apr 21 '13 at 16:20

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.

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