Documentation

After generating a unqiue plugin manager for your project, your package will begin to downlowd and you'll be shown a code snippet you can use to get started, which is tailored to your specific project.

This article may seem a bit overwhelming at first glance, but it's only meant to provide further details on the code snippet provided to you. For a quick start, simply download your custom plugin manager and then use the custom code snippet provided as starting point. If you have questions about any of the sections, use this documentation article.

Getting Started

Before implementing the plugin manager into your WordPress theme or plugin, please generate a unqiue copy for your project.

Our online generator tool will re-name the files, classes, and namepsaces, to match your specific project. This allows the plugin manager to play more nicely with implementations by other theme and plugin authors, used in conjunction with yours.

Add the Drop-in Directory

Upon unzipping your generated download package, you'll find a "plugin-manager" directory; add this entire directory to your WordPress theme or plugin.

Keep in mind that the sample code snippet provided to you assumes the "plugin-manager" directory is placed in the root of your theme or plugin, but you don't have to put it there, if you don't want. If you're placing the directory somewhere else nested within your theme or plugin, make sure to account for this when including the plugin manager class.

Setting Up

To keep organized, we suggest keeping your plugin manager setup code in its own function hooked to after_setup_theme. This will make it possible for other plugin and child theme developers to easily get rid of the plugin manager added by your product, if they wish.

function my_plugin_manager() {

	if ( ! is_admin() ) {
		return;
	}

	// Everything discussed througout this article
	// would go here.

}
add_action( 'after_setup_theme', 'my_plugin_manager' );

Note: The above example uses a function prefixed with my_, but your implementation should use a namespace unique to your theme or plugin. For example, a theme named "Jump Start" might prefix the function with jump_start_, to implement a function jump_start_plugin_manager().

Include Plugin Manager

Although your "plugin-manager" is actually a directory of several files, you only need to include one file, class-my-plugin-manager.php.

Note: Your custom plugin manager's class file will be named differently. For example, for a theme named "Jump Start", the plugin manager class file would be named class-jump-start-plugin-manager.php.

Below are some examples of you might include the plugin manager class, depending your project type.

Standard Theme

require_once( get_parent_theme_file_path( '/plugin-manager/class-my-plugin-manager.php' ) );

Child Theme

require_once( get_theme_file_path( '/plugin-manager/class-my-plugin-manager.php' ) );

Plugin

require_once( plugin_dir_path( __FILE__ ) . '/plugin-manager/class-my-plugin-manager.php' );

Suggested Plugins

By "suggested plugins" we're referring to the plugins you are suggesting that your users install, in addition to your theme or plugin.

Within the example code snippet provided to you upon generating your download package, you'll see an example array of plugins something like the following.

$plugins = array(
	array(
		'name'    => 'Easy Digital Downloads',
		'slug'    => 'easy-digital-downloads',
		'version' => '3.0+',
	),
	array(
		'name'    => 'JetPack',
		'slug'    => 'jetpack',
		'version' => '5.0+',
	),
	array(
		'name'    => 'Gravity Forms',
		'slug'    => 'gravityforms',
		'version' => '2.2+',
		'url'     => 'http://www.gravityforms.com', // Only for non wp.org plugins.
	),
);

Each individual plugin's array needs be formatted with the following keys.

Key Required Description
name Required The user-facing name of the plugin.
slug Required The slug of the plugin; this must match the name of the plugin's directory.
version Required The minimum of version of that plugin your product is compatible with. We suggest using a plus sign for clearer communication to your user like 2.0+.
url Optional The website URL to purchase or download the suggested plugin, only if the plugin is not hosted on wordpress.org.

Important! It's important that if the suggested plugin is hosted on wordpress.org, that you do not include a url for it in the plugin's array. This is meant to be an external non-wordpress.org URL. If it exists, it will disable the auto-install functionality for the given plugin, as auto-installing plugins from third-party sources is not supported.

Options

Depending on your project, you'll most likely want to pass an array of options to your plugin manager.

$args = array(
	'page_title' => __( 'Suggested Plugins', 'my-project' ),
	'menu_slug'  => 'my-project-suggested-plugins',
	// Continue adding any more options you want...
);

Below are all the possible options you can utilize.

Option Default Description
page_title Suggested Plugins Title printed at the top of the plugin manager admin screen.
views_title Suggested by {project name} Text for link to the plugin manager admin screen, which gets inserted at WordPress's main Plugins admin screen. Set to false to disable.
tab_title Suggested by {project name} Text for link to the plugin manager admin screen, which gets inserted at WordPress's Install Plugins admin screen. Set to false to disable.
extended_title Suggested Plugins by {project name} An extended title that gets used in the title tags of links generated from both $views_title and $tab_title.
menu_title NULL Title of plugin manager menu item. If left blank, this will default to $page_title.
parent_slug themes.php or plugins.php The WordPress parent admin screen slug for the plugin manager page.

If implenting into a theme, this must be themes.php.
menu_slug suggested-plugins URL slug for the plugin manager admin screen; we suggest adding a unqiue namespacing key to this value like my-project-suggested-pugins.
capability install_plugins WordPress user capability for seeing the plugin manager admin screen.
nag_action Manage suggested plugins Text of the link, which leads the user to the plugin manager admin screen.
nag_dimiss Dismiss this notice Screen reader text to dismiss plugin manager nags.
nag_update Not all of your active, suggested plugins are compatible with {project name}. Text for the message, letting users know not all installed suggested plugins are compatible with your project.
nag_install_single {project name} suggests installing 1 plugin. Text for the message, telling users to install suggested plugins (which are not already installed), if only one exists.
nag_install_multiple {project name} suggests installing {amount} plugins. Text for the message, telling users to install suggested plugins (which are not already installed).
child_theme false Whether you're implenting the plugin manager from a child theme.

This is required if implementing the plugin manager from a child theme.
plugin_file NULL The full, absolute path to your plugin's main file. If your implementation code already exists in your plugin's main file, you can simply use __FILE__.

This is required if implementing the plugin manager from a plugin.

Add Plugin Manager Object

Once you've included the plugin manager class, and you've got your array of options and array of suggested plugins, you'll use these to instantiate the plugin manager object.

$manager = new My_Plugin_Manager( $plugins, $args );

Note: Every implementation of the plugin manager package will have a uniquely named plugin manager class. For example, for a theme named "Jump Start" the plugin manager class will be named Jump_Start_Plugin_Manager.

Examples

Putting together everything from this article, here are some examples of what the final code snippet might look like for different project types.

Standard Theme

A theme named "Jump Start" might setup the plugin manager something like the following.

/**
 * Setup suggested plugin system.
 *
 * Include the Jump_Start_Plugin_Manager class and add
 * an interface for users to to manage suggested
 * plugins.
 *
 * @since x.x.x
 *
 * @see  Jump_Start_Plugin_Manager
 * @link http://mypluginmanager.com
 */
function jumpstart_plugin_manager() {

	if ( ! is_admin() ) {
		return;
	}

	/**
	 * Include plugin manager class.
	 *
	 * No other includes are needed. The Jump_Start_Plugin_Manager
	 * class will handle including any other files needed.
	 *
	 * If you want to move the "plugin-manager" directory to
	 * a different location within your theme, that's totally
	 * fine; just make sure you adjust this include path to
	 * the plugin manager class accordingly.
	 */
	require_once( get_parent_theme_file_path( '/plugin-manager/class-jump-start-plugin-manager.php' ) );

	/*
	 * Setup suggested plugins.
	 *
	 * It's a good idea to have a filter applied to this so your
	 * loyal users running child themes have a way to easily modify
	 * which plugins show as suggested for the site they're setting
	 * up for a client.
	 */
	$plugins = apply_filters( 'jumpstart_plugins', array(
		array(
			'name'    => 'Easy Digital Downloads',
			'slug'    => 'easy-digital-downloads',
			'version' => '2.8+',
		),
		array(
			'name'    => 'JetPack',
			'slug'    => 'jetpack',
			'version' => '5.0+',
		),
		array(
			'name'    => 'Gravity Forms',
			'slug'    => 'gravityforms',
			'version' => '2.2+',
			'url'     => 'http://www.gravityforms.com', // Only for non wp.org plugins.
		),
	));

	/*
	 * Setup optional arguments for plugin manager interface.
	 *
	 * See the set_args() method of the Jump_Start_Plugin_Manager
	 * class for full documentation on what you can pass in here.
	 */
	$args = array(
		'page_title' => __( 'Suggested Plugins', 'jumpstart' ),
		'menu_slug'  => 'jumpstart-suggested-plugins',
	);

	/*
	 * Create plugin manager object, passing in the suggested
	 * plugins and optional arguments.
	 */
	$manager = new Jump_Start_Plugin_Manager( $plugins, $args );

}
add_action( 'after_setup_theme', 'jumpstart_plugin_manager' );

Child Theme

A child theme named "Jimmy" might setup the plugin manager something like the following.

/**
 * Setup suggested plugin system.
 *
 * Include the Jimmy_Plugin_Manager class and add
 * an interface for users to to manage suggested
 * plugins.
 *
 * @since x.x.x
 *
 * @see  Jimmy_Plugin_Manager
 * @link http://mypluginmanager.com
 */
function jimmy_plugin_manager() {

	if ( ! is_admin() ) {
		return;
	}

	/**
	 * Include plugin manager class.
	 *
	 * No other includes are needed. The Jimmy_Plugin_Manager
	 * class will handle including any other files needed.
	 *
	 * If you want to move the "plugin-manager" directory to
	 * a different location within your child theme, that's
	 * totally fine; just make sure you adjust this include
	 * path to the plugin manager class accordingly.
	 */
	require_once( get_theme_file_path( '/plugin-manager/class-jimmy-plugin-manager.php' ) );

	// Setup suggested plugins.
	$plugins = array(
		array(
			'name'    => 'Easy Digital Downloads',
			'slug'    => 'easy-digital-downloads',
			'version' => '2.8+',
		),
		array(
			'name'    => 'JetPack',
			'slug'    => 'jetpack',
			'version' => '5.0+',
		),
		array(
			'name'    => 'Gravity Forms',
			'slug'    => 'gravityforms',
			'version' => '2.2+',
			'url'     => 'http://www.gravityforms.com', // Only for non wp.org plugins.
		),
	);

	/*
	 * Setup optional arguments for plugin manager interface.
	 *
	 * See the set_args() method of the Jimmy_Plugin_Manager
	 * class for full documentation on what you can pass in here.
	 */
	$args = array(
		'page_title'  => __( 'Suggested Plugins', 'jimmy' ),
		'menu_slug'   => 'jimmy-suggested-plugins',
		'child_theme' => true,
	);

	/*
	 * Create plugin manager object, passing in the suggested
	 * plugins and optional arguments.
	 */
	$manager = new Jimmy_Plugin_Manager( $plugins, $args );

}
add_action( 'after_setup_theme', 'jimmy_plugin_manager' );

Plugin

A plugin named "Simple Analytics" might setup the plugin manager something like the following.

/**
 * Setup suggested plugin system.
 *
 * Include the Simple_Analytics_Plugin_Manager class and add
 * an interface for users to to manage suggested
 * plugins.
 *
 * @since x.x.x
 *
 * @see  Simple_Analytics_Plugin_Manager
 * @link http://mypluginmanager.com
 */
function simple_analytics_plugin_manager() {

	if ( ! is_admin() ) {
		return;
	}

	/**
	 * Include plugin manager class.
	 *
	 * No other includes are needed. The Simple_Analytics_Plugin_Manager
	 * class will handle including any other files needed.
	 *
	 * If you want to move the "plugin-manager" directory to
	 * a different location within your plugin, that's totally
	 * fine; just make sure you adjust this include path to
	 * the plugin manager class accordingly.
	 */
	require_once( plugin_dir_path( __FILE__ ) . '/plugin-manager/class-simple-analytics-plugin-manager.php' );

	/*
	 * Setup suggested plugins.
	 *
	 * It's a good idea to have a filter applied to this so your
	 * loyal dev users have an easy way to modify what plugins
	 * are suggested.
	 */
	$plugins = apply_filters( 'simple_analytics_plugins', array(
		array(
			'name'    => 'Easy Digital Downloads',
			'slug'    => 'easy-digital-downloads',
			'version' => '2.8+',
		),
		array(
			'name'    => 'JetPack',
			'slug'    => 'jetpack',
			'version' => '5.0+',
		),
		array(
			'name'    => 'Gravity Forms',
			'slug'    => 'gravityforms',
			'version' => '2.2+',
			'url'     => 'http://www.gravityforms.com', // Only for non wp.org plugins.
		),
	));

	/*
	 * Setup optional arguments for plugin manager interface.
	 *
	 * See the set_args() method of the Simple_Analytics_Plugin_Manager
	 * class for full documentation on what you can pass in here.
	 */
	$args = array(
		'page_title'  => __( 'Suggested by Simple Analytics', 'simple-analytics' ),
		'menu_title'  => __( 'Suggested', 'simple-analytics' ),
		'menu_slug'   => 'simple-analytics-suggested-plugins',
		'parent_slug' => 'plugins.php',
		'plugin_file' => __FILE__, // Required for use in plugins.
	);

	/*
	 * Create plugin manager object, passing in the suggested
	 * plugins and optional arguments.
	 */
	$manager = new Simple_Analytics_Plugin_Manager( $plugins, $args );

}
add_action( 'after_setup_theme', 'simple_analytics_plugin_manager' );