Including a WordPress Page Template in a Plugin

Note that this plugin is just a working proof-of-concept. Do not use this in a production environment.

One of the challenges of working with templates within the context of WordPress plugin development is that there’s no easy way to bundle templates with your plugin and register them with WordPress.

Template are usually relegated to theme development. And rightly so, correct?

After all, page templates are used to provide layout and presentation which is precisely what themes are meant to provide.

But if you’re working on a larger, more complex plugin that introduces custom post types, page templates, and other advanced functionality then there may be a use case in which bundling templates with your plugin is necessary.

I’ve hit up against this exact issue in a recent project, so I thought I’d share the basics of how I solved the problem, and then provide an example plugin to make the process of registering page templates with WordPress themes a bit easier.

On The “Page Template in Plugin” Discussion

I’ve shared this before, but I generally believe that themes should be dedicated to providing presentation and layouts for data, and plugins should be responsible for introducing functionality into WordPress.

The thing is, the lines can get blurred (and often are). Personally, I think that we – as designers and/or developers – blur the lines more than we should, and that’s another post for another time, but there are times where a plugin may need to include a page template, or a theme may need to introduce some custom functionality.

Thanks to things such as the Settings API, it’s relatively easy for themes to introduce functionality, but it’s not as easy for plugins to introduce presentation functionality.

Case in point: It’s not easy to include a page template with your plugin and register it with WordPress.

There has been a fair amount of discussion about this on the web, and even some relatively complex solutions that can be achieved at the code level.

Usually, I’m all for programmers using whatever solution solves their problem (so long as it’s not a complete abomination of code :), so I thought I’d share – and open source – an example plugin for how I’ve gone about solving this problem.

The Page Template Example Plugin

The Page Template Example plugin is an extremely simple plugin used for demonstration that distills one strategy for including templates with your plugins and registering them with WordPress.

Straight from the README:

An example WordPress plugin used to show how to include templates with your plugins and programmatically add them to the active theme.

The way it works is quite simple:

The template is included with the plugin

When the plugin is activated, a copy of the template is written to the active theme’s directory

When the plugin is deactivated, the template is removed from the active theme’s directory

Technically, this works by basically creating an empty file in the active theme’s directory, reading the contents of the template in the plugin, then writing it to the file that was created upon plugin activation.

A Word of Caution

This plugin is meant for demonstration purposes only which is why I’ve tagged it as 0.1. Think of it as a proof of concept.

Sure, it can be made more robust with enhanced error handling and functionality and I’d love to see a few of you create some pull requests, but until then I recommend avoiding using this plugin in production environments.

If anything, use it as a starting point off of which to build more advanced functionality.

Known Issues

To be clear, there are known issues that I cover in the plugin’s README. Ultimately, I’d love to see these issues added or resolved in a future version of the plugin.

If I have time to continue working on this, I will; however, if you have time, feel free to add your commits as well.

Anyway, the known issues are:

If the user changes a theme, the plugin does not move the template to the new theme’s directory.

There’s practically no error handling for the file operations.

If a template with the same file name already exists, there’s no notification or error handling in this case so the user has no idea that the bundled template was not activsated.

…and more to be discovered.

Again, this is more-or-less a proof of concept as showing one way in which you can add templates to your plugin and have WordPress easily recognize them.

Add To It!

Since this plugin is nothing but a simple, working proof-of-concept, feel free to add to it – I’m open to any and all improvements that you guys want to add.

The purpose of getting an 0.1 out on GitHub was to show that it is possible to include templates with plugins and register them with WordPress without having to introduce any sort of hacky-work around.

Secondly, there are far more talented WordPress programmers that I’m hoping will initiate a few pull requests so that the plugin reaps the benefits, and so that I – anyone else who reads the blog or the plugin – learns from them.

So have at it :).