elementor / includes / settings / settings-page.php

settings-page.php in Elementor Website Builder – more than just a page builder 3.29.2, at includes/settings/settings-page.php

468 lines 11.2 KB

Raw Download Zip

1	<?php
2	namespace Elementor;
3
4	use Elementor\Plugin;
5
6	if ( ! defined( 'ABSPATH' ) ) {
7	exit; // Exit if accessed directly.
8	}
9
10	/**
11	* Elementor settings page.
12	*
13	* An abstract class that provides the needed properties and methods to handle
14	* WordPress dashboard settings pages in inheriting classes.
15	*
16	* @since 1.0.0
17	* @abstract
18	*/
19	abstract class Settings_Page {
20
21	/**
22	* Settings page ID.
23	*/
24	const PAGE_ID = '';
25
26	/**
27	* Tabs.
28	*
29	* Holds the settings page tabs, sections and fields.
30	*
31	* @access private
32	*
33	* @var array
34	*/
35	private $tabs;
36
37	/**
38	* Create tabs.
39	*
40	* Return the settings page tabs, sections and fields.
41	*
42	* @since 1.5.0
43	* @access protected
44	* @abstract
45	*/
46	abstract protected function create_tabs();
47
48	/**
49	* Get settings page title.
50	*
51	* Retrieve the title for the settings page.
52	*
53	* @since 1.5.0
54	* @access protected
55	* @abstract
56	*/
57	abstract protected function get_page_title();
58
59	/**
60	* Get settings page URL.
61	*
62	* Retrieve the URL of the settings page.
63	*
64	* @since 1.5.0
65	* @access public
66	* @static
67	*
68	* @return string Settings page URL.
69	*/
70	final public static function get_url() {
71	return admin_url( 'admin.php?page=' . static::PAGE_ID );
72	}
73
74	/**
75	* Get settings tab URL.
76	*
77	* Retrieve the URL of a specific tab in the settings page.
78	*
79	* @since 3.23.0
80	* @access public
81	* @static
82	*
83	* @param string $tab_id The ID of the settings tab.
84	*
85	* @return string Settings tab URL.
86	*/
87	final public static function get_settings_tab_url( $tab_id ): string {
88	$settings_page_id = Plugin::$instance->experiments->is_feature_active( 'home_screen' )
89	? 'elementor-settings'
90	: 'elementor';
91
92	return admin_url( "admin.php?page=$settings_page_id#tab-$tab_id" );
93	}
94
95	/**
96	* Settings page constructor.
97	*
98	* Initializing Elementor settings page.
99	*
100	* @since 1.5.0
101	* @access public
102	*/
103	public function __construct() {
104	// PHPCS - The user data is not used.
105	if ( ! empty( $_POST['option_page'] ) && static::PAGE_ID === $_POST['option_page'] ) { // phpcs:ignore WordPress.Security.NonceVerification.Missing
106	add_action( 'admin_init', [ $this, 'register_settings_fields' ] );
107	}
108	}
109
110	/**
111	* Get tabs.
112	*
113	* Retrieve the settings page tabs, sections and fields.
114	*
115	* @since 1.5.0
116	* @access public
117	*
118	* @return array Settings page tabs, sections and fields.
119	*/
120	final public function get_tabs() {
121	$this->ensure_tabs();
122
123	return $this->tabs;
124	}
125
126	/**
127	* Add tab.
128	*
129	* Register a new tab to a settings page.
130	*
131	* @since 1.5.0
132	* @access public
133	*
134	* @param string $tab_id Tab ID.
135	* @param array $tab_args Optional. Tab arguments. Default is an empty array.
136	*/
137	final public function add_tab( $tab_id, array $tab_args = [] ) {
138	$this->ensure_tabs();
139
140	if ( isset( $this->tabs[ $tab_id ] ) ) {
141	// Don't override an existing tab
142	return;
143	}
144
145	if ( ! isset( $tab_args['sections'] ) ) {
146	$tab_args['sections'] = [];
147	}
148
149	$this->tabs[ $tab_id ] = $tab_args;
150	}
151
152	/**
153	* Add section.
154	*
155	* Register a new section to a tab.
156	*
157	* @since 1.5.0
158	* @access public
159	*
160	* @param string $tab_id Tab ID.
161	* @param string $section_id Section ID.
162	* @param array $section_args Optional. Section arguments. Default is an
163	* empty array.
164	*/
165	final public function add_section( $tab_id, $section_id, array $section_args = [] ) {
166	$this->ensure_tabs();
167
168	if ( ! isset( $this->tabs[ $tab_id ] ) ) {
169	// If the requested tab doesn't exists, use the first tab
170	$tab_id = key( $this->tabs );
171	}
172
173	if ( isset( $this->tabs[ $tab_id ]['sections'][ $section_id ] ) ) {
174	// Don't override an existing section
175	return;
176	}
177
178	if ( ! isset( $section_args['fields'] ) ) {
179	$section_args['fields'] = [];
180	}
181
182	$this->tabs[ $tab_id ]['sections'][ $section_id ] = $section_args;
183	}
184
185	/**
186	* Add field.
187	*
188	* Register a new field to a section.
189	*
190	* @since 1.5.0
191	* @access public
192	*
193	* @param string $tab_id Tab ID.
194	* @param string $section_id Section ID.
195	* @param string $field_id Field ID.
196	* @param array $field_args Field arguments.
197	*/
198	final public function add_field( $tab_id, $section_id, $field_id, array $field_args ) {
199	$this->ensure_tabs();
200
201	if ( ! isset( $this->tabs[ $tab_id ] ) ) {
202	// If the requested tab doesn't exists, use the first tab
203	$tab_id = key( $this->tabs );
204	}
205
206	if ( ! isset( $this->tabs[ $tab_id ]['sections'][ $section_id ] ) ) {
207	// If the requested section doesn't exists, use the first section
208	$section_id = key( $this->tabs[ $tab_id ]['sections'] );
209	}
210
211	if ( isset( $this->tabs[ $tab_id ]['sections'][ $section_id ]['fields'][ $field_id ] ) ) {
212	// Don't override an existing field
213	return;
214	}
215
216	$this->tabs[ $tab_id ]['sections'][ $section_id ]['fields'][ $field_id ] = $field_args;
217	}
218
219	/**
220	* Add fields.
221	*
222	* Register multiple fields to a section.
223	*
224	* @since 1.5.0
225	* @access public
226	*
227	* @param string $tab_id Tab ID.
228	* @param string $section_id Section ID.
229	* @param array $fields {
230	* An array of fields.
231	*
232	* @type string $field_id Field ID.
233	* @type array $field_args Field arguments.
234	* }
235	*/
236	final public function add_fields( $tab_id, $section_id, array $fields ) {
237	foreach ( $fields as $field_id => $field_args ) {
238	$this->add_field( $tab_id, $section_id, $field_id, $field_args );
239	}
240	}
241
242	/**
243	* Register settings fields.
244	*
245	* In each tab register his inner sections, and in each section register his
246	* inner fields.
247	*
248	* @since 1.5.0
249	* @access public
250	*/
251	final public function register_settings_fields() {
252	$controls_class_name = __NAMESPACE__ . '\Settings_Controls';
253
254	$tabs = $this->get_tabs();
255
256	foreach ( $tabs as $tab_id => $tab ) {
257
258	foreach ( $tab['sections'] as $section_id => $section ) {
259	$full_section_id = 'elementor_' . $section_id . '_section';
260
261	$label = isset( $section['label'] ) ? $section['label'] : '';
262
263	$section_callback = isset( $section['callback'] ) ? $section['callback'] : '__return_empty_string';
264
265	add_settings_section( $full_section_id, $label, $section_callback, static::PAGE_ID );
266
267	foreach ( $section['fields'] as $field_id => $field ) {
268	$full_field_id = ! empty( $field['full_field_id'] ) ? $field['full_field_id'] : 'elementor_' . $field_id;
269
270	$field['field_args']['id'] = $full_field_id;
271
272	$field_classes = [ $full_field_id ];
273
274	if ( ! empty( $field['class'] ) ) {
275	$field_classes[] = $field['field_args']['class'];
276	}
277
278	$field['field_args']['class'] = implode( ' ', $field_classes );
279
280	if ( ! isset( $field['render'] ) ) {
281	$field['render'] = [ $controls_class_name, 'render' ];
282	}
283
284	add_settings_field(
285	$full_field_id,
286	isset( $field['label'] ) ? $field['label'] : '',
287	$field['render'],
288	static::PAGE_ID,
289	$full_section_id,
290	$field['field_args']
291	);
292
293	$setting_args = [];
294
295	if ( ! empty( $field['setting_args'] ) ) {
296	$setting_args = $field['setting_args'];
297	}
298
299	register_setting( static::PAGE_ID, $full_field_id, $setting_args );
300	}
301	}
302	}
303	}
304
305	/**
306	* Display settings page.
307	*
308	* Output the content for the settings page.
309	*
310	* @since 1.5.0
311	* @access public
312	*/
313	public function display_settings_page() {
314	$this->register_settings_fields();
315
316	$tabs = $this->get_tabs();
317	?>
318	<div class="wrap">
319	<h1 class="wp-heading-inline"><?php echo esc_html( $this->get_page_title() ); ?></h1>
320	<div id="elementor-settings-tabs-wrapper" class="nav-tab-wrapper">
321	<?php
322	foreach ( $tabs as $tab_id => $tab ) {
323	if ( ! $this->should_render_tab( $tab ) ) {
324	continue;
325	}
326
327	$active_class = '';
328
329	if ( 'general' === $tab_id ) {
330	$active_class = ' nav-tab-active';
331	}
332
333	$sanitized_tab_id = esc_attr( $tab_id );
334	$sanitized_tab_label = esc_html( $tab['label'] );
335
336	// PHPCS - Escaped the relevant strings above.
337	echo "<a id='elementor-settings-tab-{$sanitized_tab_id}' class='nav-tab{$active_class}' href='#tab-{$sanitized_tab_id}'>{$sanitized_tab_label}</a>"; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
338	}
339	?>
340	</div>
341	<form id="elementor-settings-form" method="post" action="options.php">
342	<?php
343	settings_fields( static::PAGE_ID );
344
345	foreach ( $tabs as $tab_id => $tab ) {
346	if ( ! $this->should_render_tab( $tab ) ) {
347	continue;
348	}
349
350	$active_class = '';
351
352	if ( 'general' === $tab_id ) {
353	$active_class = ' elementor-active';
354	}
355
356	$sanitized_tab_id = esc_attr( $tab_id );
357
358	// PHPCS - $active_class is a non-dynamic string and $sanitized_tab_id is escaped above.
359	echo "<div id='tab-{$sanitized_tab_id}' class='elementor-settings-form-page{$active_class}'>"; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
360
361	foreach ( $tab['sections'] as $section_id => $section ) {
362	if ( ! $this->should_render_section( $section ) ) {
363	continue;
364	}
365
366	$full_section_id = 'elementor_' . $section_id . '_section';
367
368	if ( ! empty( $section['label'] ) ) {
369	echo '<h2>' . esc_html( $section['label'] ) . '</h2>';
370	}
371
372	if ( ! empty( $section['callback'] ) ) {
373	$section['callback']();
374	}
375
376	echo '<table class="form-table">';
377
378	do_settings_fields( static::PAGE_ID, $full_section_id );
379
380	echo '</table>';
381	}
382
383	echo '</div>';
384	}
385
386	submit_button();
387	?>
388	</form>
389	</div><!-- /.wrap -->
390	<?php
391	}
392
393	public function get_usage_fields() {
394	return [
395	'allow_tracking' => [
396	'label' => esc_html__( 'Usage Data Sharing', 'elementor' ),
397	'field_args' => [
398	'type' => 'checkbox',
399	'value' => 'yes',
400	'default' => '',
401	'sub_desc' => sprintf(
402	'%1$s <a href="https://go.elementor.com/usage-data-tracking/" target="_blank">%2$s</a>',
403	esc_html__( 'Become a super contributor by opting in to share non-sensitive plugin data and to receive periodic email updates from us.', 'elementor' ),
404	esc_html__( 'Learn more', 'elementor' )
405	),
406	],
407	'setting_args' => [ __NAMESPACE__ . '\Tracker', 'check_for_settings_optin' ],
408	],
409	];
410	}
411
412	/**
413	* Ensure tabs.
414	*
415	* Make sure the settings page has tabs before inserting any new sections or
416	* fields.
417	*
418	* @since 1.5.0
419	* @access private
420	*/
421	private function ensure_tabs() {
422	if ( null === $this->tabs ) {
423	$this->tabs = $this->create_tabs();
424
425	$page_id = static::PAGE_ID;
426
427	/**
428	* After create settings.
429	*
430	* Fires after the settings are created in Elementor admin page.
431	*
432	* The dynamic portion of the hook name, `$page_id`, refers to the current page ID.
433	*
434	* @since 1.0.0
435	*
436	* @param Settings_Page $this The settings page.
437	*/
438	do_action( "elementor/admin/after_create_settings/{$page_id}", $this );
439	}
440	}
441
442	/**
443	* Should it render the settings tab
444	*
445	* @param array $tab
446	*
447	* @return bool
448	*/
449	private function should_render_tab( $tab ) {
450	// BC - When 'show_if' prop is not exists, it actually should render the tab.
451	return ! empty( $tab['sections'] ) && ( ! isset( $tab['show_if'] ) \|\| $tab['show_if'] );
452	}
453
454	/**
455	* Should it render the settings section
456	*
457	* @param array $section
458	*
459	* Since 3.19.0
460	*
461	* @return bool
462	*/
463	private function should_render_section( $section ) {
464	// BC - When 'show_if' prop is not exists, it actually should render the section.
465	return ! isset( $section['show_if'] ) \|\| $section['show_if'];
466	}
467	}
468