code-snippets / php / settings / class-setting-field.php

class-setting-field.php in Code Snippets 3.7.0, at php/settings/class-setting-field.php

268 lines 6.4 KB

Raw Download Zip

1	<?php
2	/**
3	* This file handles rendering the settings fields
4	*
5	* @since 2.0.0
6	* @package Code_Snippets
7	* @subpackage Settings
8	*/
9
10	namespace Code_Snippets\Settings;
11
12	/**
13	* Represents a single setting field
14	*
15	* @property-read string $desc Field description.
16	* @property-read string $label Field label.
17	* @property-read string $type Field type.
18	* @property-read string $name Setting name.
19	*
20	* @property-read int $min Minimum value (for numerical inputs).
21	* @property-read int $max Maximum value(for numerical inputs).
22	* @property-read array<string, string> $options List of options for a select or checkboxes field.
23	* @property-read callable $render_callback Custom function to use when rendering a callback field.
24	* @property-read callable $sanitize_callback Custom function to use when sanitize the setting value.
25	* @property-read mixed $default Default setting value.
26	*
27	* @property-read string $input_name Value of `name` HTML attribute on an input element.
28	* @property-read string $element_id
29	*/
30	class Setting_Field {
31
32	/**
33	* Input field identifier.
34	*
35	* @var string
36	*/
37	private string $field_id;
38
39	/**
40	* Settings section identifier.
41	*
42	* @var string
43	*/
44	private string $section;
45
46	/**
47	* List of possible arguments.
48	*
49	* @var array<string, mixed>
50	*/
51	private array $args = array(
52	'desc' => '',
53	'label' => '',
54	'min' => null,
55	'max' => null,
56	'options' => [],
57	);
58
59	/**
60	* Class constructor.
61	*
62	* @param string $section_id Settings section identifier.
63	* @param string $field_id Setting field identifier.
64	* @param array<string, mixed> $args The setting field attributes.
65	*/
66	public function __construct( string $section_id, string $field_id, array $args ) {
67	$this->field_id = $field_id;
68	$this->section = $section_id;
69	$this->args = array_merge( $this->args, $args );
70	}
71
72	/**
73	* Retrieve a single setting attribute.
74	*
75	* @param string $argument Attribute name.
76	*
77	* @return mixed Attribute value.
78	*/
79	public function __get( string $argument ) {
80
81	if ( 'input_name' === $argument ) {
82	return sprintf( '%s[%s][%s]', OPTION_NAME, $this->section, $this->field_id );
83	}
84
85	return $this->args[ $argument ];
86	}
87
88	/**
89	* Retrieve the saved value for this setting.
90	*
91	* @return mixed
92	*/
93	private function get_saved_value() {
94	return get_setting( $this->section, $this->field_id );
95	}
96
97	/**
98	* Render the setting field
99	*/
100	public function render() {
101	$method_name = 'render_' . $this->type . '_field';
102
103	if ( method_exists( $this, $method_name ) ) {
104	call_user_func( array( $this, $method_name ) );
105	} else {
106	// Error message, not necessary to translate.
107	printf( 'Cannot render a %s field.', esc_html( $this->type ) );
108	return;
109	}
110
111	if ( $this->desc ) {
112	echo '<p class="description">', wp_kses_post( $this->desc ), '</p>';
113	}
114	}
115
116	/**
117	* Render a callback field.
118	*/
119	public function render_callback_field() {
120	call_user_func( $this->render_callback );
121	}
122
123	/**
124	* Render a single checkbox field.
125	*
126	* @param string $input_name Input name.
127	* @param string $label Input label.
128	* @param boolean $checked Whether the checkbox should be checked.
129	*/
130	private static function render_checkbox( string $input_name, string $label, bool $checked ) {
131
132	$checkbox = sprintf(
133	'<input type="checkbox" name="%s"%s>',
134	esc_attr( $input_name ),
135	checked( $checked, true, false )
136	);
137
138	$kses = [
139	'input' => [
140	'type' => [],
141	'name' => [],
142	'checked' => [],
143	],
144	];
145
146	if ( $label ) {
147	printf(
148	'<label>%s %s</label>',
149	wp_kses( $checkbox, $kses ),
150	wp_kses_post( $label )
151	);
152	} else {
153	echo wp_kses( $checkbox, $kses );
154	}
155	}
156
157	/**
158	* Render a checkbox field for a setting
159	*
160	* @return void
161	* @since 2.0.0
162	*/
163	public function render_checkbox_field() {
164	$this->render_checkbox( $this->input_name, $this->label, $this->get_saved_value() ?? false );
165	}
166
167	/**
168	* Render a checkbox field for a setting
169	*
170	* @return void
171	* @since 2.0.0
172	*/
173	public function render_checkboxes_field() {
174	$saved_value = $this->get_saved_value();
175	$saved_value = is_array( $saved_value ) ? $saved_value : [];
176
177	echo '<fieldset>';
178	printf( '<legend class="screen-reader-text"><span>%s</span></legend>', esc_html( $this->name ) );
179
180	foreach ( $this->options as $option => $label ) {
181	$this->render_checkbox( $this->input_name . "[$option]", $label, in_array( $option, $saved_value, true ) );
182	echo '<br>';
183	}
184
185	echo '</fieldset>';
186	}
187
188	/**
189	* Render a basic text field for an editor setting.
190	*
191	* @return void
192	*/
193	private function render_text_field() {
194	printf(
195	'<input id="%s" type="text" name="%s" value="%s" class="regular-text %s">',
196	esc_attr( $this->element_id ),
197	esc_attr( $this->input_name ),
198	esc_attr( $this->get_saved_value() ),
199	esc_attr( $this->element_id )
200	);
201
202	if ( $this->label ) {
203	echo ' ' . wp_kses_post( $this->label );
204	}
205	}
206
207	/**
208	* Render a number select field for an editor setting
209	*
210	* @since 2.0.0
211	*/
212	private function render_number_field() {
213	printf(
214	'<input type="number" name="%s" value="%s"',
215	esc_attr( $this->input_name ),
216	esc_attr( $this->get_saved_value() )
217	);
218
219	if ( is_numeric( $this->min ) ) {
220	printf( ' min="%d"', intval( $this->min ) );
221	}
222
223	if ( is_numeric( $this->max ) ) {
224	printf( ' max="%d"', intval( $this->max ) );
225	}
226
227	echo '>';
228
229	if ( $this->label ) {
230	echo ' ' . wp_kses_post( $this->label );
231	}
232	}
233
234	/**
235	* Render a number select field for an editor setting.
236	*
237	* @since 3.0.0
238	*/
239	private function render_select_field() {
240	$saved_value = $this->get_saved_value();
241	printf( '<select name="%s">', esc_attr( $this->input_name ) );
242
243	foreach ( $this->options as $option => $option_label ) {
244	printf(
245	'<option value="%s"%s>%s</option>',
246	esc_attr( $option ),
247	selected( $option, $saved_value, false ),
248	esc_html( $option_label )
249	);
250	}
251
252	echo '</select>';
253	}
254
255	/**
256	* Render a button link.
257	*
258	* @since 3.5.1
259	*/
260	private function render_action_field() {
261	printf(
262	'<button type="submit" name="%s" class="button">%s</button>',
263	esc_attr( $this->input_name ),
264	esc_html( $this->label ? $this->label : $this->name )
265	);
266	}
267	}
268