Clone

Documentation Field Types Clone

Overview

The clone field allows you to select and display existing fields. It does not duplicate any fields in the DB, instead, it loads and displays the selected fields at run-time.

You may also select one (or more) field groups making it possible to load in ‘module’ groups. A good example of this can be seen with the screenshots below where a single field group is created for ‘Button’ information. This field group is then ‘cloned’ when a button is needed.

The clone field may be used in one of two ways. It can replace itself with the selected fields (seamless) or display the selected fields as a group of sub fields.

Demo

Changelog

• Added in version 5.4.0

Settings

Template usage

Loading the value of a cloned field is the same as loading a normal field. If using the ‘Group’ display setting, you may also load all cloned values as an array by loading the ‘Clone field’ itself.

Some of the following examples use a clone field called ‘main_button’ which is cloning a field group called ‘Button’. The ‘Button’ field group contains 2 fields called ‘text’ and ‘url’.

Basic

This example shows how to load a clone field value with the following default settings. Note that these settings will essentially replace the clone field with the selected fields:

• Name: main_button
• Display: seamless
• Prefix Names: no
• Fields: A field group called ‘Button’ described above

<?php 
	
$text = get_field('text');
$url = get_field('url');

?>

Prefix Field Names

This example shows how to load a clone field value with the following ‘group’ settings. Note that these settings will render the ‘button’ fields within a group and prefix the field names. All values will be saved / loaded with the name prefix ‘main_button_’

• Name: main_button
• Display: group
• Prefix Names: yes
• Fields: A field group called ‘Button’ described above

<?php 

$text = get_field('main_button_text');
$url = get_field('main_button_url');

?>

Using the ‘Group’ display setting will allow ACF to load the clone field values as an array like so.

<?php 

$button = get_field('main_button');

$text = $button['text'];
$url = $button['url'];

?>

Sub fields

Clone fields may also be used within a repeater or flexible content field. This example shows the same ‘main_button’ clone field (from the previous example) used within a repeater field.

<?php 

if( have_rows('slides') ) {
	
	while( have_rows('slides') ) {
		
		// increment row
		the_row();
		
		
		// vars
		$button = get_sub_field('button');
		
		
		// ...
		
	}
	
}

?>

Limitations

The clone field contains a few limitations. These limitations are found in edge cases when using clone fields within a repeater or flexible content field.

1. multiple cloned sub fields

A cloned sub field may not be able to save it’s value if it exists alongside another instance of itself. For example, imagine a repeater field (called ‘Row’) containing 2 clone fields both cloning in the same field (called ‘Cell’). Even if both clone fields use the ‘Prefix Name’ setting to make each ‘Cell’ have a unique name, they both use the same field_key, so they will override each-other during save.

2. have_rows() nested clone field

The have_rows() function will return false when loading a cloned sub field using the ‘Display = Block’ setting. Please note that using the ‘Seamless’ display setting will allow sub have_rows() loops to work as expected.

Notes

Data structure

The clone field does not change the data structure when saving values to the DB. The only change comes from the ‘Prepend field name’ setting. Values are not saved as an array, but are saved as normal individual field values. This means that meta queries are possible as per normal.

Data conflicts

It is possible to create data conflicts by cloning a field with a name already used in the group. This is the same issue as creating 2 fields using the same name. Please use the ‘Prefix Field Names’ setting when appropriate to avoid this.

A good rule of thumb is to use the ‘Prefix Field Names’ setting when choosing the ‘Group’ display setting, and the opposite when using the ‘Seamless’ group setting.

Disabled field groups

It is possible to clone a field group that has is set to ‘Disabled’. Disabling a field group prevents it from being loaded on a post edit page, which is a good idea when making ‘module’ groups.

Cloning a clone

It is possible to clone a clone field. This may sound extreme, but it can be a useful feature in specific scenarios. For example, you may be creating a page builder with the flexible content field and find that each layout contains the same ‘settings’ fields. Instead of duplicating these ‘settings’ fields in each layout (and the headache of maintaining changes to these fields across multiple layouts), you could define all ‘settings’ fields in the first layout only. The second layout could use a clone field to clone these ‘settings’ fields. The third layout could use a clone field to clone the one defined in the second layout.

The benefit of this is that if you add a new ‘setting’ to the first layout, you only need to update the clone field in your second layout. All other clone fields (in layout 3, 4, etc) will mimic this and show the new ‘settings’ field!