Understanding where your ACF field group settings are coming from

This is a follow up to the "How to avoid conflicts when using the ACF Local JSON feature" article.

This is a follow up to the How to avoid conflicts when using the ACF Local JSON feature article. I recommend you take a look at that post first to get the necessary background.

In this article I will attempt to provide some tips for understanding and cleaning up the state of your ACF field groups with regard to the ACF Local JSON feature, version control and working in a team.

When using the Local JSON feature, it’s important to understand that the field group settings used in the content editing side of ACF (eg. Edit Post or other field group Location) can be different to the settings seen in the ACF Edit Field Group admin pages.

Whereas the ACF Field Groups and Edit Field Group admin pages will always use the settings that are stored in the database, the content editing side of ACF will use the field group settings that have the highest modified value. These could be stored in the database or a JSON file.

Unfortunately ACF doesn’t give you any indication of where the field group settings used on the content editing side are being loaded from. It will only tell you if a Sync is available for the field group.

“JSON field groups will be available for sync when either the JSON field group does not exist in the DB, or when the JSON field group contains a higher ‘modified’ value (within the JSON array) than the DB post’s modified date.” – advancedcustomfields.com

So where are my field group settings loading from?

The following method for determining where a field group’s settings are loading from was suggested to me by Aaron Rutley (coauthor of the ACF Theme Code plugin).

I recommend taking a backup of the site’s database and acf-json before proceeding.

1. Open the field group’s JSON file in a code editor and add an underscore to the end of the title property near the top of the file. Making this change via a code editor avoids updating the modified value in the JSON.
2. Save the edited file.
3. In the WordPress admin go to one of the field group’s Locations (eg. Edit Page) and check if the underscore is visible in the field group’s title. It’s important to note we are looking at the content editing side of ACF, not the Edit Field Group admin page.
4. If the underscore is visible, the JSON file is being loaded.
5. If the underscore is not visible, the field group is being loaded from the database.
6. Make note of where the field group settings are loading from.
7. Open the field group’s JSON file in a code editor again and remove the underscore from the end of the title property.
8. Save the JSON file to restore it to it’s original state.

Why do I need to know this?

If you have noticed that you are having issues with your field group settings (as discribed in the previous article, knowing where your field groups are loading from is the first step in understanding and fixing the problem.

Understanding the state of all the things

When using the Local JSON feature with version control, here are the possible states for any given field group.

Tips for your various states

Cleaning up a site that has a combination of these states can be quite a tricky task with much to consider. Below are some basic tips to get you started in the process. Please be sure you have all the necessary backups before making any changes.

State #1 is the goal (as describe in the previous article). Each field group should have a JSON file in the project repository that contains all the desired field group settings. The field group should not exist in the database.

State #4 and State #8 are the trickiest. Some of the desired field group settings are in the JSON file while others are in the database. Firstly this will require some manual merging of settings, via either the JSON file or the WordPress admin, to get the field group to a different state.

State #2 can be identified by saving the field group and checking if the updated JSON file is showing up as a new or modified file in your local version control setup.

State #3 can be rememdy by removing the JSON file and resaving the field group via the WordPress admin. This will create a new JSON file with the field group settings from the database.

State #5 can be fixed by moving the JSON file out the `acf-json` folder, deleting the field group via the WordPress admin and then moving the JSON file back to it’s original place. State #6 then requires also adding the JSON file to your repo.

In the case of State #7, a JSON file may not yet exist for the field group if it hasn’t been saved since the Local JSON feature was enabled on the site.

Ejecting field groups from the database

As previously mentioned, it is recommended that field groups only exist in JSON files, not in the database.

Please note if you delete a field group via the WordPress Admin, ACF will also delete the JSON file associated with the field group. To remove a field group from the datebase but keep the JSON file, follow the instructions for State #5 above.