One of the best ways to take your short codes to the next level and make them more developer friendly is to provide template files that can be copied to a theme folder and then modified to suit the needs of each individual user.

Last year I wrote about creating a template file loader in plugins and we’re going to work off of that tutorial for this post. If you haven’t read it, or you need a refresher, I’d suggest you read that post before continuing here.

A template file loader is what we use to describe the functions and/or classes responsible for loading HTML markup from a template file that can be easily modified by creating a copy of the file and placing it in a specific location, such as a folder in the currently active theme.

The concept of a template loader is pretty simple:

1. Determine the name of the file to be loaded
2. Determine the locations to look for the file and the order in which each should be searched
3. Search each location for the file
4. Load the file and stop searching as soon as it is found
5. Fall back to some default template if the requested file is never found

For this tutorial, we will use the template loading class written by Gary Jones.

In order to maintain continuity, we are going to enhance the box short code we wrote in the previous part and add support for template files to it. Right now, our short code looks like this:

Adding a template file to this short code is relatively simple. First we will copy Gary’s template loader class into a folder called includes in our plugin folder and make a few minor changes. Our version looks like this:

We simply changed a few constants and properties to match up with our plugin.

Second, we need to create another folder in our plugin called templates. This will hold our template files. In this folder, create a blank file called box.php. This will hold the HTML markup of our box short code.

Third, at the top of our plugin, we need to define a constant for the plugin’s directory path and also load our template loader class:

Fourth, we need to update our short code function to call the template file. This is pretty simple and just involves instantiating our template class and calling the get_template_part() method:

You should notice a few things.

1. We are using an output buffer. This is because short codes must return their content, not ouput, and loading the template file would normally cause the contents of the file to be output to the screen.

2. We have setup a global variable called $sc101_atts. This is because we need the attributes of our short code to be available in the template file. Without a global, they would not be accessible.

3. I added $content to the $atts so that it is accessible via the global.

We can now move the HTML of our box short code into the template file, templates/box.php:

That’s it! Our short code now supports template files. By default, the file in templates/ will be used, but if a user wanted to, they could create a folder in the currently active theme called sc-101 and then copy the box.php template file to that folder. Any changes made to the theme version will be reflected in the rendered output. One of the huge advantages to this technique is that users can now customize the template files without sacrificing the ability to upgrade the plugin when a new version is released.

A complete version of the plugin is available to download below.

Download Plugin