Since version: v1.5.8
Switch Field Type from Free to Pro
This guide explains how to transition an existing setup from the Free field type to the Pro field type while both plugins remain installed side by side. Since the Free and Pro versions operate independently, the migration affects only the ACF/SCF field type, not the stored data or the plugin installation itself.
1. Free and Pro Plugins Running in Parallel
The Free and Pro versions of the plugin can be activated at the same time. Existing fields continue to work as long as their field type remains set to the Free version. The migration process begins only when you manually change the field type to the Pro variant.
2. Migration by Switching the Field Type
The transition from Free to Pro happens by changing the field type in the field settings. Once switched, the field immediately uses the Pro engine, including its extended configuration options and more advanced output logic. The underlying data remains intact, but the way it is processed and rendered changes.
3. Update Templates Before Switching
Before changing the field type, templates should be updated to handle the Pro output. The Pro version generates more complex HTML structures and additional metadata that do not exist in the Free version. Code that was written specifically for the Free output no longer work and may cause errors.
Key considerations:
- Review all templates where the field is rendered.
- Ensure the template logic is compatible with the Pro output format.
- Prepare for a short transition period where both Free and Pro fields may exist simultaneously.
4. Use get_table() Instead of Free‑Version Output Code
The Pro version provides the get_table() and corresponding functions, which generates the complete HTML output for the table. This function replaces the custom or manual rendering code commonly used in the Free version.
Reasons to use get_table() or corresponding Table Field plugin functions:
- It supports all advanced Pro features.
- It ensures consistent and complete HTML output.
- It reduces the need for custom rendering logic.
- There are filters to change and customize the table HTML output.
5. get_table() Can Also Render Fields That have the Free Field Type
For a smoother migration, get_table() is able to process fields having the Free version. This allows you to update templates ahead of time and switch the field type later without breaking the frontend.
6. Differences in Formatted and Unformatted Output
The formatted and unformatted output of field data differs between the Free and Pro versions. The Pro version includes additional structure, metadata, and formatting rules. Any custom code that relies on the Free version’s output format must be reviewed and adapted accordingly.
7. Note How the Transition of the Field’s Data in the Database Is Handled
When a fields field type is switched from the Free version to the Pro version, the fields data stored in the database does not get rewritten or reformatted automatically. A field continues to hold the original Free‑version data structure until it is saved again in the Pro format.
How the Pro Version Handles Free‑Formatted Data at Runtime
When you get the field data using the get_field() or a corresponding ACF/SCF function, the Pro plugin intercepts the value before it reaches your template. This happens through the filter: acf/load_value/type=table_pro This filter detects whether the stored field data still uses the Free‑version structure. If so, it translates the Free‑formatted data into the Pro‑compatible structure on the fly. This translation happens only during output, not in the database itself.
When using get_post_meta(), the plugin’s automatic detection of Free vs. Pro data does not apply, so you must manually detect the data format and perform the necessary migration logic yourself.
Why the Database Is Not Automatically Updated
The plugin avoids rewriting stored data automatically because, once a Pro table field is saved anywhere in the admin (not on the field settings page), the Pro data structure is written to the database, and switching the field type back to the Free version is no longer possible yet. So, if the field type has been switched to Pro in the field group settings, you can still switch back to the Free version as long as no table fields from this fieldgroup have been saved in the admin using the Pro variant.