Overview
Local JSON is a new feature added in version 5 which saves field group and field settings as .json files within your theme. The idea is similar to caching, and both dramatically speeds up ACF and allows for version control over your field settings!
Getting started
To start using the local JSON feature, simply create a new folder in your theme and name it acf-json. This folder must have permissions for the server to read and write (in most cases 755 will work well).
Once this folder exists, each time you save a field group a JSON file will be created (or updated) with the field group and field settings. The JSON file will be named using the field group’s unique key.
Now that the JSON file exists, ACF will load the relevant field group and field settings from this file which reduces the number of database calls during your page load!
Saving explained
Each time you save a field group a JSON file will be created (or updated) with the field group and field settings. The JSON file will be named using the field group’s unique key. Only 1 save point (folder) exists and can be customized by adding the following code to your theme.
<?php
add_filter('acf/settings/save_json', 'my_acf_json_save_point');
function my_acf_json_save_point( $path ) {
// update path
$path = get_stylesheet_directory() . '/my-custom-folder';
// return
return $path;
}
?>Loading Explained
During ACF’s initialization procedure, all .json files within the acf-json folder will be loaded. By default ACF looks for a folder within your theme called acf-json, however, this is only 1 of the load points which can be added
To add a new load point (folder) for ACF to look in, please add the following code to your theme or plugin.
<?php
add_filter('acf/settings/load_json', 'my_acf_json_load_point');
function my_acf_json_load_point( $paths ) {
// remove original path (optional)
unset($paths[0]);
// append path
$paths[] = get_stylesheet_directory() . '/my-custom-folder';
// return
return $paths;
}
?>This filter will allow plugin and theme developers to easily register field groups which cannot be edited by clients.
Syncing changes
The real power in ‘local JSON’ is the ability to sync changes. This allows multiple devs to work on a project, use git to push / pull files, and keep all databases synchronized with the latest field group settings!
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.
When fields groups are detected for synchronization, you will see a new tab above the field group list where you can select the groups to be imported.
Security
If you wish to hide your field group or field settings from the public, simply add an empty index.php file to your acf-json folder. WP use the same method to hide the wp-content/themes folder, they like to add a message too 👍.
index.php
<?php
// Silence is golden.
?>