elementor / trunk / includes / base / controls-stack.php

controls-stack.php in Elementor Website Builder – more than just a page builder 3.6.0-dev1, at trunk/includes/base/controls-stack.php

2,405 lines 64.7 KB

Raw Download Zip

1	<?php
2	namespace Elementor;
3
4	use Elementor\Core\Base\Base_Object;
5	use Elementor\Core\DynamicTags\Manager;
6	use Elementor\Core\Schemes\Manager as Schemes_Manager;
7	use Elementor\Core\Breakpoints\Manager as Breakpoints_Manager;
8
9	if ( ! defined( 'ABSPATH' ) ) {
10	exit; // Exit if accessed directly.
11	}
12
13	/**
14	* Elementor controls stack.
15	*
16	* An abstract class that provides the needed properties and methods to
17	* manage and handle controls in the editor panel to inheriting classes.
18	*
19	* @since 1.4.0
20	* @abstract
21	*/
22	abstract class Controls_Stack extends Base_Object {
23
24	/**
25	* Responsive 'desktop' device name.
26	*
27	* @deprecated 3.4.0
28	*/
29	const RESPONSIVE_DESKTOP = 'desktop';
30
31	/**
32	* Responsive 'tablet' device name.
33	*
34	* @deprecated 3.4.0
35	*/
36	const RESPONSIVE_TABLET = 'tablet';
37
38	/**
39	* Responsive 'mobile' device name.
40	*
41	* @deprecated 3.4.0
42	*/
43	const RESPONSIVE_MOBILE = 'mobile';
44
45	/**
46	* Generic ID.
47	*
48	* Holds the unique ID.
49	*
50	* @access private
51	*
52	* @var string
53	*/
54	private $id;
55
56	private $active_settings;
57
58	private $parsed_active_settings;
59
60	/**
61	* Parsed Dynamic Settings.
62	*
63	* @access private
64	*
65	* @var null\|array
66	*/
67	private $parsed_dynamic_settings;
68
69	/**
70	* Raw Data.
71	*
72	* Holds all the raw data including the element type, the child elements,
73	* the user data.
74	*
75	* @access private
76	*
77	* @var null\|array
78	*/
79	private $data;
80
81	/**
82	* The configuration.
83	*
84	* Holds the configuration used to generate the Elementor editor. It includes
85	* the element name, icon, categories, etc.
86	*
87	* @access private
88	*
89	* @var null\|array
90	*/
91	private $config;
92
93	/**
94	* The additional configuration.
95	*
96	* Holds additional configuration that has been set using `set_config` method.
97	* The `config` property is not modified directly while using the method because
98	* it's used to check whether the initial config already loaded (in `get_config`).
99	* After the initial config loaded, the additional config is merged into it.
100	*
101	* @access private
102	*
103	* @var null\|array
104	*/
105	private $additional_config = [];
106
107	/**
108	* Current section.
109	*
110	* Holds the current section while inserting a set of controls sections.
111	*
112	* @access private
113	*
114	* @var null\|array
115	*/
116	private $current_section;
117
118	/**
119	* Current tab.
120	*
121	* Holds the current tab while inserting a set of controls tabs.
122	*
123	* @access private
124	*
125	* @var null\|array
126	*/
127	private $current_tab;
128
129	/**
130	* Current popover.
131	*
132	* Holds the current popover while inserting a set of controls.
133	*
134	* @access private
135	*
136	* @var null\|array
137	*/
138	private $current_popover;
139
140	/**
141	* Injection point.
142	*
143	* Holds the injection point in the stack where the control will be inserted.
144	*
145	* @access private
146	*
147	* @var null\|array
148	*/
149	private $injection_point;
150
151
152	/**
153	* Data sanitized.
154	*
155	* @access private
156	*
157	* @var bool
158	*/
159	private $settings_sanitized = false;
160
161	/**
162	* Element render attributes.
163	*
164	* Holds all the render attributes of the element. Used to store data like
165	* the HTML class name and the class value, or HTML element ID name and value.
166	*
167	* @access private
168	*
169	* @var array
170	*/
171	private $render_attributes = [];
172
173	/**
174	* Get element name.
175	*
176	* Retrieve the element name.
177	*
178	* @since 1.4.0
179	* @access public
180	* @abstract
181	*
182	* @return string The name.
183	*/
184	abstract public function get_name();
185
186	/**
187	* Get unique name.
188	*
189	* Some classes need to use unique names, this method allows you to create
190	* them. By default it retrieves the regular name.
191	*
192	* @since 1.6.0
193	* @access public
194	*
195	* @return string Unique name.
196	*/
197	public function get_unique_name() {
198	return $this->get_name();
199	}
200
201	/**
202	* Get element ID.
203	*
204	* Retrieve the element generic ID.
205	*
206	* @since 1.4.0
207	* @access public
208	*
209	* @return string The ID.
210	*/
211	public function get_id() {
212	return $this->id;
213	}
214
215	/**
216	* Get element ID.
217	*
218	* Retrieve the element generic ID as integer.
219	*
220	* @since 1.8.0
221	* @access public
222	*
223	* @return string The converted ID.
224	*/
225	public function get_id_int() {
226	/** We ignore possible notices, in order to support elements created prior to v1.8.0 and might include
227	* non-base 16 characters as part of their ID.
228	*/
229	return @hexdec( $this->id );
230	}
231
232	/**
233	* Get the type.
234	*
235	* Retrieve the type, e.g. 'stack', 'section', 'widget' etc.
236	*
237	* @since 1.4.0
238	* @access public
239	* @static
240	*
241	* @return string The type.
242	*/
243	public static function get_type() {
244	return 'stack';
245	}
246
247	/**
248	* @since 2.9.0
249	* @access public
250	*
251	* @return bool
252	*/
253	public function is_editable() {
254	return true;
255	}
256
257	/**
258	* Get current section.
259	*
260	* When inserting new controls, this method will retrieve the current section.
261	*
262	* @since 1.7.1
263	* @access public
264	*
265	* @return null\|array Current section.
266	*/
267	public function get_current_section() {
268	return $this->current_section;
269	}
270
271	/**
272	* Get current tab.
273	*
274	* When inserting new controls, this method will retrieve the current tab.
275	*
276	* @since 1.7.1
277	* @access public
278	*
279	* @return null\|array Current tab.
280	*/
281	public function get_current_tab() {
282	return $this->current_tab;
283	}
284
285	/**
286	* Get controls.
287	*
288	* Retrieve all the controls or, when requested, a specific control.
289	*
290	* @since 1.4.0
291	* @access public
292	*
293	* @param string $control_id The ID of the requested control. Optional field,
294	* when set it will return a specific control.
295	* Default is null.
296	*
297	* @return mixed Controls list.
298	*/
299	public function get_controls( $control_id = null ) {
300	return self::get_items( $this->get_stack()['controls'], $control_id );
301	}
302
303	/**
304	* Get active controls.
305	*
306	* Retrieve an array of active controls that meet the condition field.
307	*
308	* If specific controls was given as a parameter, retrieve active controls
309	* from that list, otherwise check for all the controls available.
310	*
311	* @since 1.4.0
312	* @since 2.0.9 Added the `controls` and the `settings` parameters.
313	* @access public
314	* @deprecated 3.0.0
315	*
316	* @param array $controls Optional. An array of controls. Default is null.
317	* @param array $settings Optional. Controls settings. Default is null.
318	*
319	* @return array Active controls.
320	*/
321	public function get_active_controls( array $controls = null, array $settings = null ) {
322	Plugin::$instance->modules_manager->get_modules( 'dev-tools' )->deprecation->deprecated_function( __METHOD__, '3.0.0' );
323
324	if ( ! $controls ) {
325	$controls = $this->get_controls();
326	}
327
328	if ( ! $settings ) {
329	$settings = $this->get_controls_settings();
330	}
331
332	$active_controls = array_reduce(
333	array_keys( $controls ), function( $active_controls, $control_key ) use ( $controls, $settings ) {
334	$control = $controls[ $control_key ];
335
336	if ( $this->is_control_visible( $control, $settings ) ) {
337	$active_controls[ $control_key ] = $control;
338	}
339
340	return $active_controls;
341	}, []
342	);
343
344	return $active_controls;
345	}
346
347	/**
348	* Get controls settings.
349	*
350	* Retrieve the settings for all the controls that represent them.
351	*
352	* @since 1.5.0
353	* @access public
354	*
355	* @return array Controls settings.
356	*/
357	public function get_controls_settings() {
358	return array_intersect_key( $this->get_settings(), $this->get_controls() );
359	}
360
361	/**
362	* Add new control to stack.
363	*
364	* Register a single control to allow the user to set/update data.
365	*
366	* This method should be used inside `register_controls()`.
367	*
368	* @since 1.4.0
369	* @access public
370	*
371	* @param string $id Control ID.
372	* @param array $args Control arguments.
373	* @param array $options Optional. Control options. Default is an empty array.
374	*
375	* @return bool True if control added, False otherwise.
376	*/
377	public function add_control( $id, array $args, $options = [] ) {
378	$default_options = [
379	'overwrite' => false,
380	'position' => null,
381	];
382
383	if ( isset( $args['scheme'] ) ) {
384	$args['global'] = [
385	'default' => Plugin::$instance->kits_manager->convert_scheme_to_global( $args['scheme'] ),
386	];
387
388	unset( $args['scheme'] );
389	}
390
391	$options = array_merge( $default_options, $options );
392
393	if ( $options['position'] ) {
394	$this->start_injection( $options['position'] );
395	}
396
397	if ( $this->injection_point ) {
398	$options['index'] = $this->injection_point['index']++;
399	}
400
401	if ( empty( $args['type'] ) \|\| ! in_array( $args['type'], [ Controls_Manager::SECTION, Controls_Manager::WP_WIDGET ], true ) ) {
402	$args = $this->handle_control_position( $args, $id, $options['overwrite'] );
403	}
404
405	if ( $options['position'] ) {
406	$this->end_injection();
407	}
408
409	unset( $options['position'] );
410
411	if ( $this->current_popover && ! $this->current_popover['initialized'] ) {
412	$args['popover'] = [
413	'start' => true,
414	];
415
416	$this->current_popover['initialized'] = true;
417	}
418
419	return Plugin::$instance->controls_manager->add_control_to_stack( $this, $id, $args, $options );
420	}
421
422	/**
423	* Remove control from stack.
424	*
425	* Unregister an existing control and remove it from the stack.
426	*
427	* @since 1.4.0
428	* @access public
429	*
430	* @param string $control_id Control ID.
431	*
432	* @return bool\|\WP_Error
433	*/
434	public function remove_control( $control_id ) {
435	return Plugin::$instance->controls_manager->remove_control_from_stack( $this->get_unique_name(), $control_id );
436	}
437
438	/**
439	* Update control in stack.
440	*
441	* Change the value of an existing control in the stack. When you add new
442	* control you set the `$args` parameter, this method allows you to update
443	* the arguments by passing new data.
444	*
445	* @since 1.4.0
446	* @since 1.8.1 New `$options` parameter added.
447	*
448	* @access public
449	*
450	* @param string $control_id Control ID.
451	* @param array $args Control arguments. Only the new fields you want
452	* to update.
453	* @param array $options Optional. Some additional options. Default is
454	* an empty array.
455	*
456	* @return bool
457	*/
458	public function update_control( $control_id, array $args, array $options = [] ) {
459	$is_updated = Plugin::$instance->controls_manager->update_control_in_stack( $this, $control_id, $args, $options );
460
461	if ( ! $is_updated ) {
462	return false;
463	}
464
465	$control = $this->get_controls( $control_id );
466
467	if ( Controls_Manager::SECTION === $control['type'] ) {
468	$section_args = $this->get_section_args( $control_id );
469
470	$section_controls = $this->get_section_controls( $control_id );
471
472	foreach ( $section_controls as $section_control_id => $section_control ) {
473	$this->update_control( $section_control_id, $section_args, $options );
474	}
475	}
476
477	return true;
478	}
479
480	/**
481	* Get stack.
482	*
483	* Retrieve the stack of controls.
484	*
485	* @since 1.9.2
486	* @access public
487	*
488	* @return array Stack of controls.
489	*/
490	public function get_stack() {
491	$stack = Plugin::$instance->controls_manager->get_element_stack( $this );
492
493	if ( null === $stack ) {
494	$this->init_controls();
495
496	return Plugin::$instance->controls_manager->get_element_stack( $this );
497	}
498
499	return $stack;
500	}
501
502	/**
503	* Get position information.
504	*
505	* Retrieve the position while injecting data, based on the element type.
506	*
507	* @since 1.7.0
508	* @access public
509	*
510	* @param array $position {
511	* The injection position.
512	*
513	* @type string $type Injection type, either `control` or `section`.
514	* Default is `control`.
515	* @type string $at Where to inject. If `$type` is `control` accepts
516	* `before` and `after`. If `$type` is `section`
517	* accepts `start` and `end`. Default values based on
518	* the `type`.
519	* @type string $of Control/Section ID.
520	* @type array $fallback Fallback injection position. When the position is
521	* not found it will try to fetch the fallback
522	* position.
523	* }
524	*
525	* @return bool\|array Position info.
526	*/
527	final public function get_position_info( array $position ) {
528	$default_position = [
529	'type' => 'control',
530	'at' => 'after',
531	];
532
533	if ( ! empty( $position['type'] ) && 'section' === $position['type'] ) {
534	$default_position['at'] = 'end';
535	}
536
537	$position = array_merge( $default_position, $position );
538
539	if (
540	'control' === $position['type'] && in_array( $position['at'], [ 'start', 'end' ], true ) \|\|
541	'section' === $position['type'] && in_array( $position['at'], [ 'before', 'after' ], true )
542	) {
543	_doing_it_wrong( sprintf( '%s::%s', get_called_class(), __FUNCTION__ ), 'Invalid position arguments. Use `before` / `after` for control or `start` / `end` for section.', '1.7.0' ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
544
545	return false;
546	}
547
548	$target_control_index = $this->get_control_index( $position['of'] );
549
550	if ( false === $target_control_index ) {
551	if ( ! empty( $position['fallback'] ) ) {
552	return $this->get_position_info( $position['fallback'] );
553	}
554
555	return false;
556	}
557
558	$target_section_index = $target_control_index;
559
560	$registered_controls = $this->get_controls();
561
562	$controls_keys = array_keys( $registered_controls );
563
564	while ( Controls_Manager::SECTION !== $registered_controls[ $controls_keys[ $target_section_index ] ]['type'] ) {
565	$target_section_index--;
566	}
567
568	if ( 'section' === $position['type'] ) {
569	$target_control_index++;
570
571	if ( 'end' === $position['at'] ) {
572	while ( Controls_Manager::SECTION !== $registered_controls[ $controls_keys[ $target_control_index ] ]['type'] ) {
573	if ( ++$target_control_index >= count( $registered_controls ) ) {
574	break;
575	}
576	}
577	}
578	}
579
580	$target_control = $registered_controls[ $controls_keys[ $target_control_index ] ];
581
582	if ( 'after' === $position['at'] ) {
583	$target_control_index++;
584	}
585
586	$section_id = $registered_controls[ $controls_keys[ $target_section_index ] ]['name'];
587
588	$position_info = [
589	'index' => $target_control_index,
590	'section' => $this->get_section_args( $section_id ),
591	];
592
593	if ( ! empty( $target_control['tabs_wrapper'] ) ) {
594	$position_info['tab'] = [
595	'tabs_wrapper' => $target_control['tabs_wrapper'],
596	'inner_tab' => $target_control['inner_tab'],
597	];
598	}
599
600	return $position_info;
601	}
602
603	/**
604	* Get control key.
605	*
606	* Retrieve the key of the control based on a given index of the control.
607	*
608	* @since 1.9.2
609	* @access public
610	*
611	* @param string $control_index Control index.
612	*
613	* @return int Control key.
614	*/
615	final public function get_control_key( $control_index ) {
616	$registered_controls = $this->get_controls();
617
618	$controls_keys = array_keys( $registered_controls );
619
620	return $controls_keys[ $control_index ];
621	}
622
623	/**
624	* Get control index.
625	*
626	* Retrieve the index of the control based on a given key of the control.
627	*
628	* @since 1.7.6
629	* @access public
630	*
631	* @param string $control_key Control key.
632	*
633	* @return false\|int Control index.
634	*/
635	final public function get_control_index( $control_key ) {
636	$controls = $this->get_controls();
637
638	$controls_keys = array_keys( $controls );
639
640	return array_search( $control_key, $controls_keys );
641	}
642
643	/**
644	* Get section controls.
645	*
646	* Retrieve all controls under a specific section.
647	*
648	* @since 1.7.6
649	* @access public
650	*
651	* @param string $section_id Section ID.
652	*
653	* @return array Section controls
654	*/
655	final public function get_section_controls( $section_id ) {
656	$section_index = $this->get_control_index( $section_id );
657
658	$section_controls = [];
659
660	$registered_controls = $this->get_controls();
661
662	$controls_keys = array_keys( $registered_controls );
663
664	while ( true ) {
665	$section_index++;
666
667	if ( ! isset( $controls_keys[ $section_index ] ) ) {
668	break;
669	}
670
671	$control_key = $controls_keys[ $section_index ];
672
673	if ( Controls_Manager::SECTION === $registered_controls[ $control_key ]['type'] ) {
674	break;
675	}
676
677	$section_controls[ $control_key ] = $registered_controls[ $control_key ];
678	};
679
680	return $section_controls;
681	}
682
683	/**
684	* Add new group control to stack.
685	*
686	* Register a set of related controls grouped together as a single unified
687	* control. For example grouping together like typography controls into a
688	* single, easy-to-use control.
689	*
690	* @since 1.4.0
691	* @access public
692	*
693	* @param string $group_name Group control name.
694	* @param array $args Group control arguments. Default is an empty array.
695	* @param array $options Optional. Group control options. Default is an
696	* empty array.
697	*/
698	final public function add_group_control( $group_name, array $args = [], array $options = [] ) {
699	$group = Plugin::$instance->controls_manager->get_control_groups( $group_name );
700
701	if ( ! $group ) {
702	wp_die( sprintf( '%s::%s: Group "%s" not found.', get_called_class(), __FUNCTION__, $group_name ) ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
703	}
704
705	$group->add_controls( $this, $args, $options );
706	}
707
708	/**
709	* Get scheme controls.
710	*
711	* Retrieve all the controls that use schemes.
712	*
713	* @since 1.4.0
714	* @access public
715	* @deprecated 3.0.0
716	*
717	* @return array Scheme controls.
718	*/
719	final public function get_scheme_controls() {
720
721	Plugin::$instance->modules_manager->get_modules( 'dev-tools' )->deprecation->deprecated_function( __METHOD__, '3.0.0' );
722
723	$enabled_schemes = Schemes_Manager::get_enabled_schemes();
724
725	return array_filter(
726	$this->get_controls(), function ( $control ) use ( $enabled_schemes ) {
727	return ( ! empty( $control['scheme'] ) && in_array( $control['scheme']['type'], $enabled_schemes ) );
728	}
729	);
730	}
731
732	/**
733	* Get style controls.
734	*
735	* Retrieve style controls for all active controls or, when requested, from
736	* a specific set of controls.
737	*
738	* @since 1.4.0
739	* @since 2.0.9 Added the `settings` parameter.
740	* @access public
741	* @deprecated 3.0.0
742	*
743	* @param array $controls Optional. Controls list. Default is null.
744	* @param array $settings Optional. Controls settings. Default is null.
745	*
746	* @return array Style controls.
747	*/
748	final public function get_style_controls( array $controls = null, array $settings = null ) {
749	Plugin::$instance->modules_manager->get_modules( 'dev-tools' )->deprecation->deprecated_function( __METHOD__, '3.0.0' );
750
751	$controls = $this->get_active_controls( $controls, $settings );
752
753	$style_controls = [];
754
755	foreach ( $controls as $control_name => $control ) {
756	$control_obj = Plugin::$instance->controls_manager->get_control( $control['type'] );
757
758	if ( ! $control_obj instanceof Base_Data_Control ) {
759	continue;
760	}
761
762	$control = array_merge( $control_obj->get_settings(), $control );
763
764	if ( $control_obj instanceof Control_Repeater ) {
765	$style_fields = [];
766
767	foreach ( $this->get_settings( $control_name ) as $item ) {
768	$style_fields[] = $this->get_style_controls( $control['fields'], $item );
769	}
770
771	$control['style_fields'] = $style_fields;
772	}
773
774	if ( ! empty( $control['selectors'] ) \|\| ! empty( $control['dynamic'] ) \|\| ! empty( $control['style_fields'] ) ) {
775	$style_controls[ $control_name ] = $control;
776	}
777	}
778
779	return $style_controls;
780	}
781
782	/**
783	* Get tabs controls.
784	*
785	* Retrieve all the tabs assigned to the control.
786	*
787	* @since 1.4.0
788	* @access public
789	*
790	* @return array Tabs controls.
791	*/
792	final public function get_tabs_controls() {
793	return $this->get_stack()['tabs'];
794	}
795
796	/**
797	* Add new responsive control to stack.
798	*
799	* Register a set of controls to allow editing based on user screen size.
800	* This method registers one or more controls per screen size/device, depending on the current Responsive Control
801	* Duplication Mode. There are 3 control duplication modes:
802	* * 'off' - Only a single control is generated. In the Editor, this control is duplicated in JS.
803	* * 'on' - Multiple controls are generated, one control per enabled device/breakpoint + a default/desktop control.
804	* * 'dynamic' - If the control includes the `'dynamic' => 'active' => true` property - the control is duplicated,
805	* once for each device/breakpoint + default/desktop.
806	* If the control doesn't include the `'dynamic' => 'active' => true` property - the control is not duplicated.
807	*
808	* @since 1.4.0
809	* @access public
810	*
811	* @param string $id Responsive control ID.
812	* @param array $args Responsive control arguments.
813	* @param array $options Optional. Responsive control options. Default is
814	* an empty array.
815	*/
816	final public function add_responsive_control( $id, array $args, $options = [] ) {
817	$args['responsive'] = [];
818
819	$active_breakpoints = Plugin::$instance->breakpoints->get_active_breakpoints();
820
821	$devices = Plugin::$instance->breakpoints->get_active_devices_list( [ 'reverse' => true ] );
822
823	if ( isset( $args['devices'] ) ) {
824	$devices = array_intersect( $devices, $args['devices'] );
825
826	$args['responsive']['devices'] = $devices;
827
828	unset( $args['devices'] );
829	}
830
831	$control_to_check = $args;
832
833	if ( ! empty( $options['overwrite'] ) ) {
834	$existing_control = Plugin::$instance->controls_manager->get_control_from_stack( $this->get_unique_name(), $id );
835
836	if ( ! is_wp_error( $existing_control ) ) {
837	$control_to_check = $existing_control;
838	}
839	}
840
841	$responsive_duplication_mode = Plugin::$instance->breakpoints->get_responsive_control_duplication_mode();
842	$additional_breakpoints_active = Plugin::$instance->experiments->is_feature_active( 'additional_custom_breakpoints' );
843	$control_is_dynamic = ! empty( $control_to_check['dynamic']['active'] );
844	$is_frontend_available = ! empty( $control_to_check['frontend_available'] );
845	$has_prefix_class = ! empty( $control_to_check['prefix_class'] );
846
847	// If the new responsive controls experiment is active, create only one control - duplicates per device will
848	// be created in JS in the Editor.
849	if (
850	$additional_breakpoints_active
851	&& ( 'off' === $responsive_duplication_mode \|\| ( 'dynamic' === $responsive_duplication_mode && ! $control_is_dynamic ) )
852	// Some responsive controls need responsive settings to be available to the widget handler, even when empty.
853	&& ! $is_frontend_available
854	&& ! $has_prefix_class
855	) {
856	$args['is_responsive'] = true;
857
858	if ( ! empty( $options['overwrite'] ) ) {
859	$this->update_control( $id, $args, [
860	'recursive' => ! empty( $options['recursive'] ),
861	] );
862	} else {
863	$this->add_control( $id, $args, $options );
864	}
865
866	return;
867	}
868
869	if ( isset( $args['default'] ) ) {
870	$args['desktop_default'] = $args['default'];
871
872	unset( $args['default'] );
873	}
874
875	foreach ( $devices as $device_name ) {
876	$control_args = $args;
877
878	// Set parent using the name from previous iteration.
879	$control_args['parent'] = isset( $control_name ) ? $control_name : null;
880
881	if ( isset( $control_args['device_args'] ) ) {
882	if ( ! empty( $control_args['device_args'][ $device_name ] ) ) {
883	$control_args = array_merge( $control_args, $control_args['device_args'][ $device_name ] );
884	}
885
886	unset( $control_args['device_args'] );
887	}
888
889	if ( ! empty( $args['prefix_class'] ) ) {
890	$device_to_replace = Breakpoints_Manager::BREAKPOINT_KEY_DESKTOP === $device_name ? '' : '-' . $device_name;
891
892	$control_args['prefix_class'] = sprintf( $args['prefix_class'], $device_to_replace );
893	}
894
895	$direction = 'max';
896
897	if ( Breakpoints_Manager::BREAKPOINT_KEY_DESKTOP !== $device_name ) {
898	$direction = $active_breakpoints[ $device_name ]->get_direction();
899	}
900
901	$control_args['responsive'][ $direction ] = $device_name;
902
903	if ( isset( $control_args['min_affected_device'] ) ) {
904	if ( ! empty( $control_args['min_affected_device'][ $device_name ] ) ) {
905	$control_args['responsive']['min'] = $control_args['min_affected_device'][ $device_name ];
906	}
907
908	unset( $control_args['min_affected_device'] );
909	}
910
911	if ( isset( $control_args[ $device_name . '_default' ] ) ) {
912	$control_args['default'] = $control_args[ $device_name . '_default' ];
913	}
914
915	foreach ( $devices as $device ) {
916	unset( $control_args[ $device . '_default' ] );
917	}
918
919	$id_suffix = Breakpoints_Manager::BREAKPOINT_KEY_DESKTOP === $device_name ? '' : '_' . $device_name;
920	$control_name = $id . $id_suffix;
921
922	// Set this control as child of previous iteration control.
923	$this->update_control( $control_args['parent'], [ 'inheritors' => [ $control_name ] ] );
924
925	if ( ! empty( $options['overwrite'] ) ) {
926	$this->update_control( $control_name, $control_args, [
927	'recursive' => ! empty( $options['recursive'] ),
928	] );
929	} else {
930	$this->add_control( $control_name, $control_args, $options );
931	}
932	}
933	}
934
935	/**
936	* Update responsive control in stack.
937	*
938	* Change the value of an existing responsive control in the stack. When you
939	* add new control you set the `$args` parameter, this method allows you to
940	* update the arguments by passing new data.
941	*
942	* @since 1.4.0
943	* @access public
944	*
945	* @param string $id Responsive control ID.
946	* @param array $args Responsive control arguments.
947	* @param array $options Optional. Additional options.
948	*/
949	final public function update_responsive_control( $id, array $args, array $options = [] ) {
950	$this->add_responsive_control( $id, $args, [
951	'overwrite' => true,
952	'recursive' => ! empty( $options['recursive'] ),
953	] );
954	}
955
956	/**
957	* Remove responsive control from stack.
958	*
959	* Unregister an existing responsive control and remove it from the stack.
960	*
961	* @since 1.4.0
962	* @access public
963	*
964	* @param string $id Responsive control ID.
965	*/
966	final public function remove_responsive_control( $id ) {
967	$devices = [
968	Breakpoints_Manager::BREAKPOINT_KEY_DESKTOP,
969	Breakpoints_Manager::BREAKPOINT_KEY_TABLET,
970	Breakpoints_Manager::BREAKPOINT_KEY_MOBILE,
971	];
972
973	foreach ( $devices as $device_name ) {
974	$id_suffix = Breakpoints_Manager::BREAKPOINT_KEY_DESKTOP === $device_name ? '' : '_' . $device_name;
975
976	$this->remove_control( $id . $id_suffix );
977	}
978	}
979
980	/**
981	* Get class name.
982	*
983	* Retrieve the name of the current class.
984	*
985	* @since 1.4.0
986	* @access public
987	*
988	* @return string Class name.
989	*/
990	final public function get_class_name() {
991	return get_called_class();
992	}
993
994	/**
995	* Get the config.
996	*
997	* Retrieve the config or, if non set, use the initial config.
998	*
999	* @since 1.4.0
1000	* @access public
1001	*
1002	* @return array\|null The config.
1003	*/
1004	final public function get_config() {
1005	if ( null === $this->config ) {
1006	// TODO: This is for backwards compatibility starting from 2.9.0
1007	// This if statement should be removed when the method is hard-deprecated
1008	if ( $this->has_own_method( '_get_initial_config', self::class ) ) {
1009	Plugin::$instance->modules_manager->get_modules( 'dev-tools' )->deprecation->deprecated_function( '_get_initial_config', '2.9.0', __CLASS__ . '::get_initial_config()' );
1010
1011	$this->config = $this->_get_initial_config();
1012	} else {
1013	$this->config = $this->get_initial_config();
1014	}
1015
1016	foreach ( $this->additional_config as $key => $value ) {
1017	if ( isset( $this->config[ $key ] ) ) {
1018	$this->config[ $key ] = wp_parse_args( $value, $this->config[ $key ] );
1019	} else {
1020	$this->config[ $key ] = $value;
1021	}
1022	}
1023	}
1024
1025	return $this->config;
1026	}
1027
1028	/**
1029	* Set a config property.
1030	*
1031	* Set a specific property of the config list for this controls-stack.
1032	*
1033	* @since 3.5.0
1034	* @access public
1035	*/
1036	public function set_config( $key, $value ) {
1037	if ( isset( $this->additional_config[ $key ] ) ) {
1038	$this->additional_config[ $key ] = wp_parse_args( $value, $this->additional_config[ $key ] );
1039	} else {
1040	$this->additional_config[ $key ] = $value;
1041	}
1042	}
1043
1044	/**
1045	* Get frontend settings keys.
1046	*
1047	* Retrieve settings keys for all frontend controls.
1048	*
1049	* @since 1.6.0
1050	* @access public
1051	*
1052	* @return array Settings keys for each control.
1053	*/
1054	final public function get_frontend_settings_keys() {
1055	$controls = [];
1056
1057	foreach ( $this->get_controls() as $control ) {
1058	if ( ! empty( $control['frontend_available'] ) ) {
1059	$controls[] = $control['name'];
1060	}
1061	}
1062
1063	return $controls;
1064	}
1065
1066	/**
1067	* Get controls pointer index.
1068	*
1069	* Retrieve pointer index where the next control should be added.
1070	*
1071	* While using injection point, it will return the injection point index.
1072	* Otherwise index of the last control plus one.
1073	*
1074	* @since 1.9.2
1075	* @access public
1076	*
1077	* @return int Controls pointer index.
1078	*/
1079	public function get_pointer_index() {
1080	if ( null !== $this->injection_point ) {
1081	return $this->injection_point['index'];
1082	}
1083
1084	return count( $this->get_controls() );
1085	}
1086
1087	/**
1088	* Get the raw data.
1089	*
1090	* Retrieve all the items or, when requested, a specific item.
1091	*
1092	* @since 1.4.0
1093	* @access public
1094	*
1095	* @param string $item Optional. The requested item. Default is null.
1096	*
1097	* @return mixed The raw data.
1098	*/
1099	public function get_data( $item = null ) {
1100	if ( ! $this->settings_sanitized && ( ! $item \|\| 'settings' === $item ) ) {
1101	$this->data['settings'] = $this->sanitize_settings( $this->data['settings'] );
1102
1103	$this->settings_sanitized = true;
1104	}
1105
1106	return self::get_items( $this->data, $item );
1107	}
1108
1109	/**
1110	* @since 2.0.14
1111	* @access public
1112	*/
1113	public function get_parsed_dynamic_settings( $setting = null, $settings = null ) {
1114	if ( null === $settings ) {
1115	$settings = $this->get_settings();
1116	}
1117
1118	if ( null === $this->parsed_dynamic_settings ) {
1119	$this->parsed_dynamic_settings = $this->parse_dynamic_settings( $settings );
1120	}
1121
1122	return self::get_items( $this->parsed_dynamic_settings, $setting );
1123	}
1124
1125	/**
1126	* Get active settings.
1127	*
1128	* Retrieve the settings from all the active controls.
1129	*
1130	* @since 1.4.0
1131	* @since 2.1.0 Added the `controls` and the `settings` parameters.
1132	* @access public
1133	*
1134	* @param array $controls Optional. An array of controls. Default is null.
1135	* @param array $settings Optional. Controls settings. Default is null.
1136	*
1137	* @return array Active settings.
1138	*/
1139	public function get_active_settings( $settings = null, $controls = null ) {
1140	$is_first_request = ! $settings && ! $this->active_settings;
1141
1142	if ( ! $settings ) {
1143	if ( $this->active_settings ) {
1144	return $this->active_settings;
1145	}
1146
1147	$settings = $this->get_controls_settings();
1148
1149	$controls = $this->get_controls();
1150	}
1151
1152	$active_settings = [];
1153
1154	foreach ( $settings as $setting_key => $setting ) {
1155	if ( ! isset( $controls[ $setting_key ] ) ) {
1156	$active_settings[ $setting_key ] = $setting;
1157
1158	continue;
1159	}
1160
1161	$control = $controls[ $setting_key ];
1162
1163	if ( $this->is_control_visible( $control, $settings ) ) {
1164	$control_obj = Plugin::$instance->controls_manager->get_control( $control['type'] );
1165
1166	if ( $control_obj instanceof Control_Repeater ) {
1167	foreach ( $setting as & $item ) {
1168	$item = $this->get_active_settings( $item, $control['fields'] );
1169	}
1170	}
1171
1172	$active_settings[ $setting_key ] = $setting;
1173	} else {
1174	$active_settings[ $setting_key ] = null;
1175	}
1176	}
1177
1178	if ( $is_first_request ) {
1179	$this->active_settings = $active_settings;
1180	}
1181
1182	return $active_settings;
1183	}
1184
1185	/**
1186	* Get settings for display.
1187	*
1188	* Retrieve all the settings or, when requested, a specific setting for display.
1189	*
1190	* Unlike `get_settings()` method, this method retrieves only active settings
1191	* that passed all the conditions, rendered all the shortcodes and all the dynamic
1192	* tags.
1193	*
1194	* @since 2.0.0
1195	* @access public
1196	*
1197	* @param string $setting_key Optional. The key of the requested setting.
1198	* Default is null.
1199	*
1200	* @return mixed The settings.
1201	*/
1202	public function get_settings_for_display( $setting_key = null ) {
1203	if ( ! $this->parsed_active_settings ) {
1204	$this->parsed_active_settings = $this->get_active_settings( $this->get_parsed_dynamic_settings(), $this->get_controls() );
1205	}
1206
1207	return self::get_items( $this->parsed_active_settings, $setting_key );
1208	}
1209
1210	/**
1211	* Parse dynamic settings.
1212	*
1213	* Retrieve the settings with rendered dynamic tags.
1214	*
1215	* @since 2.0.0
1216	* @access public
1217	*
1218	* @param array $settings Optional. The requested setting. Default is null.
1219	* @param array $controls Optional. The controls array. Default is null.
1220	* @param array $all_settings Optional. All the settings. Default is null.
1221	*
1222	* @return array The settings with rendered dynamic tags.
1223	*/
1224	public function parse_dynamic_settings( $settings, $controls = null, $all_settings = null ) {
1225	if ( null === $all_settings ) {
1226	$all_settings = $this->get_settings();
1227	}
1228
1229	if ( null === $controls ) {
1230	$controls = $this->get_controls();
1231	}
1232
1233	foreach ( $controls as $control ) {
1234	$control_name = $control['name'];
1235	$control_obj = Plugin::$instance->controls_manager->get_control( $control['type'] );
1236
1237	if ( ! $control_obj instanceof Base_Data_Control ) {
1238	continue;
1239	}
1240
1241	if ( $control_obj instanceof Control_Repeater ) {
1242	if ( ! isset( $settings[ $control_name ] ) ) {
1243	continue;
1244	}
1245
1246	foreach ( $settings[ $control_name ] as & $field ) {
1247	$field = $this->parse_dynamic_settings( $field, $control['fields'], $field );
1248	}
1249
1250	continue;
1251	}
1252
1253	$dynamic_settings = $control_obj->get_settings( 'dynamic' );
1254
1255	if ( ! $dynamic_settings ) {
1256	$dynamic_settings = [];
1257	}
1258
1259	if ( ! empty( $control['dynamic'] ) ) {
1260	$dynamic_settings = array_merge( $dynamic_settings, $control['dynamic'] );
1261	}
1262
1263	if ( empty( $dynamic_settings ) \|\| ! isset( $all_settings[ Manager::DYNAMIC_SETTING_KEY ][ $control_name ] ) ) {
1264	continue;
1265	}
1266
1267	if ( ! empty( $dynamic_settings['active'] ) && ! empty( $all_settings[ Manager::DYNAMIC_SETTING_KEY ][ $control_name ] ) ) {
1268	$parsed_value = $control_obj->parse_tags( $all_settings[ Manager::DYNAMIC_SETTING_KEY ][ $control_name ], $dynamic_settings );
1269
1270	$dynamic_property = ! empty( $dynamic_settings['property'] ) ? $dynamic_settings['property'] : null;
1271
1272	if ( $dynamic_property ) {
1273	$settings[ $control_name ][ $dynamic_property ] = $parsed_value;
1274	} else {
1275	$settings[ $control_name ] = $parsed_value;
1276	}
1277	}
1278	}
1279
1280	return $settings;
1281	}
1282
1283	/**
1284	* Get frontend settings.
1285	*
1286	* Retrieve the settings for all frontend controls.
1287	*
1288	* @since 1.6.0
1289	* @access public
1290	*
1291	* @return array Frontend settings.
1292	*/
1293	public function get_frontend_settings() {
1294	$frontend_settings = array_intersect_key( $this->get_settings_for_display(), array_flip( $this->get_frontend_settings_keys() ) );
1295
1296	foreach ( $frontend_settings as $key => $setting ) {
1297	if ( in_array( $setting, [ null, '' ], true ) ) {
1298	unset( $frontend_settings[ $key ] );
1299	}
1300	}
1301
1302	return $frontend_settings;
1303	}
1304
1305	/**
1306	* Filter controls settings.
1307	*
1308	* Receives controls, settings and a callback function to filter the settings by
1309	* and returns filtered settings.
1310	*
1311	* @since 1.5.0
1312	* @access public
1313	*
1314	* @param callable $callback The callback function.
1315	* @param array $settings Optional. Control settings. Default is an empty
1316	* array.
1317	* @param array $controls Optional. Controls list. Default is an empty
1318	* array.
1319	*
1320	* @return array Filtered settings.
1321	*/
1322	public function filter_controls_settings( callable $callback, array $settings = [], array $controls = [] ) {
1323	if ( ! $settings ) {
1324	$settings = $this->get_settings();
1325	}
1326
1327	if ( ! $controls ) {
1328	$controls = $this->get_controls();
1329	}
1330
1331	return array_reduce(
1332	array_keys( $settings ), function( $filtered_settings, $setting_key ) use ( $controls, $settings, $callback ) {
1333	if ( isset( $controls[ $setting_key ] ) ) {
1334	$result = $callback( $settings[ $setting_key ], $controls[ $setting_key ] );
1335
1336	if ( null !== $result ) {
1337	$filtered_settings[ $setting_key ] = $result;
1338	}
1339	}
1340
1341	return $filtered_settings;
1342	}, []
1343	);
1344	}
1345
1346	/**
1347	* Whether the control is visible or not.
1348	*
1349	* Used to determine whether the control is visible or not.
1350	*
1351	* @since 1.4.0
1352	* @access public
1353	*
1354	* @param array $control The control.
1355	* @param array $values Optional. Condition values. Default is null.
1356	*
1357	* @return bool Whether the control is visible.
1358	*/
1359	public function is_control_visible( $control, $values = null ) {
1360	if ( null === $values ) {
1361	$values = $this->get_settings();
1362	}
1363
1364	if ( ! empty( $control['conditions'] ) && ! Conditions::check( $control['conditions'], $values ) ) {
1365	return false;
1366	}
1367
1368	if ( empty( $control['condition'] ) ) {
1369	return true;
1370	}
1371
1372	foreach ( $control['condition'] as $condition_key => $condition_value ) {
1373	preg_match( '/([a-z_\-0-9]+)(?:\[([a-z_]+)])?(!?)$/i', $condition_key, $condition_key_parts );
1374
1375	$pure_condition_key = $condition_key_parts[1];
1376	$condition_sub_key = $condition_key_parts[2];
1377	$is_negative_condition = ! ! $condition_key_parts[3];
1378
1379	if ( ! isset( $values[ $pure_condition_key ] ) \|\| null === $values[ $pure_condition_key ] ) {
1380	return false;
1381	}
1382
1383	$instance_value = $values[ $pure_condition_key ];
1384
1385	if ( $condition_sub_key && is_array( $instance_value ) ) {
1386	if ( ! isset( $instance_value[ $condition_sub_key ] ) ) {
1387	return false;
1388	}
1389
1390	$instance_value = $instance_value[ $condition_sub_key ];
1391	}
1392
1393	/**
1394	* If the $condition_value is a non empty array - check if the $condition_value contains the $instance_value,
1395	* If the $instance_value is a non empty array - check if the $instance_value contains the $condition_value
1396	* otherwise check if they are equal. ( and give the ability to check if the value is an empty array )
1397	*/
1398	if ( is_array( $condition_value ) && ! empty( $condition_value ) ) {
1399	$is_contains = in_array( $instance_value, $condition_value, true );
1400	} elseif ( is_array( $instance_value ) && ! empty( $instance_value ) ) {
1401	$is_contains = in_array( $condition_value, $instance_value, true );
1402	} else {
1403	$is_contains = $instance_value === $condition_value;
1404	}
1405
1406	if ( $is_negative_condition && $is_contains \|\| ! $is_negative_condition && ! $is_contains ) {
1407	return false;
1408	}
1409	}
1410
1411	return true;
1412	}
1413
1414	/**
1415	* Start controls section.
1416	*
1417	* Used to add a new section of controls. When you use this method, all the
1418	* registered controls from this point will be assigned to this section,
1419	* until you close the section using `end_controls_section()` method.
1420	*
1421	* This method should be used inside `register_controls()`.
1422	*
1423	* @since 1.4.0
1424	* @access public
1425	*
1426	* @param string $section_id Section ID.
1427	* @param array $args Section arguments Optional.
1428	*/
1429	public function start_controls_section( $section_id, array $args = [] ) {
1430	$stack_name = $this->get_name();
1431
1432	/**
1433	* Before section start.
1434	*
1435	* Fires before Elementor section starts in the editor panel.
1436	*
1437	* @since 1.4.0
1438	*
1439	* @param Controls_Stack $this The control.
1440	* @param string $section_id Section ID.
1441	* @param array $args Section arguments.
1442	*/
1443	do_action( 'elementor/element/before_section_start', $this, $section_id, $args );
1444
1445	/**
1446	* Before section start.
1447	*
1448	* Fires before Elementor section starts in the editor panel.
1449	*
1450	* The dynamic portions of the hook name, `$stack_name` and `$section_id`, refers to the stack name and section ID, respectively.
1451	*
1452	* @since 1.4.0
1453	*
1454	* @param Controls_Stack $this The control.
1455	* @param array $args Section arguments.
1456	*/
1457	do_action( "elementor/element/{$stack_name}/{$section_id}/before_section_start", $this, $args );
1458
1459	$args['type'] = Controls_Manager::SECTION;
1460
1461	$this->add_control( $section_id, $args );
1462
1463	if ( null !== $this->current_section ) {
1464	wp_die( sprintf( 'Elementor: You can\'t start a section before the end of the previous section "%s".', $this->current_section['section'] ) ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
1465	}
1466
1467	$this->current_section = $this->get_section_args( $section_id );
1468
1469	if ( $this->injection_point ) {
1470	$this->injection_point['section'] = $this->current_section;
1471	}
1472
1473	/**
1474	* After section start.
1475	*
1476	* Fires after Elementor section starts in the editor panel.
1477	*
1478	* @since 1.4.0
1479	*
1480	* @param Controls_Stack $this The control.
1481	* @param string $section_id Section ID.
1482	* @param array $args Section arguments.
1483	*/
1484	do_action( 'elementor/element/after_section_start', $this, $section_id, $args );
1485
1486	/**
1487	* After section start.
1488	*
1489	* Fires after Elementor section starts in the editor panel.
1490	*
1491	* The dynamic portions of the hook name, `$stack_name` and `$section_id`, refers to the stack name and section ID, respectively.
1492	*
1493	* @since 1.4.0
1494	*
1495	* @param Controls_Stack $this The control.
1496	* @param array $args Section arguments.
1497	*/
1498	do_action( "elementor/element/{$stack_name}/{$section_id}/after_section_start", $this, $args );
1499	}
1500
1501	/**
1502	* End controls section.
1503	*
1504	* Used to close an existing open controls section. When you use this method
1505	* it stops adding new controls to this section.
1506	*
1507	* This method should be used inside `register_controls()`.
1508	*
1509	* @since 1.4.0
1510	* @access public
1511	*/
1512	public function end_controls_section() {
1513	$stack_name = $this->get_name();
1514
1515	// Save the current section for the action.
1516	$current_section = $this->current_section;
1517	$section_id = $current_section['section'];
1518	$args = [
1519	'tab' => $current_section['tab'],
1520	];
1521
1522	/**
1523	* Before section end.
1524	*
1525	* Fires before Elementor section ends in the editor panel.
1526	*
1527	* @since 1.4.0
1528	*
1529	* @param Controls_Stack $this The control.
1530	* @param string $section_id Section ID.
1531	* @param array $args Section arguments.
1532	*/
1533	do_action( 'elementor/element/before_section_end', $this, $section_id, $args );
1534
1535	/**
1536	* Before section end.
1537	*
1538	* Fires before Elementor section ends in the editor panel.
1539	*
1540	* The dynamic portions of the hook name, `$stack_name` and `$section_id`, refers to the stack name and section ID, respectively.
1541	*
1542	* @since 1.4.0
1543	*
1544	* @param Controls_Stack $this The control.
1545	* @param array $args Section arguments.
1546	*/
1547	do_action( "elementor/element/{$stack_name}/{$section_id}/before_section_end", $this, $args );
1548
1549	$this->current_section = null;
1550
1551	/**
1552	* After section end.
1553	*
1554	* Fires after Elementor section ends in the editor panel.
1555	*
1556	* @since 1.4.0
1557	*
1558	* @param Controls_Stack $this The control.
1559	* @param string $section_id Section ID.
1560	* @param array $args Section arguments.
1561	*/
1562	do_action( 'elementor/element/after_section_end', $this, $section_id, $args );
1563
1564	/**
1565	* After section end.
1566	*
1567	* Fires after Elementor section ends in the editor panel.
1568	*
1569	* The dynamic portions of the hook name, `$stack_name` and `$section_id`, refers to the stack name and section ID, respectively.
1570	*
1571	* @since 1.4.0
1572	*
1573	* @param Controls_Stack $this The control.
1574	* @param array $args Section arguments.
1575	*/
1576	do_action( "elementor/element/{$stack_name}/{$section_id}/after_section_end", $this, $args );
1577	}
1578
1579	/**
1580	* Start controls tabs.
1581	*
1582	* Used to add a new set of tabs inside a section. You should use this
1583	* method before adding new individual tabs using `start_controls_tab()`.
1584	* Each tab added after this point will be assigned to this group of tabs,
1585	* until you close it using `end_controls_tabs()` method.
1586	*
1587	* This method should be used inside `register_controls()`.
1588	*
1589	* @since 1.4.0
1590	* @access public
1591	*
1592	* @param string $tabs_id Tabs ID.
1593	* @param array $args Tabs arguments.
1594	*/
1595	public function start_controls_tabs( $tabs_id, array $args = [] ) {
1596	if ( null !== $this->current_tab ) {
1597	wp_die( sprintf( 'Elementor: You can\'t start tabs before the end of the previous tabs "%s".', $this->current_tab['tabs_wrapper'] ) ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
1598	}
1599
1600	$args['type'] = Controls_Manager::TABS;
1601
1602	$this->add_control( $tabs_id, $args );
1603
1604	$this->current_tab = [
1605	'tabs_wrapper' => $tabs_id,
1606	];
1607
1608	foreach ( [ 'condition', 'conditions' ] as $key ) {
1609	if ( ! empty( $args[ $key ] ) ) {
1610	$this->current_tab[ $key ] = $args[ $key ];
1611	}
1612	}
1613
1614	if ( $this->injection_point ) {
1615	$this->injection_point['tab'] = $this->current_tab;
1616	}
1617	}
1618
1619	/**
1620	* End controls tabs.
1621	*
1622	* Used to close an existing open controls tabs. When you use this method it
1623	* stops adding new controls to this tabs.
1624	*
1625	* This method should be used inside `register_controls()`.
1626	*
1627	* @since 1.4.0
1628	* @access public
1629	*/
1630	public function end_controls_tabs() {
1631	$this->current_tab = null;
1632	}
1633
1634	/**
1635	* Start controls tab.
1636	*
1637	* Used to add a new tab inside a group of tabs. Use this method before
1638	* adding new individual tabs using `start_controls_tab()`.
1639	* Each tab added after this point will be assigned to this group of tabs,
1640	* until you close it using `end_controls_tab()` method.
1641	*
1642	* This method should be used inside `register_controls()`.
1643	*
1644	* @since 1.4.0
1645	* @access public
1646	*
1647	* @param string $tab_id Tab ID.
1648	* @param array $args Tab arguments.
1649	*/
1650	public function start_controls_tab( $tab_id, $args ) {
1651	if ( ! empty( $this->current_tab['inner_tab'] ) ) {
1652	wp_die( sprintf( 'Elementor: You can\'t start a tab before the end of the previous tab "%s".', $this->current_tab['inner_tab'] ) ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
1653	}
1654
1655	$args['type'] = Controls_Manager::TAB;
1656	$args['tabs_wrapper'] = $this->current_tab['tabs_wrapper'];
1657
1658	$this->add_control( $tab_id, $args );
1659
1660	$this->current_tab['inner_tab'] = $tab_id;
1661
1662	if ( $this->injection_point ) {
1663	$this->injection_point['tab']['inner_tab'] = $this->current_tab['inner_tab'];
1664	}
1665	}
1666
1667	/**
1668	* End controls tab.
1669	*
1670	* Used to close an existing open controls tab. When you use this method it
1671	* stops adding new controls to this tab.
1672	*
1673	* This method should be used inside `register_controls()`.
1674	*
1675	* @since 1.4.0
1676	* @access public
1677	*/
1678	public function end_controls_tab() {
1679	unset( $this->current_tab['inner_tab'] );
1680	}
1681
1682	/**
1683	* Start popover.
1684	*
1685	* Used to add a new set of controls in a popover. When you use this method,
1686	* all the registered controls from this point will be assigned to this
1687	* popover, until you close the popover using `end_popover()` method.
1688	*
1689	* This method should be used inside `register_controls()`.
1690	*
1691	* @since 1.9.0
1692	* @access public
1693	*/
1694	final public function start_popover() {
1695	$this->current_popover = [
1696	'initialized' => false,
1697	];
1698	}
1699
1700	/**
1701	* End popover.
1702	*
1703	* Used to close an existing open popover. When you use this method it stops
1704	* adding new controls to this popover.
1705	*
1706	* This method should be used inside `register_controls()`.
1707	*
1708	* @since 1.9.0
1709	* @access public
1710	*/
1711	final public function end_popover() {
1712	$this->current_popover = null;
1713
1714	$last_control_key = $this->get_control_key( $this->get_pointer_index() - 1 );
1715
1716	$args = [
1717	'popover' => [
1718	'end' => true,
1719	],
1720	];
1721
1722	$options = [
1723	'recursive' => true,
1724	];
1725
1726	$this->update_control( $last_control_key, $args, $options );
1727	}
1728
1729	/**
1730	* Add render attribute.
1731	*
1732	* Used to add attributes to a specific HTML element.
1733	*
1734	* The HTML tag is represented by the element parameter, then you need to
1735	* define the attribute key and the attribute key. The final result will be:
1736	* `<element attribute_key="attribute_value">`.
1737	*
1738	* Example usage:
1739	*
1740	* `$this->add_render_attribute( 'wrapper', 'class', 'custom-widget-wrapper-class' );`
1741	* `$this->add_render_attribute( 'widget', 'id', 'custom-widget-id' );`
1742	* `$this->add_render_attribute( 'button', [ 'class' => 'custom-button-class', 'id' => 'custom-button-id' ] );`
1743	*
1744	* @since 1.0.0
1745	* @access public
1746	*
1747	* @param array\|string $element The HTML element.
1748	* @param array\|string $key Optional. Attribute key. Default is null.
1749	* @param array\|string $value Optional. Attribute value. Default is null.
1750	* @param bool $overwrite Optional. Whether to overwrite existing
1751	* attribute. Default is false, not to overwrite.
1752	*
1753	* @return self Current instance of the element.
1754	*/
1755	public function add_render_attribute( $element, $key = null, $value = null, $overwrite = false ) {
1756	if ( is_array( $element ) ) {
1757	foreach ( $element as $element_key => $attributes ) {
1758	$this->add_render_attribute( $element_key, $attributes, null, $overwrite );
1759	}
1760
1761	return $this;
1762	}
1763
1764	if ( is_array( $key ) ) {
1765	foreach ( $key as $attribute_key => $attributes ) {
1766	$this->add_render_attribute( $element, $attribute_key, $attributes, $overwrite );
1767	}
1768
1769	return $this;
1770	}
1771
1772	if ( empty( $this->render_attributes[ $element ][ $key ] ) ) {
1773	$this->render_attributes[ $element ][ $key ] = [];
1774	}
1775
1776	settype( $value, 'array' );
1777
1778	if ( $overwrite ) {
1779	$this->render_attributes[ $element ][ $key ] = $value;
1780	} else {
1781	$this->render_attributes[ $element ][ $key ] = array_merge( $this->render_attributes[ $element ][ $key ], $value );
1782	}
1783
1784	return $this;
1785	}
1786
1787	/**
1788	* Get Render Attributes
1789	*
1790	* Used to retrieve render attribute.
1791	*
1792	* The returned array is either all elements and their attributes if no `$element` is specified, an array of all
1793	* attributes of a specific element or a specific attribute properties if `$key` is specified.
1794	*
1795	* Returns null if one of the requested parameters isn't set.
1796	*
1797	* @since 2.2.6
1798	* @access public
1799	* @param string $element
1800	* @param string $key
1801	*
1802	* @return array
1803	*/
1804	public function get_render_attributes( $element = '', $key = '' ) {
1805	$attributes = $this->render_attributes;
1806
1807	if ( $element ) {
1808	if ( ! isset( $attributes[ $element ] ) ) {
1809	return null;
1810	}
1811
1812	$attributes = $attributes[ $element ];
1813
1814	if ( $key ) {
1815	if ( ! isset( $attributes[ $key ] ) ) {
1816	return null;
1817	}
1818
1819	$attributes = $attributes[ $key ];
1820	}
1821	}
1822
1823	return $attributes;
1824	}
1825
1826	/**
1827	* Set render attribute.
1828	*
1829	* Used to set the value of the HTML element render attribute or to update
1830	* an existing render attribute.
1831	*
1832	* @since 1.0.0
1833	* @access public
1834	*
1835	* @param array\|string $element The HTML element.
1836	* @param array\|string $key Optional. Attribute key. Default is null.
1837	* @param array\|string $value Optional. Attribute value. Default is null.
1838	*
1839	* @return self Current instance of the element.
1840	*/
1841	public function set_render_attribute( $element, $key = null, $value = null ) {
1842	return $this->add_render_attribute( $element, $key, $value, true );
1843	}
1844
1845	/**
1846	* Remove render attribute.
1847	*
1848	* Used to remove an element (with its keys and their values), key (with its values),
1849	* or value/s from an HTML element's render attribute.
1850	*
1851	* @since 2.7.0
1852	* @access public
1853	*
1854	* @param string $element The HTML element.
1855	* @param string $key Optional. Attribute key. Default is null.
1856	* @param array\|string $values Optional. Attribute value/s. Default is null.
1857	*/
1858	public function remove_render_attribute( $element, $key = null, $values = null ) {
1859	if ( $key && ! isset( $this->render_attributes[ $element ][ $key ] ) ) {
1860	return;
1861	}
1862
1863	if ( $values ) {
1864	$values = (array) $values;
1865
1866	$this->render_attributes[ $element ][ $key ] = array_diff( $this->render_attributes[ $element ][ $key ], $values );
1867
1868	return;
1869	}
1870
1871	if ( $key ) {
1872	unset( $this->render_attributes[ $element ][ $key ] );
1873
1874	return;
1875	}
1876
1877	if ( isset( $this->render_attributes[ $element ] ) ) {
1878	unset( $this->render_attributes[ $element ] );
1879	}
1880	}
1881
1882	/**
1883	* Get render attribute string.
1884	*
1885	* Used to retrieve the value of the render attribute.
1886	*
1887	* @since 1.0.0
1888	* @access public
1889	*
1890	* @param string $element The element.
1891	*
1892	* @return string Render attribute string, or an empty string if the attribute
1893	* is empty or not exist.
1894	*/
1895	public function get_render_attribute_string( $element ) {
1896	if ( empty( $this->render_attributes[ $element ] ) ) {
1897	return '';
1898	}
1899
1900	return Utils::render_html_attributes( $this->render_attributes[ $element ] );
1901	}
1902
1903	/**
1904	* Print render attribute string.
1905	*
1906	* Used to output the rendered attribute.
1907	*
1908	* @since 2.0.0
1909	* @access public
1910	*
1911	* @param array\|string $element The element.
1912	*/
1913	public function print_render_attribute_string( $element ) {
1914	echo $this->get_render_attribute_string( $element ); // XSS ok.
1915	}
1916
1917	/**
1918	* Print element template.
1919	*
1920	* Used to generate the element template on the editor.
1921	*
1922	* @since 2.0.0
1923	* @access public
1924	*/
1925	public function print_template() {
1926	ob_start();
1927
1928	// TODO: This is for backwards compatibility starting from 2.9.0
1929	// This `if` statement should be removed when the method is removed
1930	if ( $this->has_own_method( '_content_template', self::class ) ) {
1931	Plugin::$instance->modules_manager->get_modules( 'dev-tools' )->deprecation->deprecated_function( '_content_template', '2.9.0', __CLASS__ . '::content_template()' );
1932
1933	$this->_content_template();
1934	} else {
1935	$this->content_template();
1936	}
1937
1938	$template_content = ob_get_clean();
1939
1940	$element_type = $this->get_type();
1941
1942	/**
1943	* Template content.
1944	*
1945	* Filters the controls stack template content before it's printed in the editor.
1946	*
1947	* The dynamic portion of the hook name, `$element_type`, refers to the element type.
1948	*
1949	* @since 1.0.0
1950	*
1951	* @param string $content_template The controls stack template in the editor.
1952	* @param Controls_Stack $this The controls stack.
1953	*/
1954	$template_content = apply_filters( "elementor/{$element_type}/print_template", $template_content, $this );
1955
1956	if ( empty( $template_content ) ) {
1957	return;
1958	}
1959	?>
1960	<script type="text/html" id="tmpl-elementor-<?php echo esc_attr( $this->get_name() ); ?>-content">
1961	<?php $this->print_template_content( $template_content ); ?>
1962	</script>
1963	<?php
1964	}
1965
1966	/**
1967	* Start injection.
1968	*
1969	* Used to inject controls and sections to a specific position in the stack.
1970	*
1971	* When you use this method, all the registered controls and sections will
1972	* be injected to a specific position in the stack, until you stop the
1973	* injection using `end_injection()` method.
1974	*
1975	* @since 1.7.1
1976	* @access public
1977	*
1978	* @param array $position {
1979	* The position where to start the injection.
1980	*
1981	* @type string $type Injection type, either `control` or `section`.
1982	* Default is `control`.
1983	* @type string $at Where to inject. If `$type` is `control` accepts
1984	* `before` and `after`. If `$type` is `section`
1985	* accepts `start` and `end`. Default values based on
1986	* the `type`.
1987	* @type string $of Control/Section ID.
1988	* }
1989	*/
1990	final public function start_injection( array $position ) {
1991	if ( $this->injection_point ) {
1992	wp_die( 'A controls injection is already opened. Please close current injection before starting a new one (use `end_injection`).' );
1993	}
1994
1995	$this->injection_point = $this->get_position_info( $position );
1996	}
1997
1998	/**
1999	* End injection.
2000	*
2001	* Used to close an existing opened injection point.
2002	*
2003	* When you use this method it stops adding new controls and sections to
2004	* this point and continue to add controls to the regular position in the
2005	* stack.
2006	*
2007	* @since 1.7.1
2008	* @access public
2009	*/
2010	final public function end_injection() {
2011	$this->injection_point = null;
2012	}
2013
2014	/**
2015	* Get injection point.
2016	*
2017	* Retrieve the injection point in the stack where new controls and sections
2018	* will be inserted.
2019	*
2020	* @since 1.9.2
2021	* @access public
2022	*
2023	* @return array\|null An array when an injection point is defined, null
2024	* otherwise.
2025	*/
2026	final public function get_injection_point() {
2027	return $this->injection_point;
2028	}
2029
2030	/**
2031	* Register controls.
2032	*
2033	* Used to add new controls to any element type. For example, external
2034	* developers use this method to register controls in a widget.
2035	*
2036	* Should be inherited and register new controls using `add_control()`,
2037	* `add_responsive_control()` and `add_group_control()`, inside control
2038	* wrappers like `start_controls_section()`, `start_controls_tabs()` and
2039	* `start_controls_tab()`.
2040	*
2041	* @since 1.4.0
2042	* @access protected
2043	* @deprecated 3.1.0 Use `Controls_Stack::register_controls()` instead
2044	*/
2045	protected function _register_controls() {
2046	Plugin::$instance->modules_manager->get_modules( 'dev-tools' )->deprecation->deprecated_function( __METHOD__, '3.1.0', __CLASS__ . '::register_controls()' );
2047
2048	$this->register_controls();
2049	}
2050
2051	/**
2052	* Register controls.
2053	*
2054	* Used to add new controls to any element type. For example, external
2055	* developers use this method to register controls in a widget.
2056	*
2057	* Should be inherited and register new controls using `add_control()`,
2058	* `add_responsive_control()` and `add_group_control()`, inside control
2059	* wrappers like `start_controls_section()`, `start_controls_tabs()` and
2060	* `start_controls_tab()`.
2061	*
2062	* @since 3.1.0
2063	* @access protected
2064	*/
2065	protected function register_controls() {}
2066
2067	/**
2068	* Get default data.
2069	*
2070	* Retrieve the default data. Used to reset the data on initialization.
2071	*
2072	* @since 1.4.0
2073	* @access protected
2074	*
2075	* @return array Default data.
2076	*/
2077	protected function get_default_data() {
2078	return [
2079	'id' => 0,
2080	'settings' => [],
2081	];
2082	}
2083
2084	/**
2085	* @since 2.3.0
2086	* @access protected
2087	*/
2088	protected function get_init_settings() {
2089	$settings = $this->get_data( 'settings' );
2090
2091	foreach ( $this->get_controls() as $control ) {
2092	$control_obj = Plugin::$instance->controls_manager->get_control( $control['type'] );
2093
2094	if ( ! $control_obj instanceof Base_Data_Control ) {
2095	continue;
2096	}
2097
2098	$control = array_merge_recursive( $control_obj->get_settings(), $control );
2099
2100	$settings[ $control['name'] ] = $control_obj->get_value( $control, $settings );
2101	}
2102
2103	return $settings;
2104	}
2105
2106	/**
2107	* Get initial config.
2108	*
2109	* Retrieve the current element initial configuration - controls list and
2110	* the tabs assigned to the control.
2111	*
2112	* @since 2.9.0
2113	* @access protected
2114	*
2115	* @return array The initial config.
2116	*/
2117	protected function get_initial_config() {
2118	return [
2119	'controls' => $this->get_controls(),
2120	];
2121	}
2122
2123	/**
2124	* Get initial config.
2125	*
2126	* Retrieve the current element initial configuration - controls list and
2127	* the tabs assigned to the control.
2128	*
2129	* @since 1.4.0
2130	* @deprecated 2.9.0 use `get_initial_config()` instead
2131	* @access protected
2132	*
2133	* @return array The initial config.
2134	*/
2135	protected function _get_initial_config() {
2136	Plugin::$instance->modules_manager->get_modules( 'dev-tools' )->deprecation->deprecated_function( __METHOD__, '2.9.0', __CLASS__ . '::get_initial_config()' );
2137
2138	return $this->get_initial_config();
2139	}
2140
2141	/**
2142	* Get section arguments.
2143	*
2144	* Retrieve the section arguments based on section ID.
2145	*
2146	* @since 1.4.0
2147	* @access protected
2148	*
2149	* @param string $section_id Section ID.
2150	*
2151	* @return array Section arguments.
2152	*/
2153	protected function get_section_args( $section_id ) {
2154	$section_control = $this->get_controls( $section_id );
2155
2156	$section_args_keys = [ 'tab', 'condition' ];
2157
2158	$args = array_intersect_key( $section_control, array_flip( $section_args_keys ) );
2159
2160	$args['section'] = $section_id;
2161
2162	return $args;
2163	}
2164
2165	/**
2166	* Render element.
2167	*
2168	* Generates the final HTML on the frontend.
2169	*
2170	* @since 2.0.0
2171	* @access protected
2172	*/
2173	protected function render() {}
2174
2175	/**
2176	* Render element in static mode.
2177	*
2178	* If not inherent will call the base render.
2179	*/
2180	protected function render_static() {
2181	$this->render();
2182	}
2183
2184	/**
2185	* Determine the render logic.
2186	*/
2187	protected function render_by_mode() {
2188	if ( Plugin::$instance->frontend->is_static_render_mode() ) {
2189	$this->render_static();
2190
2191	return;
2192	}
2193
2194	$this->render();
2195	}
2196
2197	/**
2198	* Print content template.
2199	*
2200	* Used to generate the content template on the editor, using a
2201	* Backbone JavaScript template.
2202	*
2203	* @access protected
2204	* @since 2.0.0
2205	*
2206	* @param string $template_content Template content.
2207	*/
2208	protected function print_template_content( $template_content ) {
2209	echo $template_content; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
2210	}
2211
2212	/**
2213	* Render element output in the editor.
2214	*
2215	* Used to generate the live preview, using a Backbone JavaScript template.
2216	*
2217	* @since 2.9.0
2218	* @access protected
2219	*/
2220	protected function content_template() {}
2221
2222	/**
2223	* Render element output in the editor.
2224	*
2225	* Used to generate the live preview, using a Backbone JavaScript template.
2226	*
2227	* @since 2.0.0
2228	* @deprecated 2.9.0 use `content_template()` instead
2229	* @access protected
2230	*/
2231	protected function _content_template() {
2232	Plugin::$instance->modules_manager->get_modules( 'dev-tools' )->deprecation->deprecated_function( __METHOD__, '2.9.0', __CLASS__ . '::content_template()' );
2233
2234	$this->content_template();
2235	}
2236
2237	/**
2238	* Initialize controls.
2239	*
2240	* Register the all controls added by `register_controls()`.
2241	*
2242	* @since 2.0.0
2243	* @access protected
2244	*/
2245	protected function init_controls() {
2246	Plugin::$instance->controls_manager->open_stack( $this );
2247
2248	// TODO: This is for backwards compatibility starting from 2.9.0
2249	// This `if` statement should be removed when the method is removed
2250	if ( $this->has_own_method( '_register_controls', self::class ) ) {
2251	Plugin::$instance->modules_manager->get_modules( 'dev-tools' )->deprecation->deprecated_function( '_register_controls', '3.1.0', __CLASS__ . '::register_controls()' );
2252
2253	$this->_register_controls();
2254	} else {
2255	$this->register_controls();
2256	}
2257	}
2258
2259	protected function handle_control_position( array $args, $control_id, $overwrite ) {
2260	if ( isset( $args['type'] ) && in_array( $args['type'], [ Controls_Manager::SECTION, Controls_Manager::WP_WIDGET ], true ) ) {
2261	return $args;
2262	}
2263
2264	$target_section_args = $this->current_section;
2265
2266	$target_tab = $this->current_tab;
2267
2268	if ( $this->injection_point ) {
2269	$target_section_args = $this->injection_point['section'];
2270
2271	if ( ! empty( $this->injection_point['tab'] ) ) {
2272	$target_tab = $this->injection_point['tab'];
2273	}
2274	}
2275
2276	if ( null !== $target_section_args ) {
2277	if ( ! empty( $args['section'] ) \|\| ! empty( $args['tab'] ) ) {
2278	_doing_it_wrong( sprintf( '%s::%s', get_called_class(), __FUNCTION__ ), sprintf( 'Cannot redeclare control with `tab` or `section` args inside section "%s".', $control_id ), '1.0.0' ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
2279	}
2280
2281	$args = array_replace_recursive( $target_section_args, $args );
2282
2283	if ( null !== $target_tab ) {
2284	$args = array_replace_recursive( $target_tab, $args );
2285	}
2286	} elseif ( empty( $args['section'] ) && ( ! $overwrite \|\| is_wp_error( Plugin::$instance->controls_manager->get_control_from_stack( $this->get_unique_name(), $control_id ) ) ) ) {
2287	wp_die( sprintf( '%s::%s: Cannot add a control outside of a section (use `start_controls_section`).', get_called_class(), __FUNCTION__ ) ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
2288	}
2289
2290	return $args;
2291	}
2292
2293	/**
2294	* Initialize the class.
2295	*
2296	* Set the raw data, the ID and the parsed settings.
2297	*
2298	* @since 2.9.0
2299	* @access protected
2300	*
2301	* @param array $data Initial data.
2302	*/
2303	protected function init( $data ) {
2304	$this->data = array_merge( $this->get_default_data(), $data );
2305
2306	$this->id = $data['id'];
2307	}
2308
2309	/**
2310	* Initialize the class.
2311	*
2312	* Set the raw data, the ID and the parsed settings.
2313	*
2314	* @since 1.4.0
2315	* @deprecated 2.9.0 use `init()` instead
2316	* @access protected
2317	*
2318	* @param array $data Initial data.
2319	*/
2320	protected function _init( $data ) {
2321	Plugin::$instance->modules_manager->get_modules( 'dev-tools' )->deprecation->deprecated_function( __METHOD__, '2.9.0', __CLASS__ . '::init()' );
2322
2323	$this->init( $data );
2324	}
2325
2326	/**
2327	* Sanitize initial data.
2328	*
2329	* Performs settings cleaning and sanitization.
2330	*
2331	* @since 2.1.5
2332	* @access private
2333	*
2334	* @param array $settings Settings to sanitize.
2335	* @param array $controls Optional. An array of controls. Default is an
2336	* empty array.
2337	*
2338	* @return array Sanitized settings.
2339	*/
2340	private function sanitize_settings( array $settings, array $controls = [] ) {
2341	if ( ! $controls ) {
2342	$controls = $this->get_controls();
2343	}
2344
2345	foreach ( $controls as $control ) {
2346	$control_obj = Plugin::$instance->controls_manager->get_control( $control['type'] );
2347
2348	if ( $control_obj instanceof Control_Repeater ) {
2349	if ( empty( $settings[ $control['name'] ] ) ) {
2350	continue;
2351	}
2352
2353	foreach ( $settings[ $control['name'] ] as $index => $repeater_row_data ) {
2354	$sanitized_row_data = $this->sanitize_settings( $repeater_row_data, $control['fields'] );
2355
2356	$settings[ $control['name'] ][ $index ] = $sanitized_row_data;
2357	}
2358
2359	continue;
2360	}
2361
2362	$is_dynamic = isset( $settings[ Manager::DYNAMIC_SETTING_KEY ][ $control['name'] ] );
2363
2364	if ( ! $is_dynamic ) {
2365	continue;
2366	}
2367
2368	$value_to_check = $settings[ Manager::DYNAMIC_SETTING_KEY ][ $control['name'] ];
2369
2370	$tag_text_data = Plugin::$instance->dynamic_tags->tag_text_to_tag_data( $value_to_check );
2371
2372	if ( ! Plugin::$instance->dynamic_tags->get_tag_info( $tag_text_data['name'] ) ) {
2373	unset( $settings[ Manager::DYNAMIC_SETTING_KEY ][ $control['name'] ] );
2374	}
2375	}
2376
2377	return $settings;
2378	}
2379
2380	/**
2381	* Controls stack constructor.
2382	*
2383	* Initializing the control stack class using `$data`. The `$data` is required
2384	* for a normal instance. It is optional only for internal `type instance`.
2385	*
2386	* @since 1.4.0
2387	* @access public
2388	*
2389	* @param array $data Optional. Control stack data. Default is an empty array.
2390	*/
2391	public function __construct( array $data = [] ) {
2392	if ( $data ) {
2393	// TODO: This is for backwards compatibility starting from 2.9.0
2394	// This if statement should be removed when the method is hard-deprecated
2395	if ( $this->has_own_method( '_init', self::class ) ) {
2396	Plugin::$instance->modules_manager->get_modules( 'dev-tools' )->deprecation->deprecated_function( '_init', '2.9.0', __CLASS__ . '::init()' );
2397
2398	$this->_init( $data );
2399	} else {
2400	$this->init( $data );
2401	}
2402	}
2403	}
2404	}
2405