Themes aren't meant to be functional, but as theme developers, we mostly need to include some features to make our theme a bit better and a function, you know, functional. 

In this tutorial, we're going to have a glance at the term "plugin territory" and learn to use a fantastic tool written by Thomas Griffin: the TGM Plugin Activation library.

Theme Functionality: Invading Plugin Territory

Themes are meant to change the design of your WordPress website. Ideally, it should be visual. But in this golden age of WordPress, theme developers often include functional features in their themes in order to stay competitive in the market. This it was supposed to be, but it is.

This is the invasion of the plugin territory. We can define "plugin territory" in simple terms:  Functional parts of code are inside the borders of this territory. Every bit of code that changes the functionality of your website needs to be served as a plugin, if it's not already been served in the WordPress core. 

In one of my previous posts (in the series "Making the Perfect WordPress Theme"), I mentioned the rule of thumb of the "plugin territory":

If the feature is about the visual appearance of the website, it should be in the theme, but if it's about the functionality of a website, it should be included as a separate plugin.

Easy enough, right? 

Although people still tend to hard-code functional bits into their themes, theme directories (like WordPress.org and ThemeForest) are not accepting themes invading the "plugin territory". So, it has become a problem to offer functionality with themes.

Luckily, there is a fairly simple solution and it doesn't go against the "plugin territory" rule.

Introducting the TGM Plugin Activation Library

TGM Plugin Activation is a lightweight library with the purpose of bundling themes with plugins. The idea is simple: When a user installs your theme, it makes the user install plugins from WordPress.org, an external website or the theme folder. Here's what Thomas Griffin, the creator of the library, defines this handy little tool:

TGM Plugin Activation is a PHP library that allows you to easily require or recommend plugins for your WordPress themes (and plugins). It allows your users to install and even automatically activate plugins in singular or bulk fashion using native WordPress classes, functions and interfaces. You can reference pre-packaged plugins, plugins from the WordPress Plugin Repository or even plugins hosted elsewhere on the internet.

This is probably the smartest solution to the "plugin territory invasion" problem. And it's quite easy to apply, too. 

Let's have a look!

Installing TGM Plugin Activation

Installing TGM Plugin Activation is ridiculously easy. Just follow these steps:

• Download the TGM Plugin Activation library from the "Download" section of the page.
• Open the zip file and extract class-tgm-plugin-activation.php into your theme folder (anywhere you like).
• Open your theme's functions.php file and use the require_once() function to, well, require the class file (once) in your theme.
• Create a function to configure TGM Plugin Activation and hook it to tgmpa_register via the add_action() function.
• Done!

It's so easy that you don't even need complicated PHP code in order to require or recommend plugins. Take a look at the code below:

<?php

/**
 * Since I'm already doing a tutorial, I'm not going to include comments to
 * this code, but if you want, you can check out the "example.php" file
 * inside the ZIP you downloaded - it has a very detailed documentation.
 */

require_once dirname( __FILE__ ) . '/class-tgm-plugin-activation.php';

add_action( 'tgmpa_register', 'mytheme_require_plugins' );

function mytheme_require_plugins() {

    $plugins = array( /* The array to install plugins */ );
    $config = array( /* The array to configure TGM Plugin Activation */ );

    tgmpa( $plugins, $config );

}

?>

From now on, you can make your users install new plugins by setting up the $plugins variable in the function you just created. 

Let's see how it's done.

Installing Plugins with TGM Plugin Activation

As you can see from above, the $plugins variable is an array. And to define plugins to install, you need to create arrays within that array (so you can set their own parameters). Sounds hard, but it's not:

<?php

$plugins = array(
	array( /* my first plugin */ ),
	array( /* my second plugin */ ),
	array( /* my third plugin */ ),
	// ...
	array( /* my nth plugin */ )
);

?>

There are a couple of parameters to use:

• name (string, required) - The name of the plugin.
• slug (string, required) - The slug of the plugin (usually its folder's name).
• required (boolean, required) - If it's set to true, your theme will "require" the plugin. If false, the theme will "recommend" it.
• source (string, sometimes required) - The source of the plugin. If it's a WordPress.org plugin, this parameter shouldn't be used; else, it's required.
• version (string, optional) - The minimum version required for the plugin. For example; if the theme user has already installed a required plugin but doesn't have the minimum version number you specified, TGM Plugin Activation warns the user to update it.
• force_activation (boolean, optional) - If set to true, the user will not be able to deactivate the plugin while your theme is active. A bit annoying but it might be necessary in some scenarios.
• force_deactivation (boolean, optional) - If set to true, the plugin will be deactivated once the user switches themes.
• external_url (string, optional) - If set, the name of the plugin will be linked to this address in the plugin requirement notice.

You have three options to make your users install plugins with TGM Plugin Activation: You can require a plugin from the WordPress Plugin Directory, from an external source (like your own server or a CDN), or from your theme folder (like /my-theme/plugins/shortcodes.zip).

Requiring a Plugin From WordPress.org

<?php

$plugins = array(
	array(
		'name'      => 'BuddyPress',
		'slug'      => 'buddypress',
		'required'  => false, // this plugin is recommended
	)
);

?>

Requiring a Plugin From an External Source

<?php

$plugins = array(
	array(
		'name'               => 'My Awesome Plugin',
		'slug'               => 'my-awesome-plugin',
		'source'             => 'http://files.my-website.com/my-awesome-plugin.zip',
		'required'           => true, // this plugin is required
		'external_url'       => 'http://my-website.com/introducing-my-awesome-plugin', // page of my plugin
		'force_deactivation' => true, // deactivate this plugin when the user switches to another theme
	)
);

?>

Requiring a Plugin From the Theme Directory

<?php

$plugins = array(
	array(
		'name'               => 'My Super Sleek Slider',
		'slug'               => 'my-super-sleek-slider',
		'source'             => get_stylesheet_directory() . '/lib/plugins/my-super-sleek-slider.zip', // The "internal" source of the plugin.
		'required'           => true, // this plugin is required
		'version'            => '1.2', // the user must use version 1.2 (or higher) of this plugin
		'force_activation'   => false, // this plugin is going to stay activated unless the user switches to another theme
	)
);

?>

Configuring TGM Plugin Activation

Notice the tgmpa() function with two parameters at the end of our example code? The second parameter is the $config variable which also happens to be an array, just like the $plugins parameter. As the name suggests, you can configure the TGM Plugin Activation library with this array. It also has its own set of options that you need to set:

• id (string) - A unique ID for the TGM Plugin Activation library that you implemented in your theme. This is actually very important: If another plugin also uses TGM Plugin Activation, the different IDs would prevent conflicts.
• default_path (string) - The default absolute path for plugins inside your theme. When you set this, you can just use the name of the ZIP file as the source parameter for your plugin.
• menu (string) - The menu slug for the plugin install page.
• has_notices (boolean) - If set to true, admin notices are shown for required/recommended plugins.
• dismissible (boolean) - If set to true, the user can "dismiss" the notices.
• dismiss_msg (string) - If the dismissable option is set to false, this message will be shown above the admin notice.
• is_automatic (boolean) - If set to true, plugins will be activated after the user agrees to install them.
• message (string) - Optional HTML to display before the plugins table.
• strings (array) - Yet another array that includes the messages to be displayed. You can set them as translatable strings, too. Check out the example.php file to see the full list of message strings.

<?php

$config = array(
	'id'           => 'mytheme-tgmpa', // your unique TGMPA ID
	'default_path' => get_stylesheet_directory() . '/lib/plugins/', // default absolute path
	'menu'         => 'mytheme-install-required-plugins', // menu slug
	'has_notices'  => true, // Show admin notices
	'dismissable'  => false, // the notices are NOT dismissable
	'dismiss_msg'  => 'I really, really need you to install these plugins, okay?', // this message will be output at top of nag
	'is_automatic' => true, // automatically activate plugins after installation
	'message'      => '<!--Hey there.-->', // message to output right before the plugins table
	'strings'      => array(); // The array of message strings that TGM Plugin Activation uses
);

?>

Wrapping Everything Up

As you can see, it's not at all impossible to offer functionality with WordPress themes – you just have to think of the users when they switch from your theme to another. The TGM Plugin Activation Library offers a really clever way to play it by the book.

What do you think about this tool? Have you ever used it, or are you planning to use it in the future? Tell us what you think by commenting below. And if you liked this article, don't forget to share it with your friends!