Including ACF (Advanced custom fields) in a custom theme or plugin: Exporting fields on distribution

Question

I am working on a custom theme and have included acf pro inside that theme as mentioned in the docs. The theme is working fine and acf is activated on theme activation. Here is the code.

// customize ACF path
add_filter('acf/settings/path', 'my_acf_settings_path');
function my_acf_settings_path( $path ) {
    $path = get_stylesheet_directory() . '/inc/advanced-custom-fields-pro/';
    return $path;
}
// customize ACF dir
add_filter('acf/settings/dir', 'my_acf_settings_dir');
function my_acf_settings_dir( $dir ) {
    $dir = get_stylesheet_directory_uri() . '/inc/advanced-custom-fields-pro/';
    return $dir;
}
// Include ACF
include_once( get_stylesheet_directory() . '/inc/advanced-custom-fields-pro/acf.php' );

The issue i am facing for couple of hours now is due to the groups/fields that i want to be instantiated inside acf. I have some field groups that i want to be shown on fresh installation. Below are the methods i have tried:

Method 1: I have exported the fields as json inside a folder called acf-json. ACF does recognize it and shows as a sync field. But when i try syncing it, it just creates a new empty field.

Method 2: I have also tried exporting the field groups as php files and then including it in my functions.php file but acf doesn't recognize this code.

Answer 1

Distributing ACF in a theme or plugin is a bit tricky because of lack of information in the docs. The tricky part is exporting your fields with your theme and plugin, in a way that your users dont have to do anything different then what they are used to with any other theme or plugin. I will go through the procedure in detail.

For theme and plugin Development:

Referring the official docs, it should be pretty easy to copy and paste the code in your functions.php file for theme development, while for plugin development you can add it to the main plugin file. This will accomplish these 4 tasks.

1. Add ACF Path
2. Add ACF Dir
3. Hide ACF from clients (if needed)
4. Include ACF

Up till now what you have done actually doesn't do anything special. It just activates ACF whenever you activate your theme/plugin and similarly deactivates ACF on theme/plugin deactivation.

Exporting Fields: (via JSON sync)

At this stage if you distribute your theme/plugin it will just activate ACF, but it wont have any fields inside it. ACF uses JSON to keep track of all the fields and field groups. By default ACF will look for a folder called acf-json in the root of your theme. If you have this folder then ACF will automatically add/update a new json file for each field group you add or update.

You can change the location of this folder, if you want to keep it inside your includes folder. Somehow you cant change the default location on a theme, but for plugins you can by adding this code.

add_filter('acf/settings/save_json', 'set_acf_json_save_folder');
function set_acf_json_save_folder( $path ) {
    $path = dirname(__FILE__) . '/includes/acf-json';
    return $path;
}
add_filter('acf/settings/load_json', 'add_acf_json_load_folder');
function add_acf_json_load_folder( $paths ) {
    unset($paths[0]);
    $paths[] = dirname(__FILE__) . '/includes/acf-json';
    return $paths;
}

Now if you share this theme/plugin with someone, when they go inside ACF they should see a new option for sync. On syncing all the files fields should be available to them.

Automatting the SYNC Process:

If you want to hide ACF completely then obviously you cant have your users go inside ACF and sync fields. So in this case you need a script that would automatically sync all the fields from the json folder. You can add this code inside your functions.php for themes or inside your main plugin file. You dont have to change any paths in this script because in the previous code you have already told ACF where to load the JSON files from.

add_action( 'admin_init', 'article_gamification_sync_acf_fields' );
function article_gamification_sync_acf_fields() {
    // vars
    $groups = acf_get_field_groups();
    $sync   = array();
    // bail early if no field groups
    if( empty( $groups ) )
        return;
    // find JSON field groups which have not yet been imported
    foreach( $groups as $group ) {

        // vars
        $local      = acf_maybe_get( $group, 'local', false );
        $modified   = acf_maybe_get( $group, 'modified', 0 );
        $private    = acf_maybe_get( $group, 'private', false );
        // ignore DB / PHP / private field groups
        if( $local !== 'json' || $private ) {

            // do nothing

        } elseif( ! $group[ 'ID' ] ) {

            $sync[ $group[ 'key' ] ] = $group;

        } elseif( $modified && $modified > get_post_modified_time( 'U', true, $group[ 'ID' ], true ) ) {

            $sync[ $group[ 'key' ] ]  = $group;
        }
    }
    // bail if no sync needed
    if( empty( $sync ) )
        return;
    if( ! empty( $sync ) ) { //if( ! empty( $keys ) ) {

        // vars
        $new_ids = array();

        foreach( $sync as $key => $v ) { //foreach( $keys as $key ) {

            // append fields
            if( acf_have_local_fields( $key ) ) {

                $sync[ $key ][ 'fields' ] = acf_get_local_fields( $key );

            }
            // import
            $field_group = acf_import_field_group( $sync[ $key ] );
        }
    }
}

**Now when you distribute your theme/plugin, on activation it will also activate ACF, then copy all the json files and execute them. This will automatically sync all the field groups, now you can even hide your ACF plugin, and none of your users ever have to go inside ACF to sync fields, infact they wont even have to know that ACF exists on their site. Secondly even if you make a new change in ACF, it should automatically update changes to the json files. You can now even version control them for better control. **