As WordPress authors in ThemeForest, we hope to keep our customers happy by providing them with occasional bug fixes and theme enhancements. But a key issue we faced was how to notify our users when an update was available for download.

In the past, we each had to code in our own implementation of the theme update notifier. While there is now a checkbox to enable project update notifications in the Envato Marketplace, users still have to turn it on for each project and perform theme updates manually.

Wouldn’t it be better if update notifications were displayed in the WordPress admin center? And can the update be performed immediately in the admin? Luckily, we now have the Envato WordPress toolkit plugin and toolkit library.

In this series, you will learn how to integrate these toolkits into your theme.

What we will cover in this series

In this tutorial we will implement the Envato WordPress Toolkit plugin and library into our theme. When our theme is activated, users 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 will be displayed in the admin directing the user to the plugin to update the theme.

This tutorial is divided into two parts:

• Part 1 - Integrate the TGM plugin activation class so that using our theme requires the Envato WordPress Toolkit plugin; and
• Part 2 - Implementing the Envato WordPress Toolkit library in our theme to allow new theme version checking and updating.

Plug-ins and libraries?

The Envato WordPress toolkit comes in two flavors with different uses and purposes. To avoid confusing the two, here's a comparison:

• Toolkit Plugin - This is a standalone plugin that any Envato customer can install in their WordPress site. Upon activation, all previously purchased themes as well as theme updates can be downloaded directly from the administrator.
• Toolkit Library - Authors can include code in their WordPress themes that enables the theme to check for theme version updates and update itself using the Envato Marketplace API.

1.Include required files

We first need to include some files in the project. We will bundle the Toolkit plugin with our theme and use TGM plugin activation to install and activate the Toolkit.

1. Download the TGM plug-in activation and put the main class script into the inc folder in the 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 called “plugins” in your theme. 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 need to include the TGM plugin activation class in functions.php and hook into the custom WordPress action. Here we will set up some settings for the TGM and define the 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.Specify Toolkit plug-in

Next, we configure the parameters required to include the Toolkit plug-in. Inside the tgmpa_register_toolkit function, add the following code. If you specified another plugin folder in Step 1, change the path in the source parameter.

// 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 additional plugins by adding more arrays to the $plugins variable.

4.Configure TGM

Then set the TGM options. Also in the tgmpa_register_toolkit function, add the following code below the previous step to configure the TGM. I won’t go into the specifics of what each setting does. If you want to learn more about these settings, the TGM Plugin Activation website does a great job explaining every detail.

// 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

Finally, let's initialize the TGM before the tgmpa_register_toolkit function ends.

tgmpa( $plugins, $config );

Now save your functions.php

try it

Try activating your theme. If you haven't installed or activated the Envato WordPress Toolkit plugin, you should see a notification similar to this:

in conclusion

From what we know now, we can actually stop the series and your users will be able to update themes from within the admin; however, users will only see updates in the Toolkit admin panel.

Part 2 of this tutorial will teach you how to integrate the Envato WordPress Toolkit library and how to display admin notifications when theme updates occur in ThemeForest.