Add page templates to WordPress with a plugin

Have you ever wanted to create your own page templates, but haven't had access to the theme itself? I, as a WordPress plugin author, have found this problem to be particularly annoying when developing my plugins. Luckily the solution is pretty simple! I'll quickly walk you through the few lines of code you'll need to dynamically create WordPress Page Templates directly through PHP.

The inspiration for this article and the genius behind the code solution comes from Tom mcfarlin: I'm using my edited version of your original code, which you can find on your GitHub. I have saved your comments (as well as adding some of my own) as I find it very helpful in explaining what is going on. I couldn't have said it better myself!

You can find the code in its entirety and an example plugin at the end of this post.

Should we start?

THE CODE

We will create our PHP function using a PHP class. For those of you who are not well acquainted with PHP classes, a class is defined as an object that contains a collection of functions and variables that work together. Review the Introduction to PHP.net for more details on syntax and theory.

Our container will only need 3 variables:

1. The Slug plugin: This is simply used as a unique identifier for the plugin.
2. Class instance: Since we are adding an instance of this class to the WordPress header, we better store it.
3. Template matrix: As you can probably guess, this is an array that contains the names and titles of the templates.

Here they are in code:

class PageTemplater {/ ** * A Unique Identifier * / protected $plugin_slug; / ** * A reference to an instance of this class. * / private static $instance; / ** * The array of templates that this plugin tracks. * / protected $templates;

Get class instance

As I said previously, we will add an instance of our class to the WordPress header using the Add filter () function. Therefore, we will need a method that returns (or creates) this instance to us.

For this, we will need a simple method, which will be called 'get_instance'. Check it out below;

/ ** * Returns an instance of this class. * / public static function get_instance () {if (null == self :: $instance) {self :: $instance = new PageTemplater (); } return self :: $instance; }

This will be the method called when our class is added to the WordPress header using 'add_action ()'.

WordPress filters

Now that we have solved the 'get_instance' method, we need to clarify what happens when an instance is actually created.

We will use the built-in WordPress software. Add filter () function to add an instance of our class at key points along the WordPress initialization timeline. With this method, we will insert the data from our page templates into relevant spaces, such as telling WordPress which file to use as a template when the page is called and the title to display in the Page Editor drop-down menu.

For this, we need to use the '__build' method (this will be executed when the class is instantiated).

/ ** * Initializes the plugin by setting filters and administration functions. * / private function __construct () {$this-> templates = array (); // Add a filter to the attributes metabox to inject template into the cache. if (version_compare (floatval (get_bloginfo ('version')), '4.7', '<')) {// 4.6 and older add_filter ('page_attributes_dropdown_pages_args', array ($this, 'register_project_templates')); } else {// Add a filter to the wp 4.7 version attributes metabox add_filter ('theme_page_templates', array ($this, 'add_new_template')); } // Add a filter to the save post to inject out template into the page cache add_filter ('wp_insert_post_data', array ($this, 'register_project_templates')); // Add a filter to the template include to determine if the page has our // template assigned and return it's path add_filter ('template_include', array ($this, 'view_project_template')); // Add your templates to this array. $this-> templates = array ('goodtobebad-template.php' => 'It's Good to Be Bad',); }

Here 4 different things are happening (ignoring '$ this-> templates = array ();', which is just preparing the variable for use);

1. Lines 9 - 13: This filter adds 'register_project_templates' to the 'page_attributes_dropdown_pages_args' hook. This is filling the WordPress cache with our new templates, 'fooling' WordPress into believing that the page template files actually exist in the templates directory. This adds the page templates to the drop-down list in the page attributes meta box in the page editor.
2. Lines 16 - 20: Here we are doing essentially the same as the code block above, except this time we are adding our page template (if selected) to the save post data at the same time.
3. Lines 23-28: This filter adds the 'template_include' to the 'view_project_template' hook. This is a very important function; this tells WordPress where your page template file actually is. WordPress will use the path provided by it to render the final page.
4. Lines 31 - 34: Although this is simple, it is very important. This is where you specify the page templates you want to add and the relative path to the file where the page template file is located (for example 'something.php'). I have included an example (to be used in the example plugin). See below for a general example:

$this-> templates = array ('FILE_PATH_AND_NAME' => 'TEMPLATE_TITLE', 'awesome-template.php' => 'Awesome', 'templates / organized-template.php' => 'Organized',);

(Eat, sleep) Code, repeat as needed.

register_project_templates ()

I have alluded to this method previously; let's see what it actually does.

Basically, the purpose of this method is to manipulate the WordPress cache, inserting the relevant data about our page templates in the right places. Take a look at the code first and then I'll explain.

public function register_project_templates ($atts) {// Create the key used for the themes cache $cache_key = 'page_templates-'. md5 (get_theme_root (). '/'. get_stylesheet ()); // Retrieve the cache list. // If it doesn't exist, or it's empty prepare an array $templates = wp_get_theme () -> get_page_templates (); if (empty ($templates)) {$templates = array (); } // New cache, therefore remove the old one wp_cache_delete ($cache_key, 'themes'); // Now add our template to the list of templates by merging our templates // with the existing templates array from the cache. $templates = array_merge ($templates, $this-> templates); // Add the modified cache to allow WordPress to pick it up for listing // available templates wp_cache_add ($cache_key, $templates, 'themes', 1800); return $atts; }

At that very moment. Line 4 is the first place to look. As you may have guessed, we are generating a 'cache key'. This will be used as a unique identifier for our page template data. Using the md5 () function simply creates a unique string identifier to avoid clashes.

Next, on line 8, we are looking for and retrieving the page template cache (if it already exists) - this will return an array of paths and titles. On lines 9-11, we check to see if there were any results from the cache query. If so, great. If not, create a local array to hold the data that we will cache.

The next step is crucial. On line 14 we Erase the existing page template cache. Don't worry, no data is lost, it is stored in the $ templates variable.

On line 18 we merge the existing page template cache with our new entries, and on line 22 we reinsert the entire page template cache into the WordPress system.

Simple!

view_project_template ()

We are now in our final method; This is where we tell WordPress where the actual page template file is.

/ ** * Checks if the template is assigned to the page * / public function view_project_template ($template) {// Get global post global $post; // Return template if post is empty if (! $post) {return $template; } // Return default template if we don't have a custom one defined if (! Isset ($this-> templates [get_post_meta ($post-> ID, '_wp_page_template', true)])) {return $template; } $file = plugin_dir_path (__ FILE__). get_post_meta ($post-> ID, '_wp_page_template', true); // Just to be safe, we check if the file exist first if (file_exists ($file)) {return $file; } else {echo $file; } // Return template return $template; }

Okay so this method will be compared to the $ post global variable (line 6). Checks if a page template ('_wp_page_template') has been configured for the post (which means it must be a page). If not, it doesn't matter: non-pages cannot have page templates.

Line 16 specifies the location of the page template file. As I have previously set, check the specified page template file in your plugin root directory. (Regardless, this can be easily changed - see below).

// Just changing the page template path // WordPress will now look for page templates in the subfolder 'templates', // instead of the root $file = plugin_dir_path (__ FILE__). 'templates /' .get_post_meta ($post-> ID, '_wp_page_template', true);

After this, on lines 21-24, we just have a bit of validation that checks if the file actually exists. If so, great! If not, oops… You will most likely get a PHP error message if WordPress cannot find the template file, or even a blank screen. If any of these symptoms sound familiar to you, simply check the template file path by printing the $ file variable to the screen.

If you plan to use this code commercially (which is free to do, my version of the code comes unlicensed so you can do whatever you want with it), I really recommend spending some time on error handling to get the most out of it. reliability.

That's that. With our class completed, there is only one thing left to do: add it to the WordPress header.

add_action ('plugins_loaded', array ('PageTemplater', 'get_instance'));

Congratulations if you made it! I hope you have found what I have to say useful and will benefit from it in the future.

FULL CODE

Below is the complete plugin code for easy copy and paste.

 templates = array (); // Add a filter to the attributes metabox to inject template into the cache. if (version_compare (floatval (get_bloginfo ('version')), '4.7', '<')) {// 4.6 and older add_filter ('page_attributes_dropdown_pages_args', array ($this, 'register_project_templates')); } else {// Add a filter to the wp 4.7 version attributes metabox add_filter ('theme_page_templates', array ($this, 'add_new_template')); } // Add a filter to the save post to inject out template into the page cache add_filter ('wp_insert_post_data', array ($this, 'register_project_templates')); // Add a filter to the template include to determine if the page has our // template assigned and return it's path add_filter ('template_include', array ($this, 'view_project_template')); // Add your templates to this array. $this-> templates = array ('goodtobebad-template.php' => 'It's Good to Be Bad',); } / ** * Adds our template to the page dropdown for v4.7 + * * / public function add_new_template ($posts_templates) {$posts_templates = array_merge ($posts_templates, $this-> templates); return $posts_templates; } / ** * Adds our template to the pages cache in order to trick WordPress * into thinking the template file exists where it doens't really exist. * / public function register_project_templates ($atts) {// Create the key used for the themes cache $cache_key = 'page_templates-'. md5 (get_theme_root (). '/'. get_stylesheet ()); // Retrieve the cache list. // If it doesn't exist, or it's empty prepare an array $templates = wp_get_theme () -> get_page_templates (); if (empty ($templates)) {$templates = array (); } // New cache, therefore remove the old one wp_cache_delete ($cache_key, 'themes'); // Now add our template to the list of templates by merging our templates // with the existing templates array from the cache. $templates = array_merge ($templates, $this-> templates); // Add the modified cache to allow WordPress to pick it up for listing // available templates wp_cache_add ($cache_key, $templates, 'themes', 1800); return $atts; } / ** * Checks if the template is assigned to the page * / public function view_project_template ($template) {// Get global post global $post; // Return template if post is empty if (! $post) {return $template; } // Return default template if we don't have a custom one defined if (! Isset ($this-> templates [get_post_meta ($post-> ID, '_wp_page_template', true)])) {return $template; } $file = plugin_dir_path (__FILE__). get_post_meta ($post-> ID, '_wp_page_template', true); // Just to be safe, we check if the file exist first if (file_exists ($file)) {return $file; } else {echo $file; } // Return template return $template; }} add_action ('plugins_loaded', array ('PageTemplater', 'get_instance'));

THE PLUGIN

At the same time you can download the full code as a plugin on Github.

EDITOR'S CLOSE-UP

Here's a close-up of the plugin in action. See the page template added in Page Attributes?