Tips For Supporting Plugins In WordPress Themes

I’ve been playing around with WordPress themes for about six years now and I can say with confidence that the way themes are built has changed dramatically.

When I first got involved back in 2009, it was all about theme frameworks. They were fairly new to the scene and they introduced a level of flexibility we had not yet grown to expect in the WordPress space. When you installed a fresh copy of a framework, it was all about the possibilities.

In my opinion, things have changed. An environment of endless possibility is great but it introduces a form of chaos that can only be settled with specific directions of focus. That’s where I believe we are today. Focused themes are running the show because they promote intent rather than possibility.

There are a number of ways you can build a theme with intent. Design style is one of the more basic approaches. Theme functionality really sets intent in stone, though, and that’s what I want to talk about in this article.

Integrating your themes with powerful WordPress plugins put them in a category of their own and eliminates the guessing game that comes along with ambiguity.

What does it mean to integrate themes with plugins?

Let’s get something out of the way right off the bat. Creating a theme that is designed to work only when a certain plugin is installed is not a good move. Completely ditching flexibility for intent is no better than just flexibility. It’s probably worse.

Make sure your themes work with the plugin you’re focusing on and without. Just trust me on this one.

That said, let’s go over what it means to integrate your themes with plugins.

  • Well-built plugins may have features that can only be taken advantage of at the theme level, even though the plugin functions just fine when those features are ignored. Your focused theme should take advantage of those features.
  • Well-built plugins take themes into consideration that are not focused on their functionality. So instead of requiring accommodations, they will make use of basic theme structure and functionality to operate as expected. Your focused theme should not force the plugin to do that.
  • Well-built plugins use actions, filters, and more to promote flexibility and extensibility. Your focused theme will put these tools to use to make the plugin more powerful than it was before you came along.
  • Your focused theme will do all of the above (and more) safely. More on that shortly.

When you build a theme with intent, it’s about much more than how the theme looks. It’s about how it works. It’s about how the end user will interact with it. It’s about the theme’s function as a tool to do a certain job, not just look pretty.

Let’s get down to business.

Look before you cross the street.

Life 101, right? Stepping out into the road without looking both ways can result in a fatal error. That’s a bad joke. It’s good advice, though. For those of you who didn’t realize it was a joke, I’ll explain.

When you build a theme the way I’ve described above, chances are you’re going to reference the supported plugin(s) in your code. Jumping from your theme code to a plugin’s code is like crossing the street. Stay with me here.

When you prepare to cross that street reference that plugin code, you need to be aware of certain things first. For example… ummm… is the plugin installed and activated?

Remember that users do not have to use your theme the way you expect them to. They can do whatever they want with it. While you don’t have to take every decision the user makes into consideration, there are some things that you just need to look out for. This is one of those things.

There are a few different ways you can check for dependencies before referencing them. I’ll give you a examples.

class_exists()

Reference – http://php.net/manual/en/function.class-exists.php

Straight from php.net, this function checks whether or not the given class has been defined. Oftentimes a WordPress plugin’s main plugin file will use a PHP class to set everything up. This class is the starting for the plugin’s functionality meaning if it does not exist, the plugin is most likely not activated.

That said, using the aforementioned function will tell your theme whether or not the plugin is activated and allow you to build logic based on that information. Here’s the code in action:

if ( class_exists( 'The_Plugin_Class' ) ) {
    // do theme things that depend on the plugin being activated
}

Simple. Only do things that are specific to the plugin if the plugin is activated. Not doing this can result in a fatal error.

function_exists()

Reference – http://php.net/manual/en/function.function-exists.php

Straight from php.net, this function checks the list of defined functions, both built-in (internal) and user-defined, for function_name.

You’d use this function just the same as class_exists() but you’d need to be a little more careful depending on how the plugin is built. Before, I automatically assumed the plugin was written with object oriented programming and therefore used classes. I could have been wrong in which case, it probably use procedural programming. So everything would be set up using functions, not classes. If that’s the case, use function_exists() to build your login instead.

if ( function_exists( 'plugin_function_name' ) ) {
    // do theme things that depend on the plugin being activated
}

Just make sure you take a good look at the plugin before deciding which function to use. Write your conditional logic to check for the plugin’s presence as early as possible.

is_plugin_active()

Reference – http://codex.wordpress.org/Function_Reference/is_plugin_active

Straight from the WordPress Codex, this function checks if a plugin is activated.

Stop looking at me like that. I know this function seems like it would make a lot more sense to use but just hear me out, geez.

The function uses WordPress itself to check and see if a certain plugin is activated. How the code must be written depends on where it’s being used (see the reference link for more details) but a basic example would look like this:

include_once( ABSPATH . 'wp-admin/includes/plugin.php' );
if ( is_plugin_active( 'plugin-directory/plugin-file.php' ) ) {
    // do theme things that depend on the plugin being activated
}

Notice on the second line of that code, the is_plugin_active() function looks for a specific plugin folder name and main plugin file name. You have got to be careful using this. Changing the name of a plugin folder alone will not stop the plugin from working. It will, however, see to it that the above conditional logic is not met. That’s no good.

You may be wondering why anyone would change the name of a plugin folder. Well, again, people can do what they want. But this is still something to consider. Have you ever downloaded a plugin straight from a GitHub repo? If so, what was the name of the folder?

I’m willing to bet it was plugin-name-{branch}. Am I right or am I right? Think about it. Use is_plugin_active() carefully and only when you have to.

Template Files for Plugins

First of all, this will not apply to all theme/plugin integrations. Not every plugin needs to worry about template files. That said, the underlying concept is still important. So read this section anyway and take from it what you see fit.

Template files are an important part of theming. If you’ve ever built a theme before, you know all about that. If not, you should be here. From here on out, I’m going to assume you know what template files are.

You should already be familiar with templates like single.php or perhaphs archive.php. But what about single-{post_type}.php? When’s the last time you used that one? Actually… what is it?

Take a few seconds to read the WordPress Template Hierarchy codex page. There, you will learn how WordPress decides which theme template file should be used when serving up content to your browser.

Did you know that plugins have the ability to use template files that have a higher priority than the default files, like single.php? Let me give you a real-world example.

Easy Digital Downloads

Easy Digital Downloads (EDD) is an e-commerce plugin for WordPress that specializes in digital download stores. Some time ago, I wrote about how to integrate your themes specifically with EDD. In that tutorial, I talked about the single-download.php file.

EDD uses a Custom Post Type (CPT) to create new “download” entries. Creating a new Download is just like creating a new Post or Page in your dashboard. Likewise, viewing a Download on the front-end of your website is just like viewing a Post or Page on the front-end.

By default, CPTs behave just like Posts. So how does WordPress know which template to use when serving up the content of a single CPT? That’s where the template hierarchy comes in.

Looking back at the hierarchy for “single” template files, notice that single-{post_type}.php has a higher priority than single.php. Understanding that, and the fact that {post_type} represents the registered name of the CPT, we can conclude that WordPress will search for a file called single-download.php before it “falls back” to single.php.

As mentioned before, a well-built plugin understands that not every thing will have a single-download.php file in it. Why should it? So it will be designed to serve its CPT content through the single.php template.

But you, the theme developer, should know if the plugin is prepared to use its own template. If it is, put it to use! This is part of building a theme with intent. Single post templates may have things like byline information displayed on the page. Do you need that on your CPT templates? Maybe. Maybe not. Can you use conditional logic to determine whether or not something shows? Sure. Is that scalable? Not at all. So understand how the plugin is built will tell you everything you need to know about how to build your theme with intent.

Page Templates

Another part of the template system you should consider is custom page templates. When you create a new WordPress page, you will see this meta box on the edit screen:

page-attributes

The “Template” select menu will allow you to render that page using the template of your choice, assuming one exists. As a theme developer, you can create as many Page Templates as you’d like. They can be really useful for creating predefined structures for certain types of content, so users love them.

Chances are, you’re going to create a Page Template or two for the plugin you’re integrating into your theme. Keeping with the Easy Digital Downloads example, I like to create Page Templates for a store front, a members/customers area, and sometimes more. That said, I do not want those options to appear in the Template select menu if EDD is not activated. Duh, right?

There’s a problem, though. Page Templates are not created in code. Instead, making a Page Template means creating a file that sits in your theme. So how do you wrap conditional logic around a template file? You can’t. That’s how.

Instead, you’d need to filter the Template select menu on the Edit Page screen to only show certain Page Templates if said plugin is activated. Understanding what I said before about checking before referencing plugin code, here’s an example of how you would filter that list:

function bwpy_page_template_conditions( $page_templates ) {
	if ( ! class_exists( 'The_Plugin_Class' ) ) {
		unset( $page_templates['page_templates/template-one.php'] );
		unset( $page_templates['page_templates/template-two.php'] );
	}
	return $page_templates;
}
add_filter( 'theme_page_templates', 'bwpy_page_template_conditions' );

That code simple says, “if this specific plugin is not activated, remove these two Page Templates from the list of available Templates on the Edit Page screen.”

Easy enough, right? I’m guilty of not doing this with many of my themes in the past. Soon, I will go back and fix that. Make sure you’re doing it moving forward. While it doesn’t hurt anything to leave them there (because the template files still exist within your theme), it’s misleading and avoidable.

Overall, template files are a case by case thing. Not only will there be cases where you don’t have to consider them, 9 times out of 10, ignoring them completely will not break anything. Just try to care, you know?

Final Tips and Takeaway

Of course, I can’t sit here and tell you how to integrate every theme with every plugin. But I can give you some things to think about and a couple of rules to follow in order to avoid errors.

From here, it’s up to you to consider the fine details of the support plugins when building your theme. I have a few final tips that may help:

Maintain Flexibility

Design your themes to work without the plugin(s) you focused on. Some users will choose your theme based solely on looks. Let them enjoy the design alone if that’s what they’d like to do.

Think Ahead

Some plugins will allow you to override files from the theme. EDD, for example, even let’s you override CSS files (and much more). Only do this when necessary.

While overriding plugin files from your theme seems really easy to do, understand that the plugins are designed to use their own files only when you haven’t copied them into your theme. That means once you’ve copied them over, the plugin files are no longer in use.

What happens when there’s a key change made in one of the plugin files like a bug fix? Unless you’ve fixed it yourself in said file, you’ll still have that bug while the plugin has been updated to fix it. If you’re going to override plugin files, make sure you monitor the changelog for the plugin.

Wrap Your Customizer Settings

Does your theme use the Theme Customizer? If not, have a look at how to set it up. If so, and you’ve added settings related to the plugin, be sure to wrap those settings in the conditional logic we talked about before. There’s no point in showing settings that can’t be used. The same applies for actual settings pages and other integrations you’ve created through the WordPress dashboard for the support plugin(s).

Go All In

I’m a little “iffy” on this one because I haven’t always done it. But it’s something that I believe in going forward.

Like I said at the beginning of this article, the WordPress theme space has changed over the years. It’s not all about possibilities anymore. That era has produced so many outstanding themes that end users have grown to expect the end result rather than the process used to get there. That means they no longer care if the super flexible framework was used to create the recipe theme. They just want the recipe theme.

So if you’re the theme developer who’s going to build the recipe theme, go all in. Study the needs of the user and the functionality of the plugins they will use. Design your theme (both looks and functionality) to get the absolute most out of the tools they will use.

That approach will earn more than a theme of possibilities every time.

Happy theming, folks. 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *

*