Howto: Bundle the Advanced Custom Fields into your premium Wordpress themes

It’s no secret that adding in custom fields functionality to a premium theme (if you’re a premium theme developer) is sometimes a pain in the ass, especially if you’re not using some kind of third party custom fields framework.

The Advanced Custom Fields plugin for WordPress gives you unrivalled custom fields functionality for an alarmingly low price of $0. There is also the option of buying addons for the plugin which cost $25 each and allow for unlimited use/bundling with a plugin.

The plugins I strongly advise you buy are the Repeater Field and Flexible Content Field. I own all of the additional addons, at $25 they’re a steal but these are the two that you definitely need to buy (or if you’re on a budget the repeater field at the very least).

While ACF doesn’t support bundling out-of-the-box, the author Elliot Condon allows for the plugin to be embedded as well as your purchased premium addons without buying additional licences. Please note that you are not allowed to bundle premium plugins within a free theme or plugin, however if you are selling a theme or plugin, you are allowed as long as you stipulate to the end user that distributing the premium plugins is not allowed in any way.

So lets get too it.

Step #1

You will want to visit the TGM Plugin Activation site and follow the prompts to download their handy and essential activation class, here. This class will allow us to bundle the ACF plugin in our premium theme.

Step #2

Extract the file, “class-tgm-plugin-activation.php” and place it into the root directory of your theme: wp-content/themes/theme-name/

At the top of your functions.php file (located in the root directory of your theme) add this to the very top below the opening PHP tags:

require_once ‘class-tgm-plugin-activation.php’;

This will include the activation class and lead us onto step #3.

Step #3

At the bottom of your functions.php add in the following code (before the closing PHP tag, if you have one). This code does not factor in using premium functionality like the Repeater Field, Flexible Content Field or Options Field, but the code is essentially the same, just add however many additional array entries below to bundle. ACF 4 removed the functionality from the plugin and broke it out into separate plugins to comply with WordPress plugin repository rules.

add_action( 'tgmpa_register', 'register_required_plugins' ); // This function is called from the above hook function register_required_plugins() { // The plugins array allows us to define multiple plugins we want to include. // The commented out example shows how we can include and activation a bundled // plugin zip file in our theme. $plugins = array( /* array( 'name' => 'Advanced Custom Fields', 'slug' => 'advanced-custom-fields', 'source' => get_stylesheet_directory() . '/theme/plugins/advanced-custom-fields.zip', 'required' => true, 'version' => '', 'force_activation' => true, // Force activation because we need advanced custom fields, 'force_deactivation' => false, 'external_url' => '' ), */ // This below definition will include the ACF plugin from the Wordpress.org plugins repository // and if permissions permit, will allow for it to be automatically downloaded and installed. // If permissions don't allow, the user will be prompted into downloading the plugin themselves // and installing it manually. array( 'name' => 'Advanced Custom Fields', 'slug' => 'advanced-custom-fields', 'required' => true, ), a ); $theme_text_domain = 'wp'; $config = array( 'domain' => $theme_text_domain, 'default_path' => '', 'parent_menu_slug' => 'themes.php', 'parent_url_slug' => 'themes.php', 'menu' => 'install-required-plugins', 'has_notices' => true, 'is_automatic' => false, '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 ), // %1$s = plugin name '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.' ), // %1$s = plugin name(s) 'notice_can_install_recommended' => _n_noop( 'This theme recommends the following plugin: %1$s.', 'This theme recommends the following plugins: %1$s.' ), // %1$s = plugin name(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.' ), // %1$s = plugin name(s) 'notice_can_activate_required' => _n_noop( 'The following required plugin is currently inactive: %1$s.', 'The following required plugins are currently inactive: %1$s.' ), // %1$s = plugin name(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.' ), // %1$s = plugin name(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.' ), // %1$s = plugin name(s) '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.' ), // %1$s = plugin name(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.' ), // %1$s = plugin name(s) '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 ), // %1$s = dashboard link 'nag_type' => 'updated' // Determines admin notice type - can only be 'updated' or 'error' ) ); tgmpa( $plugins, $config ); }

Step #4

After you’ve added in all required fields locally or on your staging environment, export them as PHP and paste in the exported code where the plugin tells you too. Voila, you’ve just bundled ACF with your theme and added in the needed fields.

Leave a ReplyCancel reply

4 Comments

Oldest

Newest Most Voted

Inline Feedbacks

View all comments

11 years ago

Hi there:
thanks for this info, I plan on including the ACF plugins in a ThemeForest theme and am sure this will be useful.

However I noticed that Elliott added a feature called ACF Lite Mode:
http://www.advancedcustomfields.com/resources/getting-started/including-lite-mode-in-a-plugin-theme/

What is your experience with this? Does it work in tandem or cancel out your instructions? Thanks a lot for your insight. Regards,
-JP

Dwayne

Author

JP,

Lite mode is good and pretty much removes most steps surrounding the bundling of ACF into your theme, however there is one severe limitation for some this might not be a problem, but ACF 4 broke out the premium addon functionality into additional plugins (Repeater Field, Flexible Content Field) which means if you need repeater functionality for example, you can’t have it.

Using the TGM class means you can bundle not only ACF, but also bundle the additional premium addon plugins as dependencies in your theme and you get the functionality.

So I would definitely use lite mode if none of the premium functionality matters, else-wise, use the instructions above but also bundle in those other dependencies for the functionality; repeater, flexible, options, etc.

Hi Dwayne:
That’s exactly the kind of detailed answer I was hoping for. I do indeed use both Repeater and Flexible Content fields so I’ll be taking advantage of your technique.
Thanks for sharing, you’ve saved me a ton of time and headache.

Pabrik Pintu

4 years ago

With the Advanced Custom Fields, I can make it easier to create fields that are not enough in the WordPress post pages, as we want. For example, I need additional fields, for example, subtitles, city names and so on.