If you’ve worked with WooCommerce before on a website then chances are you’ve also had to copy some of their templates files to your own theme in order to make sure structural changes to the page. This is a great system if you need to output HTML and still want to allow the end-user to be able to change things to fit it to their theme.

Adding template files

For this example I will create a templates folder within my plugin where I will add a simple page template file called redeem-gift-card.php. On that page someone can redeem their gift card (to keep line with the previous blog posts about adding custom WooCommerce fields to products where I also used gift cards as an example).

In this example the gift card will be loaded via shortcode, you also could create a custom endpoint, page templates etc if you want to.

Template functions

In order for the templates to work we need to be able to locate the right templates when they are called. With the following code the plugin first look for the called template file in themes/your-theme/woocommerce-plugin-templates/{template-name}, if that isn’t found it will search in your main theme file themes/your-theme/{template-name} and falls back to the original plugin templates in plugins/woocommerce-plugin-templates/templates/{template-name}.

Getting the file

The code above locates and return the path to an existing and valid path that can be loaded and included on the page. In order to actually get the template file there is a extra function. The following code can be used directly in the shortcode function to load the files.

This code will use the wcpt_locate_template() function to find and return the path to a valid template file, when no valid template file is found and the template file doesn’t exist in the plugins’ template folder, which should never occur, a error will be displayed.

Add a shortcode

Adding a shortcode for this example is quite easy, I’ve used the following code to create the shortcode and display out the template file contents on the page.

Currently the template file is still empty, so it will not display anything on the page. If something went wrong with any part of the code or you mis-typed the template file name you will see a error on the page where you added the [redeem_gift_card] shortcode (given that you enabled WP_DEBUG).

I included the following code in my plugins/woocommerce-plugin-templates/redeem-gift-card.php, but let your own imagination go wild here.

A good tip I want to give you is to include a header in the template files with information about the template file, when it was last modified etc. As people will be using your template files, they also need to update these if you are updating them. Therefore it is important to keep track of this and always make notes in your plugin changelog.

woocommerce-pugin-template-redeem-gift-card

Copying the template file to your theme

You are now able to create a template folder called woocommerce-plugin-templates in your theme folder and create the redeem-gift-card.php file in there. That will immediately override the template file located in the plugin itself.

Here’s how my theme override looks like;

woocommerce-template-theme-override

Bonus: Override WP template files with yours

If you’re adding a custom post type in your plugin for example, and want to include the template files in your plugin as they need specific information you can override the template files WordPress wants to load. In order to do so you can use the following code to override the post and page templates (I know, this isn’t a CPT, but its good for the example).

This will override ANY post and page with the contents of the post-override.php and page-override.php files if they exist in the templates folder. For the pages/posts it doesn’t make much sense to override, but as mentioned, this can be very useful for templates for Custom Post Types.

Closing words

You can now get started and add your own templates to your plugins. Don’t forget to make a documentation page about it so your end-users will actually know that its possible 😉 Would be a shame if all the hard work was for nothing!

You can find the full plugin demo plugin here: https://gist.github.com/JeroenSormani/181b8c8a1e5ae6ab8d12 (you still have to create the template folder + files yourself).

I would love to hear from you if this was useful in any way, have feedback, missing something that you’d love to see or just a Thank you 🙂

  • Jeroen Sormani

    I'm a professional WordPress plugin developer on a mission to create the best plugins for my clients. I'm specialised in developing general WordPress, WooCommerce and Easy Digital Downloads plugins.

    Interested in talking about a WordPress project? Get in touch!

    Follow me on Twitter
  • 12 thoughts on “How to add template files in your plugin

    Manish Gajjar April 2, 2016 at 8:52 am

    Thank you so much for sharing this information. I was trying to find out proper way for implementing template features in my plugin.

    jeroen April 3, 2016 at 12:46 am

    Glad to hear you found it useful 🙂

    Manish Gajjar April 5, 2016 at 9:14 am

    I am working on wordpress themes development from approx 2 years. Generally custom coding I used inside theme. So from now i am starting to create plugins for custom codes… 🙂

    waone April 18, 2016 at 11:02 am

    This is exactly what im looking for thankyu so much

    Chris Matthias June 1, 2016 at 9:50 pm

    Thank you for this writeup. I searched “wordpress plugin template files” and this post came up and it’s exactly what I was looking for. Sure beats looking through woocommerce and other plugins to see how they do it. Appreesh!

    jeroen June 2, 2016 at 6:47 pm

    Glad it helped you Chris 🙂

    Joel December 14, 2016 at 3:48 pm

    Very helpful guide Jeroen thanks for sharing.

    Krupa January 27, 2017 at 8:19 am

    I am trying to overwrite my plugin template file with new file I created in my child theme folder. This function below returns empty string.
    // Search template file in theme folder.
    $template = locate_template( array(
    $template_path . $template_name,
    $template_name
    ) );
    Any idea why its not showing new template file I have created in child theme folder?

    Jeroen January 27, 2017 at 8:58 am

    Hi Krupa,

    It would require some debugging, which I can’t do for you from here. I’d recommend to check the values of both the variables $template and $template_path in there to see where the function is looking for.

    The $template_path is important to have set to the right folder name, thats where its searching for primarily.

    Cheers,
    Jeroen

    Amit Biswas February 7, 2017 at 2:54 pm

    Thank you so much for this code. It is so simple to understand and working in a great way as it should. I have only removed “_doing_it_wrong” as it is a private function and not intended to use in themes or plugins. All is well.

    Thanks again.

    Jonas Lundman July 7, 2017 at 6:17 pm

    Beautiful turtorial. Clean and simple, and it works, copy and paste, thanks for sharing and spend time contributing to the global scope between jobs!

    Steve September 22, 2017 at 11:44 pm

    Thanks for this! Very clear and helpful

    Leave a Reply