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

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

272 lines 6.5 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	if ( ! is_callable( $this->render_callback ) ) {
121	return;
122	}
123
124	call_user_func( $this->render_callback, $this->args );
125	}
126
127	/**
128	* Render a single checkbox field.
129	*
130	* @param string $input_name Input name.
131	* @param string $label Input label.
132	* @param boolean $checked Whether the checkbox should be checked.
133	*/
134	private static function render_checkbox( string $input_name, string $label, bool $checked ) {
135
136	$checkbox = sprintf(
137	'<input type="checkbox" name="%s"%s>',
138	esc_attr( $input_name ),
139	checked( $checked, true, false )
140	);
141
142	$kses = [
143	'input' => [
144	'type' => [],
145	'name' => [],
146	'checked' => [],
147	],
148	];
149
150	if ( $label ) {
151	printf(
152	'<label>%s %s</label>',
153	wp_kses( $checkbox, $kses ),
154	wp_kses_post( $label )
155	);
156	} else {
157	echo wp_kses( $checkbox, $kses );
158	}
159	}
160
161	/**
162	* Render a checkbox field for a setting
163	*
164	* @return void
165	* @since 2.0.0
166	*/
167	public function render_checkbox_field() {
168	$this->render_checkbox( $this->input_name, $this->label, $this->get_saved_value() ?? false );
169	}
170
171	/**
172	* Render a checkbox field for a setting
173	*
174	* @return void
175	* @since 2.0.0
176	*/
177	public function render_checkboxes_field() {
178	$saved_value = $this->get_saved_value();
179	$saved_value = is_array( $saved_value ) ? $saved_value : [];
180
181	echo '<fieldset>';
182	printf( '<legend class="screen-reader-text"><span>%s</span></legend>', esc_html( $this->name ) );
183
184	foreach ( $this->options as $option => $label ) {
185	$this->render_checkbox( $this->input_name . "[$option]", $label, in_array( $option, $saved_value, true ) );
186	echo '<br>';
187	}
188
189	echo '</fieldset>';
190	}
191
192	/**
193	* Render a basic text field for an editor setting.
194	*
195	* @return void
196	*/
197	private function render_text_field() {
198	printf(
199	'<input id="%s" type="text" name="%s" value="%s" class="regular-text %s">',
200	esc_attr( $this->element_id ),
201	esc_attr( $this->input_name ),
202	esc_attr( $this->get_saved_value() ),
203	esc_attr( $this->element_id )
204	);
205
206	if ( $this->label ) {
207	echo ' ' . wp_kses_post( $this->label );
208	}
209	}
210
211	/**
212	* Render a number select field for an editor setting
213	*
214	* @since 2.0.0
215	*/
216	private function render_number_field() {
217	printf(
218	'<input type="number" name="%s" value="%s"',
219	esc_attr( $this->input_name ),
220	esc_attr( $this->get_saved_value() )
221	);
222
223	if ( is_numeric( $this->min ) ) {
224	printf( ' min="%d"', intval( $this->min ) );
225	}
226
227	if ( is_numeric( $this->max ) ) {
228	printf( ' max="%d"', intval( $this->max ) );
229	}
230
231	echo '>';
232
233	if ( $this->label ) {
234	echo ' ' . wp_kses_post( $this->label );
235	}
236	}
237
238	/**
239	* Render a number select field for an editor setting.
240	*
241	* @since 3.0.0
242	*/
243	private function render_select_field() {
244	$saved_value = $this->get_saved_value();
245	printf( '<select name="%s">', esc_attr( $this->input_name ) );
246
247	foreach ( $this->options as $option => $option_label ) {
248	printf(
249	'<option value="%s"%s>%s</option>',
250	esc_attr( $option ),
251	selected( $option, $saved_value, false ),
252	esc_html( $option_label )
253	);
254	}
255
256	echo '</select>';
257	}
258
259	/**
260	* Render a button link.
261	*
262	* @since 3.5.1
263	*/
264	private function render_action_field() {
265	printf(
266	'<button type="submit" name="%s" class="button">%s</button>',
267	esc_attr( $this->input_name ),
268	esc_html( $this->label ? $this->label : $this->name )
269	);
270	}
271	}
272