JSON Synchronization

Purpose

Creating containers through the administration interface normally saves them in the database. This method is convenient when working on a project locally, but also imposes some issues:

JSON Synchronization is only available if you are using the administration interface. If you are using the PHP API to create your containers and fields, they are already saved in your theme or plugin.

• Your fields and containers are not synchronized with your codebase, which means that you might run into issues during deployment: Uploading the updated code might result in a fatal error, because your containers and fields are not uploaded yet.
• There is no single source of truth. Even though containers can be exported as JSON from one instance and uploaded to a different one, if multiple developers have modified the same group, the changes made by all of them except one will be silently overwritten.
• Saving fields within a version control system (SVN, git, etc.) requires containers to be manually exported and imported, which makes it easy to forget the import or export procedures.

The JSON Synchronization feature can be enabled by creating a directory named uf-json within your theme. Once you do so, Ultimate Fields will start saving all containers as .json files in there and will only load containers from the given directory.

Advantages

Using the JSON Synchronization feature requires very little effort to implement, but brings great advantages:

1. Portability: Because containers are saved in the theme, they are now just as portable as the theme itself.
2. Version control: Because JSON is a text-based format, you can now use git and SVN to commit and auto-merge your containers.
3. There is a single source of through: Since Ultimate Fields loads the containers from the JSON folder, you will always see and use the fields, which have already been created, even by someone else.

States

Based on the existance of the uf-json folder and the status of individual containers, there are several states.

Disabled

In this state the JSON Syncrhonisation is completely disabled. Containers will not be saved to or loaded from the JSON folder and you will see the following messages:

Not writeable

If you have created a directory, but it is not writeable by PHP, you will get the following message:

In this situation, please change the permissions of the directory to 0755 in order to allow PHP to save files there.

Enabled & Synchronized

This is the best one.

When the directory is writable and Ultimate Fields can work with it, the state on the "JSON Management" page will be Enabled and you will be able to focus on the state of individual containers.

Above you can see how the JSON Management page looks like. Except for reporting that sync is enabled, the page also displays a table with all containers and their individual states. When everything is synhronized, everything will be green.

If there are any mismatches between the container in the database and the one in JSON, individual columns might become red to indicate it. In those situations you should either:

• Click the "Synchronize" button next to the container.
• Bulk-select all containers and apply the "Synchronize" action.

In both of those cases, Ultimate Fields will detect which source is newer (DB or JSON) and update the other sources to the same state.

Container States

The following states apply to individual containers when JSON is enabled.

Not existing

This message will be displayed within the JSON Synchronization box when the container exists in the database, but not in JSON.

To fix the issue, simply save the container. This will force Ultimate Fields to generate the JSON file for it. Please note that until you do so, the container will be not loaded at all, as in JSON mode Ultimate Fields works with files only.

Out of sync (1)

This happens when the database contains a newer version of the container. To fix it, simply save the container - this will save the new state in JSON.

Out of sync (2)

This will happen when JSON containes newer data than the one in the database.

It is important to click the "Synchronize" button at the bottom of the box in order to import the content of the file into the database. Unless you do so, changes made in JSON will be discarted when you attempt to make changes to the container.

Changing the directory

If you prefer to change the directory where JSON is saved, you can use the `uf.json_path' filter. It is loaded this way:

$this->path = apply_filters( 'uf.json_path', get_stylesheet_directory() . '/uf-json' );

As you notice, Ultimate Fields works with the stylesheet directory, which means that if you are running a child theme, the JSON folder should be created there. If you want to modify it, do so:

add_filter( 'uf.json_path', 'my_theme_change_json_path' );
function my_theme_change_json_path( $path ) {
    return get_template_directory() . '/assets/ultimate-fields/';
}