As WordPress authors in ThemeForest, we like to make our customers happy by providing them with occasional bug fixes and enhancements to our themes. But one key problem for us is how to notify our users when an update is available for download.

In the olden days, we each had to code in our own implementations of a theme update notifier. While there's now a checkbox to enable notifications on item updates in the Envato Marketplaces, users still have to turn it on per item and also perform the theme update manually.

Wouldn't it be better if update notifications were displayed within the WordPress admin itself? And that updates can be performed right away within the admin? Luckily for us, we now have the Envato WordPress Toolkit Plugin and Toolkit Library.

In this series, you'll learn how to integrate these toolkits into your themes.

What We'll Be Covering in This Series

In this tutorial we are going to implement both the Envato WordPress Toolkit Plugin and Library in our theme. When our theme is activated, the user will be asked to install and activate the Toolkit plugin.

Once the plugin is active, our theme will periodically check for updates, and if an update is found, a notification in the admin would be displayed which will direct the user to the plugin to update the theme.

The tutorial is split into two parts:

• Part 1 - Integrating the TGM Plugin Activation class to make the Envato WordPress Toolkit Plugin a requirement when using our theme; and
• Part 2 - Implementing the Envato WordPress Toolkit Library in our theme to allow new theme version checking and updating.

Plugin and Library?

The Envato WordPress Toolkit comes in two forms which have different usage and purpose. So that we don't get confused with the two, here is a comparison:

• Toolkit Plugin - This is a standalone plugin which can be installed by any Envato customer in their WordPress site. When activated, all previously purchased themes as well as theme updates would be available for download directly from the admin.
• Toolkit Library - Code that can be included by authors in their WordPress themes, that enables the theme to use the Envato Marketplace API to check for theme version updates and update itself.

1. Including the Required Files

We'll first need to include some files in our project. We're going to bundle the Toolkit Plugin with our theme, and we're going to use TGM Plugin Activation to install and activate the Toolkit.

1. Download TGM Plugin Activation and place the main class script into the inc folder in your theme. The path should be: mytheme/inc/class-tgm-plugin-activation.php
2. Next, download the Envato WordPress Toolkit Plugin ZIP file and place it into a new folder in your theme called plugins. The path should be: mytheme/plugins/envato-wordpress-toolkit-master.zip

2. TGM Hook Function

Now that we have the required files, let's start coding. We'll need to include the TGM Plugin Activation class in our functions.php and hook into a custom WordPress action. This is where we will put some settings for TGM and where we will define what plugins to include.

/**
 * Load the TGM Plugin Activator class to notify the user
 * to install the Envato WordPress Toolkit Plugin
 */
require_once( get_template_directory() . '/inc/class-tgm-plugin-activation.php' );
function tgmpa_register_toolkit() {

	// Code here

}
add_action( 'tgmpa_register', 'tgmpa_register_toolkit' );

3. Specifying the Toolkit Plugin

Next, we configure the parameters we need to include the Toolkit plugin. Inside the tgmpa_register_toolkit function, add the following code. Change the path in the source parameter if you specified another plugin folder in Step 1.

// Specify the Envato Toolkit plugin
$plugins = array(
	array(
		'name' => 'Envato WordPress Toolkit',
		'slug' => 'envato-wordpress-toolkit-master',
		'source' => get_template_directory() . '/plugins/envato-wordpress-toolkit-master.zip',
		'required' => true,
		'version' => '1.5',
		'force_activation' => true,
		'force_deactivation' => false,
		'external_url' => '',
	),
);

You can also add other plugins by adding more arrays to the $plugins variable.

4. Configuring TGM

Then set up the options for TGM. Also inside the tgmpa_register_toolkit function, add the following code below the previous step to configure TGM. I won't dive into the specifics on what the individual settings do. If you want more information about these settings, the TGM Plugin Activation website does a good job of explaining every bit of it.

// i18n text domain used for translation purposes
$theme_text_domain = 'default';

// Configuration of TGM
$config = array(
	'domain'       	   => $theme_text_domain,
	'default_path' 	   => '',
	'parent_menu_slug' => 'admin.php',
	'parent_url_slug'  => 'admin.php',
	'menu'         	   => 'install-required-plugins',
	'has_notices'      => true,
	'is_automatic'     => true,
	'message' 		   => '',
	'strings'      	   => array(
		'page_title'                      => __( 'Install Required Plugins', $theme_text_domain ),
		'menu_title'                      => __( 'Install Plugins', $theme_text_domain ),
		'installing'                      => __( 'Installing Plugin: %s', $theme_text_domain ),
		'oops'                            => __( 'Something went wrong with the plugin API.', $theme_text_domain ),
		'notice_can_install_required'     => _n_noop( 'This theme requires the following plugin: %1$s.', 'This theme requires the following plugins: %1$s.' ),
		'notice_can_install_recommended'  => _n_noop( 'This theme recommends the following plugin: %1$s.', 'This theme recommends the following plugins: %1$s.' ),
		'notice_cannot_install'  		  => _n_noop( 'Sorry, but you do not have the correct permissions to install the %s plugin. Contact the administrator of this site for help on getting the plugin installed.', 'Sorry, but you do not have the correct permissions to install the %s plugins. Contact the administrator of this site for help on getting the plugins installed.' ),
		'notice_can_activate_required'    => _n_noop( 'The following required plugin is currently inactive: %1$s.', 'The following required plugins are currently inactive: %1$s.' ),
		'notice_can_activate_recommended' => _n_noop( 'The following recommended plugin is currently inactive: %1$s.', 'The following recommended plugins are currently inactive: %1$s.' ),
		'notice_cannot_activate' 		  => _n_noop( 'Sorry, but you do not have the correct permissions to activate the %s plugin. Contact the administrator of this site for help on getting the plugin activated.', 'Sorry, but you do not have the correct permissions to activate the %s plugins. Contact the administrator of this site for help on getting the plugins activated.' ),
		'notice_ask_to_update' 			  => _n_noop( 'The following plugin needs to be updated to its latest version to ensure maximum compatibility with this theme: %1$s.', 'The following plugins need to be updated to their latest version to ensure maximum compatibility with this theme: %1$s.' ),
		'notice_cannot_update' 			  => _n_noop( 'Sorry, but you do not have the correct permissions to update the %s plugin. Contact the administrator of this site for help on getting the plugin updated.', 'Sorry, but you do not have the correct permissions to update the %s plugins. Contact the administrator of this site for help on getting the plugins updated.' ),
		'install_link' 					  => _n_noop( 'Begin installing plugin', 'Begin installing plugins' ),
		'activate_link' 				  => _n_noop( 'Activate installed plugin', 'Activate installed plugins' ),
		'return'                          => __( 'Return to Required Plugins Installer', $theme_text_domain ),
		'plugin_activated'                => __( 'Plugin activated successfully.', $theme_text_domain ),
		'complete' 						  => __( 'All plugins installed and activated successfully. %s', $theme_text_domain ),
		'nag_type'						  => 'updated'
	)
);

Change the $theme_text_domain variable to the text domain you are using, or leave it as default.

5. Start TGM

Lastly, let's initialize TGM right before the end of the tgmpa_register_toolkit function.

tgmpa( $plugins, $config );

Now save your functions.php

Trying It Out

Try activating your theme. If you don't have the Envato WordPress Toolkit Plugin installed or activated yet, then you should see a notification similar to this one:

Conclusion

From what we have right now, we can actually stop with the series and your users will be able to update the theme from within the admin; however, users will only be able to see that there's an update if they're inside the Toolkit admin panel.

Part 2 of the tutorial will teach you how to integrate the Envato WordPress Toolkit Library, and how to display an admin notification whenever an update to the theme is available in ThemeForest.