Custom post type template not loading from plugin

Question

I've created a custom post type called jdshs_jobs in a plugin and I have tried to get Wordpress to associate a template (single-jdshs_jobs.php) from within in sub-folder:

.../plugins/plugin-name/templates

I've attempted to tell Wordpress about the location by hooking a callback to theme_template_path on the back of a hook onto after_setup_theme. I also attempted this on the back of a hook onto plugins_loaded and i even tried it on the init hook.

This is a flavour of how I attempted it:

/**
 * Add custom template location from plugin sub-directory.
 *
 * @param array $template_paths An array of current locations.
 */
function custom_plugin_template_location( $template_paths ) {
    // Path to the plugin's templates directory
    $plugin_template_dir = plugin_dir_path( __FILE__ ) . 'templates/';

    // Add the plugin's templates directory to the list of template locations
    $template_paths[] = $plugin_template_dir;

    return $template_paths;
}
add_filter( 'theme_template_path', 'custom_plugin_template_location' );

In all three cases the custom template isn't being loaded.

I've confirmed that the template location has been added to the list of locations yet still it's not loading. WP is defaulting to the single template in the theme's template folder. I have twenty twenty four theme active while I'm developing a plugin.

I don't know if that is part of the problem or not because I tried copying the template into the theme template folder but still it didn't work.

What did work though was renaming it with a .html extension, however then none of the php aspects worked but it proved that it could be picked up from that location.

Trying to get the template to be picked up from within the plugin template folder by renaming the extension didn't work either.

Ideally I want to register the template directory as a template location and let Wordpress just pick up the relevant templates without having to do anything else.

It's not a deal breaker because I have managed to use my custom templates from the plugin subdirectory. This is how I've done it and it works quite nicely.

In my main plugin file I have the following call:

// Add custom post templates
add_action('plugins_loaded', function() {
    require_once plugin_dir_path(__FILE__) . 'src/PageTemplater.php';
    global $jdsh_solomons_jobs_templater;
    $jdsh_solomons_jobs_templater = new PageTemplater();
    $jdsh_solomons_jobs_templater->init();
});

And here's the code for my PageTemplater class:

if ( ! class_exists( 'PageTemplater' ) ) {

    /**
     * Registers page templates for the Solomons Jobs custom post type.
     */
    class PageTemplater {
        
        public function __construct() {}

        /**
         * Initilies the template registration.
         */
        public function init() {
            add_filter( 'single_template', array( &$this, 'attach_single_template' ) );
            add_filter( 'archive_template', array( &$this, 'attache_archive_template' ) );
        }
        
        /**
         * Attaches our template for the CPT.
         * 
         * @param string $template The path to the default template.
         */
        public function attach_single_template( $template ) {
            global $post;

            // Check to make sure this is one of our CPTs.
            if ( 'jdshs_jobs' === $post->post_type ) {
                $path = plugin_dir_path( __DIR__ ) . 'templates/jdshs-job-template.php';
                if ( file_exists( $path ) ) {
                    return $path;
                }
            }

            return $template;
        }

        /**
         * Attaches our archive template to archive view of our CPT.
         * 
         * @param string $template The path to the default template.
         */
        public function attache_archive_template( $template ) {
            if ( is_post_type_archive('jdshs_jobs') ) {
                $path = plugin_dir_path( __DIR__ ) . 'templates/jdshs-jobs-template.php';
                if ( file_exists( $path ) ) {
                    return $path;
                }
            }
            return $template;
        }
    }
}

From other similar questions I've seen that this approach seems to be consensus approach and I'm more than happy to continue with it but it would be good to understand why my preferred method didn't work.

I've got a local server running in a docker container and I've tried bringing it down and back up to see if that might clear some sort of server cache.

Incidentally I have tried flushing the rewrite by visiting the permalinks page and even hitting save. I even changed the structure, saved then reverted and saved again to see if that might have been the issue but no.

If you've got this far in my rambling, thanks very much for your time. If you have any ideas or suggestions they would be appreciated.

Answer 1

I think your first method isn't working because it's a theme method, not a plugin method. I could be entirely incorrect but I think the method of using single-custom_post_type.php only works for themes. (Again, I 100% could be wrong.)

However, this is what I use and it always works:

function wpse_post_type_templates( $template ) {
    if( is_singular( 'jdshs_jobs' ) ) {
        $template = plugin_dir_path( __DIR__ ) . 'templates/jdshs-job-template.php';
    }
    return $template;
}
add_filter( 'single_template', 'wpse_post_type_templates', 50, 1 );

You can name the template file whatever you like, even single-jdshs_job.php and essentially for every template, you just add it using the conditional checks. ie. is_archive( 'jdshs_jobs' ) etc.