Software Engineering in WordPress and Musings on the Deep Life

How To Include a Page Template in a WordPress Plugin

Last March, I wrote a post on How To Include a Page Template in a WordPress Plugin. The post and the associated code was a proof-of-concept that was never intended to be used in production environments.

But since then, I’ve received a few pull requests and have implemented some additional changes that have brought this plugin up to a stable `1.0.0` that I believe is capable of being used in a more stable setting.

Include a Page Template in WordPress Plugin

Page Template Example

You can checkout the project on GitHub, but the point of the project is simple: Provide a way for developers to easily include templates to work with themes within the context of their plugins.

Page Template Example is a plugin that shows one strategy for how to do that.

Here’s a general rundown of how the plugin works:

  • Add your templates to the templates directory
  • Define the template location in an associative array in the plugin (and covered in the `README`).

Easy enough, right?

What’s Included?

With the demo, you get the following:

  • A copy of the plugin, fully documented and internationalized
  • A `README` that walks you through how to get started
  • A `ChangeLog` for those that are curious about all of the changes
  • Two example templates used to show how to put the plugin to work

As is the case with most of the open source projects, I gotta give thanks to all of those who contributed to this release.

And, as usual, for those of you who discover bugs or are looking to add more functionality to the plugin, don’t hesitate to open an issue or submit a pull request!


  1. Harish

    Thanks for sharing Tom.
    Does WooCommerce plugin does something like this?

    • Tom McFarlin

      Honestly, I’m not sure.

      I’ve not dug into any of their plugins to see if they do or not.

  2. Stephen Sherrard


    I’ve done a LOT of sorting through Woocommerce code to do some custom extensions. It’s a HUGE plugin, so it’s often hard to find what you are looking for, but they do a decent job of commenting everything and providing lots of action/filter hooks.

    They tap into the template_redirect hook:

    They have it set up to check a couple of places for default/custom templates first (either from the theme or the user), and then if a specific template is not found there, they redirect to their own template which is included in a directory inside of their own plugin. They don’t try to write a template into the themes directory.

    You can find their functions that search for and load the proper template parts in the woocommerce-core-functions.php file starting around line 600.

    When they search for a template, they first search in:

    If it’s not found in any of those two, then they load the template from their own template directory inside of the woocommerce plugin folder.

    • Harish

      Sorry for my last comment. @Stephen thank you for explaining and sharing in detail.

  3. Harish

    no wonder we come to your blog so often. Thank you for going out of your way to explain this. Thanks mate.

  4. Josh

    Hi Tom

    This is a great example and I found it very useful, thanks for sharing it.

    I noticed after activating the plugin that it is loading the plugins page templates instead of the page templates of the active theme, rather than loading them in addition to the active themes templates.

    Has anyone else noticed this. Is this a known bug or limitation?


    • Josh

      Update: Both the theme’s and plugin’s page templates are showing up fine when a child theme is active but not when the parent theme is active. I tried changing:

      $cache_key = ‘page_templates-‘ . md5( get_theme_root() . ‘/’ . get_stylesheet() );
      $cache_key = ‘page_templates-‘ . md5( get_theme_root() . ‘/’ . get_template_directory() );

      That makes the theme’s page templates to show up fine but unfortunately that also stops the plugin’s templates from showing for some reason.


      • Josh

        Update: I was fortunate enough to get some assistance from an experienced coder who came up with this fix that gets everything working with both parent and child themes. Changing:
        $templates = wp_cache_get( $cache_key, ‘themes’ );
        $templates = wp_get_theme()->get_page_templates();

        With this new technique of using the cache as a way to load the template instead of uploading it to the theme directory like the old version, is there any risk that the template will disappear when the cache expires or is this a solid technique?



        • Tom McFarlin

          Ah, thanks for the follow-up on this.

          I’ll be sure to add this to the next version of the plugin. I’m actually looking to release an official plugin about this at some point, but right now the example that you have is the best working example.

          Anyway, I don’t think there’s any risk that the template will disappear because if a cache hit is missed, then it should load it from disk back into the cache.

  5. rashid

    Using bbPress recently shows it includes couple of page templates like we do in our themes, I tried to read the code but cant seem to find how they included page templates in the backend?

    Anybody have a thought?

    • Tom McFarlin

      I’m not terribly familiar with bbPress’ code base, so I won’t be of much help with this. :/

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

© 2023 Tom McFarlin

Theme by Anders NorenUp ↑