Today is great day for myself and for the WordPress community. I’ve been hard at work trying to solve a problem that has plagued theme authors for a long time – how to include or prompt users to automatically download, install and activate required (or necessary) plugins upon theme activation.
Well, now that is completely possible with a new class that I have built on top of a lot of WordPress APIs. With some help from Gary Jones, the TGM_Plugin_Activation class is now available for WordPress theme authors and users everywhere!
Version 2.0 now has an API for theme authors to hook into to use the class, eliminating the need to change the code within the class. Check out the details below!
How It Works
The TGM_Plugin_Activation class works by taking a set a key => value pairs from a multidimensional array and processes them to do one of two things:
- Automatically install a plugin that comes pre-packaged with the theme
- Automatically download the .zip file from the WordPress Plugin Repository and install it
In either case, this new class can handle multiple instances of both, which means that you can include/prompt to download as many plugins as needed!
On theme activation, users are prompted with admin notices that certain plugins are required for the theme. Users can then click the links that take them to a page where forms are prepared for them to submit. If you just follow the instructions on the Github page without removing the default examples, your users would appear on a page that looks like this:
The UI is very familiar and intuitive because it follows suit with the rest of the WordPress admin UI. Users can then hit the submit button that installs the plugin. For plugins that come pre-packaged with the theme, they will see a screen that looks like this:
For plugins that are to be downloaded the WordPress Plugin Repository, they will see a screen that looks like this:
Seen these messages before? You probably have because the TGM_Plugin_Activation class uses the same methods as WordPress itself uses to download, install, upgrade and activate plugins.
How To Include the TGM_Plugin_Activation Class with Your Theme
Take a look at the following code (taken from the example.php file included with the class):
This may seem like a lot of code, but don’t let it scare you. Most of it is commenting to help you understand what each part does and how the API interacts with the class.
First you need to include the class for use within your
functions.php file. This is done by the require_once line. You should amend the path so that it targets wherever you decide to place the class within your theme directory structure.
The crux of the API is the
tgmpa_register() hook and the
tgmpa() function. Your plugin information and configurations are added within a function that is added to the
tgmpa_register hook. There are three variables for you to play with:
$plugins variables is required for you to fill out to include your plugins. The variable takes multiple arrays of arguments for your plugins. The keys ‘name’ and ‘slug’ are required for both pre-packaged and repo plugins. If you plugin is pre-packaged, the ‘source’ key is also required. The ‘required’ key is a boolean that will soon be used to determine whether your plugin is required or simply recommended. You can leave this out for now as it will not be active until a future update.
$theme_text_domain is for localization. You set your own text domain here so that the strings used by the class can be localized along with your other theme text strings.
$config variable allows you to set the theme text domain, the default absolute path to your pre-packaged plugins, the menu slug for the install plugins page, and an array of strings to customize admin notices and other messages to your theme users. Refer to the
example.php file to learn how you can customize these for your theme.
A Look at What’s Inside
This automatic plugin installer class makes use of quite a few of WordPress’ own classes. Specifically, this class uses WP_Filesystem, Plugin_Upgrader, Plugin_Skin_Installer and WP_Error. This class also makes use of the plugins_api function as well for preparation for the plugin install and activation.
Unfortunately, none of these classes have extensive documentation (apart from WP_Error). Otto has a great tutorial on WP_Filesystem which I recommend you read get an understand of how to instantiate it. I will make a tutorial soon on how to use WP_Filesystem is correlation with other WordPress classes so you too can learn how to make applications like this one.
Questions? Comments? I’d love to have them! Please post any bugs you find or any questions that may arise when using this class because I would love to work them out. I believe this class has some great potential within the WordPress community, so please make sure you let everyone know about it!