elementor / includes / base / controls-stack.php

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

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