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
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!
Thanks for sharing Tom.
Does WooCommerce plugin does something like this?
Honestly, I’m not sure.
I’ve not dug into any of their plugins to see if they do or not.
@Harish:
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:
http://codex.wordpress.org/Plugin_API/Action_Reference/template_redirect
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:
yourtheme/slug-name.php
and
yourtheme/woocommerce/slug-name.php
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.
Sorry for my last comment. @Stephen thank you for explaining and sharing in detail.
no wonder we come to your blog so often. Thank you for going out of your way to explain this. Thanks mate.
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?
Cheers
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() );
to:
$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.
Cheers
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’ );
to:
$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?
Cheers
Cheers
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.
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?
I’m not terribly familiar with bbPress’ code base, so I won’t be of much help with this. :/