class-acf-field-group.php — Advanced Custom Fields (ACF®) 6.8.8

advanced-custom-fields / includes / fields / class-acf-field-group.php

advanced-custom-fields / includes / fields Last commit date

class-acf-field-group.php

738 lines

1	<?php
2	/**
3	* @package ACF
4	* @author WP Engine
5	*
6	* © 2026 Advanced Custom Fields (ACF®). All rights reserved.
7	* "ACF" is a trademark of WP Engine.
8	* Licensed under the GNU General Public License v2 or later.
9	* https://www.gnu.org/licenses/gpl-2.0.html
10	*/
11
12	if ( ! class_exists( 'acf_field__group' ) ) :
13	class acf_field__group extends acf_field {
14
15
16	/**
17	* This function will setup the field type data
18	*
19	* @type function
20	* @date 5/03/2014
21	* @since 5.0.0
22	*
23	* @param n/a
24	* @return n/a
25	*/
26	function initialize() {
27
28	// vars
29	$this->name = 'group';
30	$this->label = __( 'Group', 'acf' );
31	$this->category = 'layout';
32	$this->description = __( 'Provides a way to structure fields into groups to better organize the data and the edit screen.', 'acf' );
33	$this->preview_image = acf_get_url() . '/assets/images/field-type-previews/field-preview-group.png';
34	$this->doc_url = acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/group/', 'docs', 'field-type-selection' );
35	$this->supports = array(
36	'bindings' => false,
37	);
38	$this->defaults = array(
39	'sub_fields' => array(),
40	'layout' => 'block',
41	);
42	$this->have_rows = 'single';
43
44	// field filters
45	$this->add_field_filter( 'acf/prepare_field_for_export', array( $this, 'prepare_field_for_export' ) );
46	$this->add_field_filter( 'acf/prepare_field_for_import', array( $this, 'prepare_field_for_import' ) );
47	}
48
49
50	/**
51	* This filter is appied to the $field after it is loaded from the database
52	*
53	* @type filter
54	* @since 3.6
55	* @date 23/01/13
56	*
57	* @param $field - the field array holding all the field options
58	*
59	* @return $field - the field array holding all the field options
60	*/
61	function load_field( $field ) {
62
63	// vars
64	$sub_fields = acf_get_fields( $field );
65
66	// append
67	if ( $sub_fields ) {
68	$field['sub_fields'] = $sub_fields;
69	}
70
71	// return
72	return $field;
73	}
74
75
76	/**
77	* This filter is applied to the $value after it is loaded from the db
78	*
79	* @type filter
80	* @since 3.6
81	* @date 23/01/13
82	*
83	* @param $value (mixed) the value found in the database
84	* @param $post_id (mixed) the post_id from which the value was loaded
85	* @param $field (array) the field array holding all the field options
86	* @return $value
87	*/
88	function load_value( $value, $post_id, $field ) {
89
90	// bail early if no sub fields
91	if ( empty( $field['sub_fields'] ) ) {
92	return $value;
93	}
94
95	// modify names
96	$field = $this->prepare_field_for_db( $field );
97
98	// load sub fields
99	$value = array();
100
101	// loop
102	foreach ( $field['sub_fields'] as $sub_field ) {
103
104	// load
105	$value[ $sub_field['key'] ] = acf_get_value( $post_id, $sub_field );
106	}
107
108	// return
109	return $value;
110	}
111
112
113	/**
114	* This filter is appied to the $value after it is loaded from the db and before it is returned to the template
115	*
116	* @type filter
117	* @since 3.6
118	*
119	* @param mixed $value The value which was loaded from the database.
120	* @param mixed $post_id The $post_id from which the value was loaded.
121	* @param array $field The field array holding all the field options.
122	* @param boolean $escape_html Should the field return a HTML safe formatted value.
123	* @return mixed the modified value
124	*/
125	public function format_value( $value, $post_id, $field, $escape_html = false ) {
126	// bail early if no value
127	if ( empty( $value ) ) {
128	return false;
129	}
130
131	// modify names
132	$field = $this->prepare_field_for_db( $field );
133
134	// loop
135	foreach ( $field['sub_fields'] as $sub_field ) {
136
137	// extract value
138	$sub_value = acf_extract_var( $value, $sub_field['key'] );
139
140	// format value
141	$sub_value = acf_format_value( $sub_value, $post_id, $sub_field, $escape_html );
142
143	// append to $row
144	$value[ $sub_field['_name'] ] = $sub_value;
145	}
146
147	// return
148	return $value;
149	}
150
151
152	/**
153	* This filter is appied to the $value before it is updated in the db
154	*
155	* @type filter
156	* @since 3.6
157	* @date 23/01/13
158	*
159	* @param $value - the value which will be saved in the database
160	* @param $field - the field array holding all the field options
161	* @param $post_id - the post_id of which the value will be saved
162	*
163	* @return $value - the modified value
164	*/
165	function update_value( $value, $post_id, $field ) {
166
167	// bail early if no value
168	if ( ! acf_is_array( $value ) ) {
169	return null;
170	}
171
172	// bail early if no sub fields
173	if ( empty( $field['sub_fields'] ) ) {
174	return null;
175	}
176
177	// modify names
178	$field = $this->prepare_field_for_db( $field );
179
180	// loop
181	foreach ( $field['sub_fields'] as $sub_field ) {
182
183	// vars
184	$v = false;
185
186	// key (backend)
187	if ( isset( $value[ $sub_field['key'] ] ) ) {
188	$v = $value[ $sub_field['key'] ];
189
190	// name (frontend)
191	} elseif ( isset( $value[ $sub_field['_name'] ] ) ) {
192	$v = $value[ $sub_field['_name'] ];
193
194	// empty
195	} else {
196
197	// input is not set (hidden by conditioanl logic)
198	continue;
199	}
200
201	// update value
202	acf_update_value( $v, $post_id, $sub_field );
203	}
204
205	// return
206	return '';
207	}
208
209
210	/**
211	* This function will modify sub fields ready for update / load
212	*
213	* @type function
214	* @date 4/11/16
215	* @since 5.5.0
216	*
217	* @param $field (array)
218	* @return $field
219	*/
220	function prepare_field_for_db( $field ) {
221
222	// bail early if no sub fields
223	if ( empty( $field['sub_fields'] ) ) {
224	return $field;
225	}
226
227	// loop
228	foreach ( $field['sub_fields'] as &$sub_field ) {
229
230	// prefix name
231	$sub_field['name'] = $field['name'] . '_' . $sub_field['_name'];
232	}
233
234	// return
235	return $field;
236	}
237
238
239	/**
240	* Create the HTML interface for your field
241	*
242	* @param $field - an array holding all the field's data
243	*
244	* @type action
245	* @since 3.6
246	* @date 23/01/13
247	*/
248	function render_field( $field ) {
249
250	// bail early if no sub fields
251	if ( empty( $field['sub_fields'] ) ) {
252	return;
253	}
254
255	// load values
256	foreach ( $field['sub_fields'] as &$sub_field ) {
257
258	// add value
259	if ( isset( $field['value'][ $sub_field['key'] ] ) ) {
260
261	// this is a normal value
262	$sub_field['value'] = $field['value'][ $sub_field['key'] ];
263	} elseif ( isset( $sub_field['default_value'] ) ) {
264
265	// no value, but this sub field has a default value
266	$sub_field['value'] = $sub_field['default_value'];
267	}
268
269	// update prefix to allow for nested values
270	$sub_field['prefix'] = $field['name'];
271
272	// restore required
273	if ( $field['required'] ) {
274	$sub_field['required'] = 0;
275	}
276	}
277
278	// render
279	if ( $field['layout'] == 'table' ) {
280	$this->render_field_table( $field );
281	} else {
282	$this->render_field_block( $field );
283	}
284	}
285
286
287	/**
288	* description
289	*
290	* @type function
291	* @date 12/07/2016
292	* @since 5.4.0
293	*
294	* @param $post_id (int)
295	* @return $post_id (int)
296	*/
297	function render_field_block( $field ) {
298
299	// vars
300	$label_placement = ( $field['layout'] == 'block' ) ? 'top' : 'left';
301
302	// html
303	echo '<div class="acf-fields -' . esc_attr( $label_placement ) . ' -border">';
304
305	foreach ( $field['sub_fields'] as $sub_field ) {
306	acf_render_field_wrap( $sub_field );
307	}
308
309	echo '</div>';
310	}
311
312
313	/**
314	* description
315	*
316	* @type function
317	* @date 12/07/2016
318	* @since 5.4.0
319	*
320	* @param $post_id (int)
321	* @return $post_id (int)
322	*/
323	function render_field_table( $field ) {
324
325	?>
326	<table class="acf-table">
327	<thead>
328	<tr>
329	<?php
330	foreach ( $field['sub_fields'] as $sub_field ) :
331
332	// prepare field (allow sub fields to be removed)
333	$sub_field = acf_prepare_field( $sub_field );
334
335	// bail early if no field
336	if ( ! $sub_field ) {
337	continue;
338	}
339
340	// vars
341	$atts = array();
342	$atts['class'] = 'acf-th';
343	$atts['data-name'] = $sub_field['_name'];
344	$atts['data-type'] = $sub_field['type'];
345	$atts['data-key'] = $sub_field['key'];
346
347	// Add custom width
348	if ( $sub_field['wrapper']['width'] ) {
349	$atts['data-width'] = $sub_field['wrapper']['width'];
350	$atts['style'] = 'width: ' . $sub_field['wrapper']['width'] . '%;';
351	}
352
353	?>
354	<th <?php echo acf_esc_attrs( $atts ); ?>>
355	<?php acf_render_field_label( $sub_field ); ?>
356	<?php acf_render_field_instructions( $sub_field ); ?>
357	</th>
358	<?php endforeach; ?>
359	</tr>
360	</thead>
361	<tbody>
362	<tr class="acf-row">
363	<?php
364
365	foreach ( $field['sub_fields'] as $sub_field ) {
366	acf_render_field_wrap( $sub_field, 'td' );
367	}
368
369	?>
370	</tr>
371	</tbody>
372	</table>
373	<?php
374	}
375
376
377	/**
378	* Create extra options for your field. This is rendered when editing a field.
379	* The value of $field['name'] can be used (like bellow) to save extra data to the $field
380	*
381	* @type action
382	* @since 3.6
383	* @date 23/01/13
384	*
385	* @param $field - an array holding all the field's data
386	*/
387	function render_field_settings( $field ) {
388
389	// vars
390	$args = array(
391	'fields' => $field['sub_fields'],
392	'parent' => $field['ID'],
393	'is_subfield' => true,
394	);
395
396	?>
397	<div class="acf-field acf-field-setting-sub_fields" data-setting="group" data-name="sub_fields">
398	<div class="acf-label">
399	<label><?php esc_html_e( 'Sub Fields', 'acf' ); ?></label>
400	</div>
401	<div class="acf-input acf-input-sub">
402	<?php
403
404	acf_get_view( 'acf-field-group/fields', $args );
405
406	?>
407	</div>
408	</div>
409	<?php
410
411	// layout
412	acf_render_field_setting(
413	$field,
414	array(
415	'label' => __( 'Layout', 'acf' ),
416	'instructions' => __( 'Specify the style used to render the selected fields', 'acf' ),
417	'type' => 'radio',
418	'name' => 'layout',
419	'layout' => 'horizontal',
420	'choices' => array(
421	'block' => __( 'Block', 'acf' ),
422	'table' => __( 'Table', 'acf' ),
423	'row' => __( 'Row', 'acf' ),
424	),
425	)
426	);
427	}
428
429
430	/**
431	* description
432	*
433	* @type function
434	* @date 11/02/2014
435	* @since 5.0.0
436	*
437	* @param $post_id (int)
438	* @return $post_id (int)
439	*/
440	function validate_value( $valid, $value, $field, $input ) {
441
442	// bail early if no $value
443	if ( empty( $value ) ) {
444	return $valid;
445	}
446
447	// bail early if no sub fields
448	if ( empty( $field['sub_fields'] ) ) {
449	return $valid;
450	}
451
452	// loop
453	foreach ( $field['sub_fields'] as $sub_field ) {
454
455	// get sub field
456	$k = $sub_field['key'];
457
458	// bail early if value not set (conditional logic?)
459	if ( ! isset( $value[ $k ] ) ) {
460	continue;
461	}
462
463	// required
464	if ( $field['required'] ) {
465	$sub_field['required'] = 1;
466	}
467
468	// validate
469	acf_validate_value( $value[ $k ], $sub_field, "{$input}[{$k}]" );
470	}
471
472	// return
473	return $valid;
474	}
475
476
477	/**
478	* This filter is appied to the $field before it is duplicated and saved to the database
479	*
480	* @type filter
481	* @since 3.6
482	* @date 23/01/13
483	*
484	* @param $field - the field array holding all the field options
485	*
486	* @return $field - the modified field
487	*/
488	function duplicate_field( $field ) {
489
490	// get sub fields
491	$sub_fields = acf_extract_var( $field, 'sub_fields' );
492
493	// save field to get ID
494	$field = acf_update_field( $field );
495
496	// duplicate sub fields
497	acf_duplicate_fields( $sub_fields, $field['ID'] );
498
499	// return
500	return $field;
501	}
502
503	/**
504	* prepare_field_for_export
505	*
506	* Prepares the field for export.
507	*
508	* @date 11/03/2014
509	* @since 5.0.0
510	*
511	* @param array $field The field settings.
512	* @return array
513	*/
514	function prepare_field_for_export( $field ) {
515
516	// Check for sub fields.
517	if ( ! empty( $field['sub_fields'] ) ) {
518	$field['sub_fields'] = acf_prepare_fields_for_export( $field['sub_fields'] );
519	}
520	return $field;
521	}
522
523	/**
524	* prepare_field_for_import
525	*
526	* Returns a flat array of fields containing all sub fields ready for import.
527	*
528	* @date 11/03/2014
529	* @since 5.0.0
530	*
531	* @param array $field The field settings.
532	* @return array
533	*/
534	function prepare_field_for_import( $field ) {
535
536	// Check for sub fields.
537	if ( ! empty( $field['sub_fields'] ) ) {
538	$sub_fields = acf_extract_var( $field, 'sub_fields' );
539
540	// Modify sub fields.
541	foreach ( $sub_fields as $i => $sub_field ) {
542	$sub_fields[ $i ]['parent'] = $field['key'];
543	$sub_fields[ $i ]['menu_order'] = $i;
544	}
545
546	// Return array of [field, sub_1, sub_2, ...].
547	return array_merge( array( $field ), $sub_fields );
548	}
549	return $field;
550	}
551
552
553	/**
554	* Called when deleting this field's value.
555	*
556	* @date 1/07/2015
557	* @since 5.2.3
558	*
559	* @param mixed $post_id The post ID being saved
560	* @param string $meta_key The field name as seen by the DB
561	* @param array $field The field settings
562	* @return void
563	*/
564	function delete_value( $post_id, $meta_key, $field ) {
565
566	// bail early if no sub fields
567	if ( empty( $field['sub_fields'] ) ) {
568	return null;
569	}
570
571	// modify names
572	$field = $this->prepare_field_for_db( $field );
573
574	// loop
575	foreach ( $field['sub_fields'] as $sub_field ) {
576	acf_delete_value( $post_id, $sub_field );
577	}
578	}
579
580	/**
581	* delete_field
582	*
583	* Called when deleting a field of this type.
584	*
585	* @date 8/11/18
586	* @since 5.8.0
587	*
588	* @param arra $field The field settings.
589	* @return void
590	*/
591	function delete_field( $field ) {
592
593	// loop over sub fields and delete them
594	if ( $field['sub_fields'] ) {
595	foreach ( $field['sub_fields'] as $sub_field ) {
596	acf_delete_field( $sub_field['ID'] );
597	}
598	}
599	}
600
601	/**
602	* Return the schema array for the REST API.
603	*
604	* @param array $field
605	* @return array
606	*/
607	public function get_rest_schema( array $field ) {
608	$schema = array(
609	'type' => array( 'object', 'null' ),
610	'properties' => array(),
611	'required' => ! empty( $field['required'] ),
612	);
613
614	foreach ( $field['sub_fields'] as $sub_field ) {
615	if ( $sub_field_schema = acf_get_field_rest_schema( $sub_field ) ) {
616	$schema['properties'][ $sub_field['name'] ] = $sub_field_schema;
617	}
618	}
619
620	return $schema;
621	}
622
623	/**
624	* Apply basic formatting to prepare the value for default REST output.
625	*
626	* @param mixed $value
627	* @param integer\|string $post_id
628	* @param array $field
629	* @return array\|mixed
630	*/
631	public function format_value_for_rest( $value, $post_id, array $field ) {
632	if ( empty( $value ) \|\| ! is_array( $value ) \|\| empty( $field['sub_fields'] ) ) {
633	return $value;
634	}
635
636	// Loop through each row and within that, each sub field to process sub fields individually.
637	foreach ( $field['sub_fields'] as $sub_field ) {
638
639	// Extract the sub field 'field_key'=>'value' pair from the $value and format it.
640	$sub_value = acf_extract_var( $value, $sub_field['key'] );
641	$sub_value = acf_format_value_for_rest( $sub_value, $post_id, $sub_field );
642
643	// Add the sub field value back to the $value but mapped to the field name instead
644	// of the key reference.
645	$value[ $sub_field['name'] ] = $sub_value;
646	}
647
648	return $value;
649	}
650
651	/**
652	* Returns an array of JSON-LD Property output types that are supported by this field type.
653	*
654	* @since 6.8
655	*
656	* @return string[]
657	*/
658	public function get_jsonld_output_types(): array {
659	return array( 'Thing' );
660	}
661
662	/**
663	* Formats the field value for JSON-LD output.
664	*
665	* @since 6.8.0
666	*
667	* @param mixed $value The value of the field.
668	* @param integer\|string $post_id The ID of the post.
669	* @param array $field The field array.
670	* @return mixed
671	*/
672	public function format_value_for_jsonld( $value, $post_id, $field ) {
673	if ( empty( $value ) \|\| ! is_array( $value ) \|\| empty( $field['sub_fields'] ) ) {
674	return null;
675	}
676
677	// Get output format with fallback.
678	$output_format = $field['schema_output_format'] ?? '';
679	if ( empty( $output_format ) ) {
680	$property = $field['schema_property'] ?? '';
681	$output_format = \ACF\AI\GEO\Schema::get_default_output_format( $this->name, $property );
682	}
683
684	// Build the JSON-LD object.
685	$result = array();
686
687	// Add @type if we have a specific output format.
688	if ( ! empty( $output_format ) ) {
689	$result['@type'] = $output_format;
690	}
691
692	// Modify names for DB access.
693	$field = $this->prepare_field_for_db( $field );
694
695	// Process each sub field.
696	foreach ( $field['sub_fields'] as $sub_field ) {
697	// Get the sub field value.
698	$sub_value = $value[ $sub_field['key'] ] ?? $value[ $sub_field['_name'] ] ?? null;
699
700	if ( null === $sub_value ) {
701	continue;
702	}
703
704	// Check if sub field has a schema property mapping.
705	$schema_property = $sub_field['schema_property'] ?? '';
706
707	if ( empty( $schema_property ) ) {
708	// No schema property - skip this field for JSON-LD output.
709	continue;
710	}
711
712	// Parse qualified property (e.g., "Thing.name" -> "name") to strip type prefix.
713	$property_name = \ACF\AI\GEO\Schema::get_property_name( $schema_property );
714
715	// Format the sub field value for JSON-LD.
716	$formatted_value = \ACF\AI\GEO\GEO::format_field_value_for_jsonld( $sub_value, $sub_field );
717
718	if ( null !== $formatted_value ) {
719	$result[ $property_name ] = $formatted_value;
720	}
721	}
722
723	// Only return if we have content beyond @type.
724	if ( count( $result ) > 1 \|\| ( count( $result ) === 1 && ! isset( $result['@type'] ) ) ) {
725	return $result;
726	}
727
728	return null;
729	}
730	}
731
732
733	// initialize
734	acf_register_field_type( 'acf_field__group' );
735	endif; // class_exists check
736
737	?>
738