class-acf-field-checkbox.php — Secure Custom Fields 6.9.1

secure-custom-fields / includes / fields / class-acf-field-checkbox.php

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

class-acf-field-checkbox.php

611 lines

1	<?php
2
3	if ( ! class_exists( 'acf_field_checkbox' ) ) :
4
5	class acf_field_checkbox extends acf_field {
6
7	/**
8	* A local store of all values for de-duplication.
9	*
10	* @var array
11	*/
12	private array $_values; //phpcs:ignore PSR2.Classes.PropertyDeclaration.Underscore -- backwards compatibility.
13
14	/**
15	* An internal boolean tracking if all checkboxes are checked.
16	*
17	* @var boolean
18	*/
19	private bool $_all_checked; //phpcs:ignore PSR2.Classes.PropertyDeclaration.Underscore -- backwards compatibility.
20
21	/**
22	* This function will setup the field type data
23	*
24	* @type function
25	* @date 5/03/2014
26	* @since ACF 5.0.0
27	*
28	* @param n/a
29	* @return n/a
30	*/
31	function initialize() {
32
33	// vars
34	$this->name = 'checkbox';
35	$this->label = __( 'Checkbox', 'secure-custom-fields' );
36	$this->category = 'choice';
37	$this->description = __( 'A group of checkbox inputs that allow the user to select one, or multiple values that you specify.', 'secure-custom-fields' );
38	$this->preview_image = acf_get_url() . '/assets/images/field-type-previews/field-preview-checkbox.png';
39	$this->doc_url = 'https://developer.wordpress.org/secure-custom-fields/features/fields/checkbox/';
40	$this->tutorial_url = 'https://developer.wordpress.org/secure-custom-fields/features/fields/checkbox/checkbox-tutorial/';
41	$this->defaults = array(
42	'layout' => 'vertical',
43	'choices' => array(),
44	'default_value' => '',
45	'allow_custom' => 0,
46	'save_custom' => 0,
47	'toggle' => 0,
48	'return_format' => 'value',
49	'custom_choice_button_text' => __( 'Add new choice', 'secure-custom-fields' ),
50	);
51	}
52
53
54	/**
55	* Create the HTML interface for your field
56	*
57	* @param $field (array) the $field being rendered
58	*
59	* @type action
60	* @since ACF 3.6
61	* @date 23/01/13
62	*
63	* @param $field (array) the $field being edited
64	* @return n/a
65	*/
66	function render_field( $field ) {
67
68	// reset vars
69	$this->_values = array();
70	$this->_all_checked = true;
71
72	// ensure array
73	$field['value'] = acf_get_array( $field['value'] );
74	$field['choices'] = acf_get_array( $field['choices'] );
75
76	// hidden input
77	acf_hidden_input( array( 'name' => $field['name'] ) );
78
79	// vars
80	$li = '';
81	$ul = array(
82	'class' => 'acf-checkbox-list',
83	'role' => 'group',
84	);
85
86	// Add aria-labelledby if field has an ID for proper screen reader announcement
87	if ( ! empty( $field['id'] ) ) {
88	$ul['aria-labelledby'] = $field['id'] . '-label';
89	}
90
91	// append to class
92	$ul['class'] .= ' ' . ( 'horizontal' === acf_maybe_get( $field, 'layout' ) ? 'acf-hl' : 'acf-bl' );
93	$ul['class'] .= ' ' . acf_maybe_get( $field, 'class', '' );
94
95	// checkbox saves an array
96	if ( acf_maybe_get( $field, 'name' ) ) {
97	$field['name'] .= '[]';
98	}
99
100	// choices
101	$choices = acf_maybe_get( $field, 'choices', array() );
102	if ( ! empty( $choices ) ) {
103
104	// choices
105	$li .= $this->render_field_choices( $field );
106
107	// toggle
108	if ( acf_maybe_get( $field, 'toggle' ) ) {
109	$li = $this->render_field_toggle( $field ) . $li;
110	}
111	}
112
113	// custom
114	if ( isset( $field['allow_custom'] ) && $field['allow_custom'] ) {
115	$li .= $this->render_field_custom( $field );
116	}
117
118	// return
119	echo '<ul ' . acf_esc_attrs( $ul ) . '>' . "\n" . $li . '</ul>' . "\n"; //phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- escaped by specific render methods above.
120	}
121
122
123	/**
124	* description
125	*
126	* @type function
127	* @date 15/7/17
128	* @since ACF 5.6.0
129	*
130	* @param $post_id (int)
131	* @return $post_id (int)
132	*/
133	function render_field_choices( $field ) {
134
135	// walk
136	return $this->walk( $field['choices'], $field );
137	}
138
139	/**
140	* Validates values for the checkbox field
141	*
142	* @since ACF 6.0.0
143	*
144	* @param boolean $valid If the field is valid.
145	* @param mixed $value The value to validate.
146	* @param array $field The main field array.
147	* @param string $input The input element's name attribute.
148	* @return boolean
149	*/
150	public function validate_value( $valid, $value, $field, $input ) {
151	if ( ! is_array( $value ) \|\| empty( $field['allow_custom'] ) ) {
152	return $valid;
153	}
154
155	foreach ( $value as $value ) {
156	if ( empty( $value ) && $value !== '0' ) {
157	return __( 'Checkbox custom values cannot be empty. Uncheck any empty values.', 'secure-custom-fields' );
158	}
159	}
160
161	return $valid;
162	}
163
164	/**
165	* description
166	*
167	* @type function
168	* @date 15/7/17
169	* @since ACF 5.6.0
170	*
171	* @param $post_id (int)
172	* @return $post_id (int)
173	*/
174	function render_field_toggle( $field ) {
175
176	// vars
177	$atts = array(
178	'type' => 'checkbox',
179	'class' => 'acf-checkbox-toggle',
180	'label' => __( 'Toggle All', 'secure-custom-fields' ),
181	);
182
183	// custom label
184	$toggle = acf_maybe_get( $field, 'toggle' );
185	if ( is_string( $toggle ) ) {
186	$atts['label'] = $toggle;
187	}
188
189	// checked
190	if ( $this->_all_checked ) {
191	$atts['checked'] = 'checked';
192	}
193
194	// return
195	return '<li>' . acf_get_checkbox_input( $atts ) . '</li>' . "\n";
196	}
197
198
199	/**
200	* description
201	*
202	* @type function
203	* @date 15/7/17
204	* @since ACF 5.6.0
205	*
206	* @param $post_id (int)
207	* @return $post_id (int)
208	*/
209	function render_field_custom( $field ) {
210
211	// vars
212	$html = '';
213
214	// loop
215	$value = acf_maybe_get( $field, 'value', array() );
216	if ( is_array( $value ) ) {
217	foreach ( $value as $item ) {
218
219	// ignore if already exists
220	$choices = acf_maybe_get( $field, 'choices', array() );
221	if ( isset( $choices[ $item ] ) ) {
222	continue;
223	}
224
225	// vars
226	$esc_value = esc_attr( $item );
227	$text_input = array(
228	'name' => acf_maybe_get( $field, 'name', '' ),
229	'value' => $item,
230	);
231
232	// bail early if choice already exists
233	if ( in_array( $esc_value, $this->_values, true ) ) {
234	continue;
235	}
236
237	// append
238	$html .= '<li><input class="acf-checkbox-custom" type="checkbox" checked="checked" />' . acf_get_text_input( $text_input ) . '</li>' . "\n";
239	}
240	}
241
242	// append button
243	// We need to check if is better to just not display the li if the button text is empty. But for now let's keep it as stable as possible.
244	$html .= '<li><a href="#" class="button acf-add-checkbox">' . esc_attr( acf_maybe_get( $field, 'custom_choice_button_text', '' ) ) . '</a></li>' . "\n";
245
246	// return
247	return $html;
248	}
249
250
251	function walk( $choices = array(), $args = array(), $depth = 0 ) {
252
253	// bail early if no choices
254	if ( empty( $choices ) ) {
255	return '';
256	}
257
258	// defaults
259	$args = wp_parse_args(
260	$args,
261	array(
262	'id' => '',
263	'type' => 'checkbox',
264	'name' => '',
265	'value' => array(),
266	'disabled' => array(),
267	)
268	);
269
270	// vars
271	$html = '';
272
273	// sanitize values for 'selected' matching
274	if ( $depth == 0 ) {
275	$args['value'] = array_map( 'esc_attr', $args['value'] );
276	$args['disabled'] = array_map( 'esc_attr', $args['disabled'] );
277	}
278
279	// loop
280	foreach ( $choices as $value => $label ) {
281
282	// open
283	$html .= '<li>';
284
285	// optgroup
286	if ( is_array( $label ) ) {
287	$html .= '<ul>' . "\n";
288	$html .= $this->walk( $label, $args, $depth + 1 );
289	$html .= '</ul>';
290
291	// option
292	} else {
293
294	// vars
295	$esc_value = esc_attr( $value );
296	$atts = array(
297	'id' => $args['id'] . '-' . str_replace( ' ', '-', $value ),
298	'type' => $args['type'],
299	'name' => $args['name'],
300	'value' => $value,
301	'label' => $label,
302	);
303
304	// selected
305	if ( in_array( $esc_value, $args['value'] ) ) {
306	$atts['checked'] = 'checked';
307	} else {
308	$this->_all_checked = false;
309	}
310
311	// disabled
312	if ( in_array( $esc_value, $args['disabled'] ) ) {
313	$atts['disabled'] = 'disabled';
314	}
315
316	// store value added
317	$this->_values[] = $esc_value;
318
319	// append
320	$html .= acf_get_checkbox_input( $atts );
321	}
322
323	// close
324	$html .= '</li>' . "\n";
325	}
326
327	// return
328	return $html;
329	}
330
331
332
333	/**
334	* Create extra options for your field. This is rendered when editing a field.
335	* The value of $field['name'] can be used (like bellow) to save extra data to the $field
336	*
337	* @type action
338	* @since ACF 3.6
339	* @date 23/01/13
340	*
341	* @param $field - an array holding all the field's data
342	*/
343	function render_field_settings( $field ) {
344	// Encode choices (convert from array).
345	$field['choices'] = acf_encode_choices( $field['choices'] );
346	$field['default_value'] = acf_encode_choices( $field['default_value'], false );
347
348	acf_render_field_setting(
349	$field,
350	array(
351	'label' => __( 'Choices', 'secure-custom-fields' ),
352	'instructions' => __( 'Enter each choice on a new line.', 'secure-custom-fields' ) . '<br />' . __( 'For more control, you may specify both a value and label like this:', 'secure-custom-fields' ) . '<br /><span class="acf-field-setting-example">' . __( 'red : Red', 'secure-custom-fields' ) . '</span>',
353	'type' => 'textarea',
354	'name' => 'choices',
355	)
356	);
357
358	acf_render_field_setting(
359	$field,
360	array(
361	'label' => __( 'Default Value', 'secure-custom-fields' ),
362	'instructions' => __( 'Enter each default value on a new line', 'secure-custom-fields' ),
363	'type' => 'textarea',
364	'name' => 'default_value',
365	)
366	);
367
368	acf_render_field_setting(
369	$field,
370	array(
371	'label' => __( 'Return Value', 'secure-custom-fields' ),
372	'instructions' => __( 'Specify the returned value on front end', 'secure-custom-fields' ),
373	'type' => 'radio',
374	'name' => 'return_format',
375	'layout' => 'horizontal',
376	'choices' => array(
377	'value' => __( 'Value', 'secure-custom-fields' ),
378	'label' => __( 'Label', 'secure-custom-fields' ),
379	'array' => __( 'Both (Array)', 'secure-custom-fields' ),
380	),
381	)
382	);
383	}
384
385	/**
386	* Renders the field settings used in the "Validation" tab.
387	*
388	* @since ACF 6.0
389	*
390	* @param array $field The field settings array.
391	* @return void
392	*/
393	function render_field_validation_settings( $field ) {
394	acf_render_field_setting(
395	$field,
396	array(
397	'label' => __( 'Allow Custom Values', 'secure-custom-fields' ),
398	'name' => 'allow_custom',
399	'type' => 'true_false',
400	'ui' => 1,
401	'instructions' => __( "Allow 'custom' values to be added", 'secure-custom-fields' ),
402	)
403	);
404
405	acf_render_field_setting(
406	$field,
407	array(
408	'label' => __( 'Save Custom Values', 'secure-custom-fields' ),
409	'name' => 'save_custom',
410	'type' => 'true_false',
411	'ui' => 1,
412	'instructions' => __( "Save 'custom' values to the field's choices", 'secure-custom-fields' ),
413	'conditions' => array(
414	'field' => 'allow_custom',
415	'operator' => '==',
416	'value' => 1,
417	),
418	)
419	);
420	}
421
422	/**
423	* Renders the field settings used in the "Presentation" tab.
424	*
425	* @since ACF 6.0
426	*
427	* @param array $field The field settings array.
428	* @return void
429	*/
430	function render_field_presentation_settings( $field ) {
431	acf_render_field_setting(
432	$field,
433	array(
434	'label' => __( 'Layout', 'secure-custom-fields' ),
435	'instructions' => '',
436	'type' => 'radio',
437	'name' => 'layout',
438	'layout' => 'horizontal',
439	'choices' => array(
440	'vertical' => __( 'Vertical', 'secure-custom-fields' ),
441	'horizontal' => __( 'Horizontal', 'secure-custom-fields' ),
442	),
443	)
444	);
445
446	acf_render_field_setting(
447	$field,
448	array(
449	'label' => __( 'Add Toggle All', 'secure-custom-fields' ),
450	'instructions' => __( 'Prepend an extra checkbox to toggle all choices', 'secure-custom-fields' ),
451	'name' => 'toggle',
452	'type' => 'true_false',
453	'ui' => 1,
454	)
455	);
456	}
457
458	/**
459	* This filter is applied to the $field before it is saved to the database
460	*
461	* @type filter
462	* @since ACF 3.6
463	* @date 23/01/13
464	*
465	* @param $field - the field array holding all the field options
466	* @param $post_id - the field group ID (post_type = acf)
467	*
468	* @return $field - the modified field
469	*/
470	function update_field( $field ) {
471
472	// Decode choices (convert to array).
473	$field['choices'] = acf_decode_choices( $field['choices'] );
474	$field['default_value'] = acf_decode_choices( $field['default_value'], true );
475	return $field;
476	}
477
478
479	/**
480	* Filters the $value before it is updated in the db.
481	*
482	* @since ACF 3.6
483	* @date 23/01/13
484	*
485	* @param mixed $value The value which will be saved in the database.
486	* @param integer\|string $post_id The post_id of which the value will be saved.
487	* @param array $field The field array holding all the field options.
488	*
489	* @return mixed
490	*/
491	function update_value( $value, $post_id, $field ) {
492	// bail early if is empty
493	if ( empty( $value ) ) {
494	return $value;
495	}
496
497	// select -> update_value()
498	$value = acf_get_field_type( 'select' )->update_value( $value, $post_id, $field );
499
500	// save_custom
501	if ( $field['save_custom'] && scf_current_user_has_capability() ) {
502
503	// get raw $field (may have been changed via repeater field)
504	// if field is local, it won't have an ID
505	$selector = $field['ID'] ? $field['ID'] : $field['key'];
506	$field = acf_get_field( $selector );
507	if ( ! $field ) {
508	return false;
509	}
510
511	// bail early if no ID (JSON only)
512	if ( ! $field['ID'] ) {
513	return $value;
514	}
515
516	acf_get_field_type( 'select' )->append_user_choices_to_field( $value, $post_id, $field );
517	}
518
519	// return
520	return $value;
521	}
522
523
524	/**
525	* This function will translate field settings
526	*
527	* @type function
528	* @date 8/03/2016
529	* @since ACF 5.3.2
530	*
531	* @param $field (array)
532	* @return $field
533	*/
534	function translate_field( $field ) {
535
536	return acf_get_field_type( 'select' )->translate_field( $field );
537	}
538
539
540	/**
541	* This filter is applied to the $value after it is loaded from the db and before it is returned to the template
542	*
543	* @type filter
544	* @since ACF 3.6
545	* @date 23/01/13
546	*
547	* @param $value (mixed) the value which was loaded from the database
548	* @param $post_id (mixed) the post_id from which the value was loaded
549	* @param $field (array) the field array holding all the field options
550	*
551	* @return $value (mixed) the modified value
552	*/
553	function format_value( $value, $post_id, $field ) {
554
555	// Bail early if is empty.
556	if ( acf_is_empty( $value ) ) {
557	return array();
558	}
559
560	// Always convert to array of items.
561	$value = acf_array( $value );
562
563	// Return.
564	return acf_get_field_type( 'select' )->format_value( $value, $post_id, $field );
565	}
566
567	/**
568	* Return the schema array for the REST API.
569	*
570	* @param array $field
571	* @return array
572	*/
573	public function get_rest_schema( array $field ) {
574	$schema = array(
575	'type' => array( 'integer', 'string', 'array', 'null' ),
576	'required' => isset( $field['required'] ) && $field['required'],
577	'items' => array(
578	'type' => array( 'string', 'integer' ),
579	),
580	);
581
582	if ( isset( $field['default_value'] ) && '' !== $field['default_value'] ) {
583	$schema['default'] = $field['default_value'];
584	}
585
586	// If we allow custom values, nothing else to do here.
587	if ( ! empty( $field['allow_custom'] ) ) {
588	return $schema;
589	}
590
591	$schema['items']['enum'] = acf_get_field_type( 'select' )->format_rest_choices( $field['choices'] );
592
593	return $schema;
594	}
595
596	/**
597	* Returns an array of JSON-LD Property output types that are supported by this field type.
598	*
599	* @since 6.8
600	*
601	* @return string[]
602	*/
603	public function get_jsonld_output_types(): array {
604	return array( 'Text' );
605	}
606	}
607
608	// initialize
609	acf_register_field_type( 'acf_field_checkbox' );
610	endif; // class_exists check
611