1. Code
  2. Creative Coding

Plugin Templating within WordPress

Scroll to top
Read Time: 6 min

When it comes to creating a Custom Post Type within a WordPress plugin, there's always the same problem: you need to create a custom single-[cpt_slug].php file in your theme folder if you don't want to use the default single.php file from your theme.

In this post I'd like to cover two aspects of using custom templates. The first step is to show that we can use a custom file contained directly in the plugin itself instead of loading the default single.php, and the second one is how to create your own custom file in your theme folder.

Many plugins like Easy Digital Downloads or Shopp, use this method: the plugin checks if you define a custom template in your theme folder, if it is the case then the file is loaded, otherwise the default plugin template file is loaded. In both cases the theme default single.php file isn't loaded.

Define the Plugin and Its Structure

The very first step is to create a plugin, let's call it "Template Chooser". Create a "template-chooser" folder under /wp-content/plugins/, with the following structure:

template_chooser_structureThe plugin structure

Then open the main file template-choose.php and place the following plugin header code:

Define the Plugin Constants

Later in the plugin we will need to easily retrieve the plugin URL and its path, that's why we need to define a few constants:

Register a Custom Post Type

To go further, we have to setup a new custom post type, let's create a "Testimonial" CPT, with some very basic supports and features. As the aim of the post is not to teach how to create a custom post type, I'll use a pretty simple code divided in 3 parts: the custom post type labels, the supports, and the custom post type arguments. All that embed in a single function:

Do Not Use the Default single.php File

Now that our custom post type is registered, we need to create a function that will tell WordPress not to use the default single.php from the theme.

Because yes by default when displaying a custom post type on the frontend WordPress will check if a file called single-testimonial.php exists and will load it. If not, it will look for the single.php. But we don't want to use any of them.

We want WordPress to load a custom file from the plugin. To do so, we have to hook a new function to the "template_include" filter. In this function the aim is to check the type of the post and act in consequence:

Load the Right Template

As you can see, on line 33 we are calling a new function rc_tc_get_template_hierarchy(). This is the function that will check if WordPress has to load the custom file from the plugin or the template from the theme folder.

Please note that when I'm talking about the "template from the theme folder", I'm talking about a custom file loaded instead of the single.php.

Let's say you don't want to load the template included in the plugin but create your own custom template, all you have to do is to create a new folder in the theme folder, name it "plugin_template" and within this folder create a single.php file. This will be your new default single.php loaded only for testimonials displayed on the frontend.

Are you still with me? Okay, so let's create the function:

The Plugin Default Template

Now create a new testimonial in the administration. Then open includes/templates/single.php and then copy and paste this simple code:

If you visualize the testimonial on the frontend you should see the "we are in the plugin custom file". That's what we wanted. But if the plugin template file doesn't fit your needs or if you simply want to create a more personal design, you can create a file in your theme folder.

The Theme Default Template

To create a custom template that does not use the default one from the plugin, you can create a new folder called "plugin_templates" in your theme folder. Create a new file called single.php and place this code:


So what did we do exactly? Well, we created a plugin that registers a custom post type "Testimonial". We achieved functionality to load a custom file stored in the plugin folder instead of the default single.php or single-testimonial.php files from the theme folder. We also managed to load a custom file instead from the theme folder located under "plugin_templates".

Why is this nice? Because when you create your own plugin you can provide a default template to display the custom post type so you're giving the choice to the final user whether to use their own template or not.

Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on learning about the next big thing.
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.