My Blog on WordPress Development + Other Goodies

Posted on September 30, 2011 by in WordPress Customizations, WordPress Tutorials with 33 Comments

Automatically Install Plugins with Themes for WordPress

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.

With v2.2.0 just releasing, we will now be updating all the support information for the TGM Plugin Activation library at this site: http://tgmpluginactivation.com. Please go there for all the latest updates!

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!

***UPDATE***

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!

Click here to download the class from Github

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:

  1. Automatically install a plugin that comes pre-packaged with the theme
  2. 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, $config and $theme_text_domain.

The $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.

The $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.

The $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!

Thomas

Do you like what you have read and want to receive content updates? Sign up below and also get my
"7 Tips to a Professional WordPress Setup" absolutely free!

  • http://wpconsult.net Paul

    This is really awesome, thanks!
    I’m developing a theme and I want to prompt users to install a slider plugin, instead of bundling all functionality in the theme

    • Thomas Griffin

      No problem. I have been in your situation many times before and this is the perfect solution for that. :)

  • http://creativityincluded.com Chris Ford

    Great, great idea — I can see including this on every theme I create from now on!

    • Thomas Griffin

      Thanks Chris! I hope that you do – I would love to showcase it!

  • http://nathangiesbrecht.com Nathan Giesbrecht

    This is brilliant! I will be using this with every theme I develop from now on.

    • Thomas Griffin

      Good deal! Make sure you let me know if you do – I’d love to see it in action. :)

  • JPry

    This is definitely a great idea! Thanks for making it available.

    Just one question: Is it possible to make this so that it can accept a unzipped directory in addition to a zip file for an included plugin? Granted, it is better to distribute zipped files, but it would be nice to have the option.

    • Thomas Griffin

      Currently that option is not available. You could always just place it in an unzipped folder and reference specifically the zip file, though. :)

  • Pingback: Wordpress Themes Can Now Include Plugins: Here's How To Do It

  • Ezhil

    Hi thomas,
    Fanstastic class and a must need for professioanl themes, i got some problem when installing few plugins [ wp-pagenavi, wp-views, wp-postratings etc... ] ‘ The plugin generated unexpected output. ‘ , i hope this error is due to characters or whitespace before the . But when i install the same plugin using search option / upload option their are no errors, so do we need to do some tweaking to avoid those errors?

  • Marc Remblance

    Loving this guys, really hope this is the way forward for Commercial WordPress themes. As someone just entering the theming market, what is the general consensus in regards to ‘in-built’ widgets (ie custom flickr widget, twitter widget etc..) and asking a customer to install X plugins? Are places like ‘Themeforest’ coming round to the thinking of the latter?

    • Thomas Griffin

      I’m not sure what the general consensus is exactly, but if a user expects that functionality to be present when he/she switches themes, then it is safe to assume that you should be using a plugin and not a built-in widget. :-)

  • http://www.viraljetani.com Vir J

    Hi Thomas,
    I used your class. Great Work I cant stop appreciating it.
    I have developed a theme and need Magic-Fields plugin to be into theme package when anyone activates the theme..
    However when i Click on Install Magic-Fields Now button into prompt list. its giving me error after loading a bit. I am pasting the error here,
    “
    object(WP_Error)#199 (2) { ["errors"]=> array(1) { ["plugins_api_failed"]=> array(1) { [0]=> string(57) “An Unexpected HTTP Error occurred during the API request.” } } ["error_data"]=> array(1) { ["plugins_api_failed"]=> string(79) “Could not open handle for fopen() to http://api.wordpress.org/plugins/info/1.0/” } }

    Something went wrong.
    ”

    Any help over this would be highly appreciated.

    Thanks and Regards,
    Vir.

    • Thomas Griffin

      That error seems to be with the WordPress plugins_api() function and not specifically with our class. This could also be an issue with your permissions on your computer, or it could be just a small bug with the WordPress Plugins API. Have you made sure the plugin slug is correct?

    • http://www.facebook.com/rasihanbharathi Bharathi Kannan

      i too have the same problem !! have you fount out the solution ??

  • http://kattagami.com kattagami

    Hello Thomas,

    Thanks a lot for this fantastic Class :)
    There is a way to automatically activate the plugin after the install process ?

    Gilles

    • Thomas Griffin

      Thanks for the kind words! Yes, as of right now the current version of the class (v2.1.1) has automatic installation already built in. The next version of the class (which is due out soon) will have a config option where you can turn automatic activation on and off to give you greater control of how the plugins are presented.

  • http://icustomizethesis.com Puneet Sahalot

    Perfect solution for a building a complete theme package for clients!
    PS: Would be great if you add a bit of code to hide “deactivate” option for “essential” plugins to be used with themes.

    • Thomas Griffin

      Thanks man! You will have that ability with the next version (2.2.0) that will come out today. You have two optional plugin parameters that you can set for each plugin: ‘force_activation’ and ‘force_deactivation’. ‘force_activation’ will force the plugin to be active the entire time the theme is in use (can only be deactivated if a user switches themes). ‘force_deactivation’ deactivates the plugin upon theme switch (useful for theme-specific plugins). Force activation also checks to see if the plugin is already installed, and if it is, it activates it automatically for you. :-)

      • http://icustomizethesis.com Puneet Sahalot

        Great! That’s going to be a perfect solution for a Theme Developer :-)
        Looking forward to using it with future projects.
        Thanks again!

  • http://gavinflood.com Gavin Flood

    Excellent class man, will make things so much handier for me! I’ll definitely be spreading the word and letting people know about this! This may just become one of my main resources for theme development!

    • Thomas Griffin

      Thanks man, glad you are enjoying it!

  • Pingback: http thomasgriffinmedia com blog 2011 09 automatically install… « Internet Marketing and WordPress Design Resources

  • Makc

    Thomas, thank you very much!

  • http://rak-seo.co.il Reichman

    nothing like WordPress, thanks for the tip!

  • http://www.fearhealing.com David Cosier

    Hi Thomas,

    I was wondering if you would be able to provide some direction to how you added the “notify me of followup comments via email” and “subscribe me to your mailing list.” (located at the bottom of this post). Is this a WordPress plugin? If so, where would I find it? If not, is there a WordPress plugin which provides similar features?

    Thanks for your response!

    David :)

  • Zain mehmood

    ITS AN aWESOMEEE SOLUTION HELPED ME ALOT . . . THANKS TGM

  • Dennis

    Hi, would you be able to list your own repo location on a separate website/server, some plugins can be big to have packaged with a theme and not all of them are located in the wordpress repo

    • Thomas Griffin

      Sure. You can specify the source URL for your plugin using the ‘source’ key within the plugin array, and it can point to an external zip file of your choosing. :-)

  • Jonathan

    Hi there, This is exactly what I was looking for! I’ve just installed this code and it is working fine showing the recommendations at the top of the dashboard. However, clicking on the plugins menu all I get is a blank screen now? Any reason as to why this might be?

    Many Thanks

    • Thomas Griffin

      Hey Jonathan,

      I just pushed an update a couple minutes ago that fixed one bug (unrelated to yours, but it would be good to go ahead and use the newest version). As for the blank screen, have you changed the location of the plugins page? It could be that the slugs you have entered are not correct. By default, they both point to themes.php. I would make sure that using both of the defaults makes the plugin page work correctly. If so, you know that you’ve entered something incorrectly. :-) That’s the only thing I can think of that would cause that issue.

  • Paul

    Hello Thomas!
    Thank you very much for this plug-in! It is just awesome, so clean, light and powerful!
    Although i have a lack of understanding with ‘force_activation’ …
    Do the user need to install the plug-in himself through your plugin settings page or the admin message after theme activation?
    Or is there a way to force the installation(!) and activation of the plugin by activating the theme?

  • sadi

    hey there ,

    your class is awesome . just one question . in the install plugin menu every plugin is shown as recommend . where to change it like optional for one plugin or recommend for another ?

    thank you