An ACF Pro Addon – Component Field

Description

Build it once, use it forever. A simple acf add-on that allows you to treat a field group as a component and reuse it in any other field groups.

Requirement*

  • WordPress 6+
  • ACF PRO 6+

Installation

  1. Login to your wordpress dashboard and navigate to Plugins > Add New.
  2. Click the Upload Plugin button beside the heading.
  3. Upload advanced-custom-fields-component_field.zip to the file upload area.
  4. Activate the plugin and have fun

When should I use this?

Have you ever found yourself creating the same set of fields in your project, say like, a custom lists menu, a testimonial block, sliders, or even a button? Well, this plugin might just be the one you need. Essentially, this plugin will allow you to only create that “same set of fields” once, and you can reuse it as many times as you want. Even better, if you want to add a new field in those “same set of fields” in the future, you only need to do it once, and it’ll apply to all the places you use it. See this example for details.

The concept – a reusable field

The concept is coming for the popular javascript library, React. A web page is really just built by a bunch of components and each component is independent. So, why can’t ACF be like that? A field group is built by different reusable components, each component has its own set of fields that should not be affect by another. You can put a component inside another component and inside another one. When you want to change something, you only need to change it once, and it’ll apply to all.

How it works?

When I started making this, I tried many different ways, but they all get stuck with the same problem: the values will get overwritten if you have more than 1. So, I took a step back and tried to find a way that won’t cause this issue. And it turned out, it already exists, the repeater field! The way repeater field works is, the sub_field’s key is combined with the parent field’s key with an index, like so, {parent_key}_{index}_{sub_field_key}. This way, when the value is save, the key is always different, and that’s why we can have a repeater field inside a repeater field.

The component field plugin is using the same logic, it’s treated as a repeater field, the values are consider sub_fields. By extending the functionality of the repeater field, we can also leverage the already built in functions. There’s no extra function you need to learn, no extra way of outputting the data. Everything is exactly the same as if you were using regular repeater field. See example for detail.

Why don’t give acf 4 a little love?

One reason is because, repeater doesn’t come free with acf 4, so this component field will need to rely on another paid plugin, I don’t feel comfortable about that. But the main reason is, the way acf 4 saves the fields and the way js is triggered in the backend. It’s not dynamic enough for us to swap the sub fields easily. If you are still using acf 4, you should really give acf 5 a try. I bet you’d love it and will never want to go back to acf 4.

The potentials

When you get a hang of it. You can prepare a list of components that you use commonly and export them to json files. Whenever you start a new project and you need the exact same component, you just need to import the component you already had, and modify it to suit your need, and you are good to go. Kinda like a DIY acf field without actually creating a full plugin. It also makes the complex field group extremely easy, as long as you are able to identify what should be a component and what’s not.

How to

Live Examples

Disclaimer

  1. When you doing nested components, make sure you don’t go crazy and create an infinite loop.
  2. If you are using acf’s local cache json file, make sure you sync it before editing the component fields, because sometimes (happens once a while), it’d be out of sync, and the saved value will be lost.
  3. When you have tabs in your component group, when including that component, make sure you use the “block” layout (which is default already). Otherwise the layout will go off.
  4. Depending on the server’s setting, if you nest too many component (like, a lot), you might hit the max_post_size or max_input_nesting_level limit.
  5. An unknown bug or a bug that has not been fixed might destroys your data. I’ve already tested most of the extreme cases, but might still have missed one or two. If you are doing something crazily complex, please backup your database first. If you lost your data by using this plugin irregularly, an unknown bug or a bug that has not been fixed might destroys your data, I do not take responsibility for it. If you want to go crazy with this plugin, use with caution.

Test Log

Tested up to version:
Wordpress 6.4.3
ACF Pro 6.2.7

Changelog

2.0.7 (2024/03/15)

– Fix a PHP warning related to version 8.3.

2.0.6 (2023/08/01)

– Fix a PHP warning related to version 8.2.

2.0.5

– (New) Now compatible with ACF PRO version 6 (2022-09-21).
– Added support for top level component field pagination (from repeater field).
– Added support for ACF PRO version 6 new layout and UI/UX.
– Added backward compatibility to continue support for ACF PRO version 5.

2.0.4

– Fix a bug where importing without component flag generates php errors.

2.0.3

– Minor update to code formatting per Codecanyon new requirement

2.0.2

– Fix a bug where converting to repeater field sometimes delete the component field group.
– Fix a WPML bug where field groups cache is trigger too early.
– Fix a bug where local acf-json folder contains location setting for component field group.

2.0.1

– Add import compatibility when using v1 export json file.
– Add admin tool to run migration manually (Custom Fields -> Tools).
– Add 2.0.1 migration to attempt to fix corrupted component fields when upgraded to component field v2 in incorrect order previously

2.0.0

– Complete rewrite for better performance, brand new hot features and small UX changes.
– Minimal requirement for ACF pro is now 5.7+ because of the javascript changes. Component field version 1 will still be supported for questions and help until end of 2018, but will no longer receive new updates.
– Core changes: V2 no longer uses custom post status, acf-component, to handle the component field. In stead, it uses meta value. (when you upgrade to 2.0, the plugin will run script to fix this for you)
– Core changes: the field group property ‘field_group_id’ has been renamed to ‘field_group_key’. (when you upgrade to 2.0, the plugin will run script to fix this for you)
– New feature: you can now convert existing repeater field into a component field (a new component field group will be created and the repeater field’s sub fields will be moved into it)
– New feature: you can now convert a component field to repeater field and optionally auto delete the component field after the conversion. (current component field will be changed to repeater, and the component field gorup’s fields will be duplicated as the repeater’s sub-fields)
– UX enhanced: You can now set the default component field settings on the component field group. (such as button label, min, max, layout)
– UX enhanced: In the list table, when you are in the component tab, it’ll now show you how many times the component has been used. This is useful if your site has a lot of old components, and not sure if it’s save to delete or not.
– UX enhanced: After you duplicate a component field group, it’ll now redirect you to the component tab, instead of the active tab.
– Performance enhanced: with the new JS in ACF pro 5.7, some of hacky js code for component field has been removed. Now the backend run a lot smoother.
– Code enhanced: plugin code has been completely rewrite for better performance and less hacky stuff. The file/folder structure is also reorganized for better readability.

1.0.14

-Fix importing/exporting bug for acf pro 5.6.5’s new “admin tool” framework.

1.0.13

-Fix field class constructor for ACF 5.6.0 release.

1.0.12

– Fix a bug where component add row event isn’t register properly when the field group metabox is added through ajax.

1.0.11

– Component field’s “this is a component” checkbox will now remain checked upon duplication.
– Fix wpml language duplication not selecting the proper component group. After language duplication, it’ll “try” to find the matching translated component field.
– Added /lang/acf-component_field-default.pot file  

1.0.10

–Add optional alternative styling for nested components. Huh?

1.0.9

-Fix php warning error when importing regular acf json file.

1.0.8

– Fix a copy-paste mistake that’ll cause warning error if wp_debug is on.

1.0.7

– Added plugin activation hook to fix component field not restore after updating plugin.

1.0.6

– Fix a bug where after updating a component field, acf_get_field_groups() doesn’t check the local json cache syncing properly.
– Fix a bug where single sync/bulk sync from local json cache doesn’t set the proper status.

1.0.5

– Add ability to read local php fields generated by “acf_add_local_field_group()” in the “select field group” dropdown.
– Fix a bug where if a component field is exported to a local php export, it cannot render the sub fields..

1.0.4

– Added German translation, thanks to Thomas. Added index.php to prevent directory listing.

1.0.3

– Updated plugin metadata to point to the live demo

1.0.2

– Fix backend javascript when having nested component field

1.0.1

– Fix a frontend value parsing issue.

1.0.0

– Initial release.