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

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

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

class-acf-field-button-group.php

347 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_button_group' ) ) :
13
14	class acf_field_button_group extends acf_field {
15
16
17	/**
18	* initialize()
19	*
20	* This function will setup the field type data
21	*
22	* @date 18/9/17
23	* @since 5.6.3
24	*
25	* @param n/a
26	* @return n/a
27	*/
28	function initialize() {
29
30	// vars
31	$this->name = 'button_group';
32	$this->label = __( 'Button Group', 'acf' );
33	$this->category = 'choice';
34	$this->description = __( 'A group of buttons with values that you specify, users can choose one option from the values provided.', 'acf' );
35	$this->preview_image = acf_get_url() . '/assets/images/field-type-previews/field-preview-button-group.png';
36	$this->doc_url = acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/button-group/', 'docs', 'field-type-selection' );
37	$this->defaults = array(
38	'choices' => array(),
39	'default_value' => '',
40	'allow_null' => 0,
41	'return_format' => 'value',
42	'layout' => 'horizontal',
43	);
44	}
45
46
47	/**
48	* Creates the field's input HTML
49	*
50	* @since 5.6.3
51	*
52	* @param array $field The field settings array
53	*/
54	public function render_field( $field ) {
55
56	// vars
57	$html = '';
58	$selected = null;
59	$buttons = array();
60	$value = esc_attr( $field['value'] );
61
62	// bail ealrly if no choices
63	if ( empty( $field['choices'] ) ) {
64	return;
65	}
66
67	// buttons
68	foreach ( $field['choices'] as $_value => $_label ) {
69
70	// checked
71	$checked = ( $value === esc_attr( $_value ) );
72	if ( $checked ) {
73	$selected = true;
74	}
75
76	// append
77	$buttons[] = array(
78	'name' => $field['name'],
79	'value' => $_value,
80	'label' => $_label,
81	'checked' => $checked,
82	'button_group' => true,
83	);
84	}
85
86
87	// maybe select initial value
88	if ( ! $field['allow_null'] && $selected === null ) {
89	$buttons[0]['checked'] = true;
90	}
91
92	// Ensure roving tabindex when allow_null is enabled and no selection yet.
93	if ( $field['allow_null'] && $selected === null && ! empty( $buttons ) ) {
94	$buttons[0]['tabindex'] = '0';
95	}
96
97	// div
98	$div = array(
99	'class' => 'acf-button-group',
100	'role' => 'radiogroup',
101	);
102
103	// Add aria-labelledby if field has an ID for proper screen reader announcement
104	if ( ! empty( $field['id'] ) ) {
105	$div['aria-labelledby'] = $field['id'] . '-label';
106	}
107
108	if ( 'vertical' === $field['layout'] ) {
109	$div['class'] .= ' -vertical';
110	}
111	if ( $field['class'] ) {
112	$div['class'] .= ' ' . $field['class'];
113	}
114	if ( $field['allow_null'] ) {
115	$div['data-allow_null'] = 1;
116	}
117
118	// hdden input
119	$html .= acf_get_hidden_input( array( 'name' => $field['name'] ) );
120
121	// open
122	$html .= '<div ' . acf_esc_attrs( $div ) . '>';
123
124	// loop
125	foreach ( $buttons as $button ) {
126
127	// checked
128	if ( $button['checked'] ) {
129	$button['checked'] = 'checked';
130	} else {
131	unset( $button['checked'] );
132	}
133
134	// append
135	$html .= acf_get_radio_input( $button );
136	}
137
138	// close
139	$html .= '</div>';
140
141	// return
142	echo $html; //phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- safe HTML, escaped by input building functions.
143	}
144
145
146	/**
147	* render_field_settings()
148	*
149	* Creates the field's settings HTML
150	*
151	* @date 18/9/17
152	* @since 5.6.3
153	*
154	* @param array $field The field settings array
155	* @return n/a
156	*/
157	function render_field_settings( $field ) {
158	// Encode choices (convert from array).
159	$field['choices'] = acf_encode_choices( $field['choices'] );
160
161	acf_render_field_setting(
162	$field,
163	array(
164	'label' => __( 'Choices', 'acf' ),
165	'instructions' => __( 'Enter each choice on a new line.', 'acf' ) . '<br />' . __( 'For more control, you may specify both a value and label like this:', 'acf' ) . '<br /><span class="acf-field-setting-example">' . __( 'red : Red', 'acf' ) . '</span>',
166	'type' => 'textarea',
167	'name' => 'choices',
168	)
169	);
170
171	acf_render_field_setting(
172	$field,
173	array(
174	'label' => __( 'Default Value', 'acf' ),
175	'instructions' => __( 'Appears when creating a new post', 'acf' ),
176	'type' => 'text',
177	'name' => 'default_value',
178	)
179	);
180
181	acf_render_field_setting(
182	$field,
183	array(
184	'label' => __( 'Return Value', 'acf' ),
185	'instructions' => __( 'Specify the returned value on front end', 'acf' ),
186	'type' => 'radio',
187	'name' => 'return_format',
188	'layout' => 'horizontal',
189	'choices' => array(
190	'value' => __( 'Value', 'acf' ),
191	'label' => __( 'Label', 'acf' ),
192	'array' => __( 'Both (Array)', 'acf' ),
193	),
194	)
195	);
196	}
197
198	/**
199	* Renders the field settings used in the "Validation" tab.
200	*
201	* @since 6.0
202	*
203	* @param array $field The field settings array.
204	* @return void
205	*/
206	function render_field_validation_settings( $field ) {
207	acf_render_field_setting(
208	$field,
209	array(
210	'label' => __( 'Allow Null', 'acf' ),
211	'instructions' => '',
212	'name' => 'allow_null',
213	'type' => 'true_false',
214	'ui' => 1,
215	)
216	);
217	}
218
219	/**
220	* Renders the field settings used in the "Presentation" tab.
221	*
222	* @since 6.0
223	*
224	* @param array $field The field settings array.
225	* @return void
226	*/
227	function render_field_presentation_settings( $field ) {
228	acf_render_field_setting(
229	$field,
230	array(
231	'label' => __( 'Layout', 'acf' ),
232	'instructions' => '',
233	'type' => 'radio',
234	'name' => 'layout',
235	'layout' => 'horizontal',
236	'choices' => array(
237	'horizontal' => __( 'Horizontal', 'acf' ),
238	'vertical' => __( 'Vertical', 'acf' ),
239	),
240	)
241	);
242	}
243
244	/**
245	* This filter is appied to the $field before it is saved to the database
246	*
247	* @date 18/9/17
248	* @since 5.6.3
249	*
250	* @param array $field The field array holding all the field options
251	* @return $field
252	*/
253	function update_field( $field ) {
254
255	return acf_get_field_type( 'radio' )->update_field( $field );
256	}
257
258
259	/**
260	* This filter is appied to the $value after it is loaded from the db
261	*
262	* @date 18/9/17
263	* @since 5.6.3
264	*
265	* @param mixed $value The value found in the database
266	* @param mixed $post_id The post ID from which the value was loaded from
267	* @param array $field The field array holding all the field options
268	* @return $value
269	*/
270	function load_value( $value, $post_id, $field ) {
271
272	return acf_get_field_type( 'radio' )->load_value( $value, $post_id, $field );
273	}
274
275
276	/**
277	* This function will translate field settings
278	*
279	* @date 18/9/17
280	* @since 5.6.3
281	*
282	* @param array $field The field array holding all the field options
283	* @return $field
284	*/
285	function translate_field( $field ) {
286
287	return acf_get_field_type( 'radio' )->translate_field( $field );
288	}
289
290
291	/**
292	* This filter is appied to the $value after it is loaded from the db and before it is returned to the template
293	*
294	* @date 18/9/17
295	* @since 5.6.3
296	*
297	* @param mixed $value The value found in the database
298	* @param mixed $post_id The post ID from which the value was loaded from
299	* @param array $field The field array holding all the field options
300	* @return $value
301	*/
302	function format_value( $value, $post_id, $field ) {
303
304	return acf_get_field_type( 'radio' )->format_value( $value, $post_id, $field );
305	}
306
307	/**
308	* Return the schema array for the REST API.
309	*
310	* @param array $field
311	* @return array
312	*/
313	function get_rest_schema( array $field ) {
314	$schema = parent::get_rest_schema( $field );
315
316	if ( isset( $field['default_value'] ) && '' !== $field['default_value'] ) {
317	$schema['default'] = $field['default_value'];
318	}
319
320	$schema['enum'] = acf_get_field_type( 'select' )->format_rest_choices( $field['choices'] );
321	$schema['enum'][] = null;
322
323	// Allow null via UI will value to empty string.
324	if ( ! empty( $field['allow_null'] ) ) {
325	$schema['enum'][] = '';
326	}
327
328	return $schema;
329	}
330
331	/**
332	* Returns an array of JSON-LD Property output types that are supported by this field type.
333	*
334	* @since 6.8
335	*
336	* @return string[]
337	*/
338	public function get_jsonld_output_types(): array {
339	return array( 'Text' );
340	}
341	}
342
343
344	// initialize
345	acf_register_field_type( 'acf_field_button_group' );
346	endif; // class_exists check
347