Ship plugin with a custom theme

Question

I need to add a plugin to a theme and enable it automatically once the theme is activated. Would also like to change its settings if possible. This is the plugin I am trying to include: https://wordpress.org/plugins/subheading/

I tried adding the plugin inside the theme plugin folder but it does not show up on WP plugins page. What am I doing wrong?

Answer 1

The user decides

To answer your last question first:

I tried adding the plugin inside the theme plugin folder [...] What am I doing wrong?

You are trying to bundle functionality into a theme. That is the wrong thing in the first place. Themes offer presentation - Plugins offers functionality.

Aside from that, functionality should be the users choice. And your theme should work with and without the plugin. You also save the user from loosing his settings when he switches the theme. Just note that your theme "supports subheading plugin". The installation and activation is up to the user.

How to?

To achieve that, you can just wrap plugin functionality in a filter or hook and check if the plugin is active using is_plugin_active():

// functions.php
add_action( 'subheading', 'subheading_callback' );
function subheading_callback()
{
    if ( ! is_plugin_active( 'plugin-folder-name/plugin-file.php' ) )
    {
        remove_action( current_action(), __FUNCTION__ );
        return;
    }

    // Call subheading-plugin function to output subheading here
    // From the subheading plugin:
    // $before = '', $after = '', $display = true, $id = false
    the_subheading( '<h3>', '</h3>', true, get_the_ID() );
}

Then in your template file, just add the hook to output the subheading.

// for e.g. single.php - in the loop
do_action( 'subheading' );

Aside from that, there is the "TGM Plugin Activation" script which you can use in your theme. It allows you to tell the user upon activation that s/he needs the plugins X, Y and Z which you can set up with default settings (IIRC).

Answer 2

There's no method to bundle a plugin with a theme install. Your best bet would be to check if a plugin is installed using is_plugin_active in your functions.php. If not, display a notice in the admin area directing them to download/install it.