elementor / includes / base / element-base.php

element-base.php in Elementor Website Builder – more than just a page builder 3.7.4, at includes/base/element-base.php

920 lines 21.8 KB

Raw Download Zip

1	<?php
2	namespace Elementor;
3
4	if ( ! defined( 'ABSPATH' ) ) {
5	exit; // Exit if accessed directly.
6	}
7
8	/**
9	* Elementor element base.
10	*
11	* An abstract class to register new Elementor elements. It extended the
12	* `Controls_Stack` class to inherit its properties.
13	*
14	* This abstract class must be extended in order to register new elements.
15	*
16	* @since 1.0.0
17	* @abstract
18	*/
19	abstract class Element_Base extends Controls_Stack {
20
21	/**
22	* Child elements.
23	*
24	* Holds all the child elements of the element.
25	*
26	* @access private
27	*
28	* @var Element_Base[]
29	*/
30	private $children;
31
32	/**
33	* Element default arguments.
34	*
35	* Holds all the default arguments of the element. Used to store additional
36	* data. For example WordPress widgets use this to store widget names.
37	*
38	* @access private
39	*
40	* @var array
41	*/
42	private $default_args = [];
43
44	/**
45	* Is type instance.
46	*
47	* Whether the element is an instance of that type or not.
48	*
49	* @access private
50	*
51	* @var bool
52	*/
53	private $is_type_instance = true;
54
55	/**
56	* Depended scripts.
57	*
58	* Holds all the element depended scripts to enqueue.
59	*
60	* @since 1.9.0
61	* @access private
62	*
63	* @var array
64	*/
65	private $depended_scripts = [];
66
67	/**
68	* Depended styles.
69	*
70	* Holds all the element depended styles to enqueue.
71	*
72	* @since 1.9.0
73	* @access private
74	*
75	* @var array
76	*/
77	private $depended_styles = [];
78
79	/**
80	* Add script depends.
81	*
82	* Register new script to enqueue by the handler.
83	*
84	* @since 1.9.0
85	* @access public
86	*
87	* @param string $handler Depend script handler.
88	*/
89	public function add_script_depends( $handler ) {
90	$this->depended_scripts[] = $handler;
91	}
92
93	/**
94	* Add style depends.
95	*
96	* Register new style to enqueue by the handler.
97	*
98	* @since 1.9.0
99	* @access public
100	*
101	* @param string $handler Depend style handler.
102	*/
103	public function add_style_depends( $handler ) {
104	$this->depended_styles[] = $handler;
105	}
106
107	/**
108	* Get script dependencies.
109	*
110	* Retrieve the list of script dependencies the element requires.
111	*
112	* @since 1.3.0
113	* @access public
114	*
115	* @return array Element scripts dependencies.
116	*/
117	public function get_script_depends() {
118	return $this->depended_scripts;
119	}
120
121	/**
122	* Enqueue scripts.
123	*
124	* Registers all the scripts defined as element dependencies and enqueues
125	* them. Use `get_script_depends()` method to add custom script dependencies.
126	*
127	* @since 1.3.0
128	* @access public
129	*/
130	final public function enqueue_scripts() {
131	$deprecated_scripts = [
132	//Insert here when you have a deprecated script
133	];
134
135	foreach ( $this->get_script_depends() as $script ) {
136	if ( isset( $deprecated_scripts[ $script ] ) ) {
137	Utils::handle_deprecation( $script, $deprecated_scripts[ $script ]['version'], $deprecated_scripts[ $script ]['replacement'] );
138	}
139
140	wp_enqueue_script( $script );
141	}
142	}
143
144	/**
145	* Get style dependencies.
146	*
147	* Retrieve the list of style dependencies the element requires.
148	*
149	* @since 1.9.0
150	* @access public
151	*
152	* @return array Element styles dependencies.
153	*/
154	public function get_style_depends() {
155	return $this->depended_styles;
156	}
157
158	/**
159	* Enqueue styles.
160	*
161	* Registers all the styles defined as element dependencies and enqueues
162	* them. Use `get_style_depends()` method to add custom style dependencies.
163	*
164	* @since 1.9.0
165	* @access public
166	*/
167	final public function enqueue_styles() {
168	foreach ( $this->get_style_depends() as $style ) {
169	wp_enqueue_style( $style );
170	}
171	}
172
173	/**
174	* @since 1.0.0
175	* @deprecated 2.6.0
176	* @access public
177	* @static
178	*/
179	final public static function add_edit_tool() {}
180
181	/**
182	* @since 2.2.0
183	* @deprecated 2.6.0
184	* @access public
185	* @static
186	*/
187	final public static function is_edit_buttons_enabled() {
188	return get_option( 'elementor_edit_buttons' );
189	}
190
191	/**
192	* Get default child type.
193	*
194	* Retrieve the default child type based on element data.
195	*
196	* Note that not all elements support children.
197	*
198	* @since 1.0.0
199	* @access protected
200	* @abstract
201	*
202	* @param array $element_data Element data.
203	*
204	* @return Element_Base
205	*/
206	abstract protected function _get_default_child_type( array $element_data );
207
208	/**
209	* Before element rendering.
210	*
211	* Used to add stuff before the element.
212	*
213	* @since 1.0.0
214	* @access public
215	*/
216	public function before_render() {}
217
218	/**
219	* After element rendering.
220	*
221	* Used to add stuff after the element.
222	*
223	* @since 1.0.0
224	* @access public
225	*/
226	public function after_render() {}
227
228	/**
229	* Get element title.
230	*
231	* Retrieve the element title.
232	*
233	* @since 1.0.0
234	* @access public
235	*
236	* @return string Element title.
237	*/
238	public function get_title() {
239	return '';
240	}
241
242	/**
243	* Get element icon.
244	*
245	* Retrieve the element icon.
246	*
247	* @since 1.0.0
248	* @access public
249	*
250	* @return string Element icon.
251	*/
252	public function get_icon() {
253	return 'eicon-columns';
254	}
255
256	public function get_help_url() {
257	return 'https://go.elementor.com/widget-' . $this->get_name();
258	}
259
260	public function get_custom_help_url() {
261	return '';
262	}
263
264	/**
265	* Whether the reload preview is required.
266	*
267	* Used to determine whether the reload preview is required or not.
268	*
269	* @since 1.0.0
270	* @access public
271	*
272	* @return bool Whether the reload preview is required.
273	*/
274	public function is_reload_preview_required() {
275	return false;
276	}
277
278	/**
279	* @since 2.3.1
280	* @access protected
281	*/
282	protected function should_print_empty() {
283	return true;
284	}
285
286	/**
287	* Get child elements.
288	*
289	* Retrieve all the child elements of this element.
290	*
291	* @since 1.0.0
292	* @access public
293	*
294	* @return Element_Base[] Child elements.
295	*/
296	public function get_children() {
297	if ( null === $this->children ) {
298	$this->init_children();
299	}
300
301	return $this->children;
302	}
303
304	/**
305	* Get default arguments.
306	*
307	* Retrieve the element default arguments. Used to return all the default
308	* arguments or a specific default argument, if one is set.
309	*
310	* @since 1.0.0
311	* @access public
312	*
313	* @param array $item Optional. Default is null.
314	*
315	* @return array Default argument(s).
316	*/
317	public function get_default_args( $item = null ) {
318	return self::get_items( $this->default_args, $item );
319	}
320
321	/**
322	* Add new child element.
323	*
324	* Register new child element to allow hierarchy.
325	*
326	* @since 1.0.0
327	* @access public
328	* @param array $child_data Child element data.
329	* @param array $child_args Child element arguments.
330	*
331	* @return Element_Base\|false Child element instance, or false if failed.
332	*/
333	public function add_child( array $child_data, array $child_args = [] ) {
334	if ( null === $this->children ) {
335	$this->init_children();
336	}
337
338	$child_type = $this->get_child_type( $child_data );
339
340	if ( ! $child_type ) {
341	return false;
342	}
343
344	$child = Plugin::$instance->elements_manager->create_element_instance( $child_data, $child_args, $child_type );
345
346	if ( $child ) {
347	$this->children[] = $child;
348	}
349
350	return $child;
351	}
352
353	/**
354	* Add link render attributes.
355	*
356	* Used to add link tag attributes to a specific HTML element.
357	*
358	* The HTML link tag is represented by the element parameter. The `url_control` parameter
359	* needs to be an array of link settings in the same format they are set by Elementor's URL control.
360	*
361	* Example usage:
362	*
363	* `$this->add_link_attributes( 'button', $settings['link'] );`
364	*
365	* @since 2.8.0
366	* @access public
367	*
368	* @param array\|string $element The HTML element.
369	* @param array $url_control Array of link settings.
370	* @param bool $overwrite Optional. Whether to overwrite existing
371	* attribute. Default is false, not to overwrite.
372	*
373	* @return Element_Base Current instance of the element.
374	*/
375
376	public function add_link_attributes( $element, array $url_control, $overwrite = false ) {
377	$attributes = [];
378
379	if ( ! empty( $url_control['url'] ) ) {
380	$allowed_protocols = array_merge( wp_allowed_protocols(), [ 'skype', 'viber' ] );
381
382	$attributes['href'] = esc_url( $url_control['url'], $allowed_protocols );
383	}
384
385	if ( ! empty( $url_control['is_external'] ) ) {
386	$attributes['target'] = '_blank';
387	}
388
389	if ( ! empty( $url_control['nofollow'] ) ) {
390	$attributes['rel'] = 'nofollow';
391	}
392
393	if ( ! empty( $url_control['custom_attributes'] ) ) {
394	// Custom URL attributes should come as a string of comma-delimited key\|value pairs
395	$attributes = array_merge( $attributes, Utils::parse_custom_attributes( $url_control['custom_attributes'] ) );
396	}
397
398	if ( $attributes ) {
399	$this->add_render_attribute( $element, $attributes, null, $overwrite );
400	}
401
402	return $this;
403	}
404
405	/**
406	* Print element.
407	*
408	* Used to generate the element final HTML on the frontend and the editor.
409	*
410	* @since 1.0.0
411	* @access public
412	*/
413	public function print_element() {
414	$element_type = $this->get_type();
415
416	/**
417	* Before frontend element render.
418	*
419	* Fires before Elementor element is rendered in the frontend.
420	*
421	* @since 2.2.0
422	*
423	* @param Element_Base $this The element.
424	*/
425	do_action( 'elementor/frontend/before_render', $this );
426
427	/**
428	* Before frontend element render.
429	*
430	* Fires before Elementor element is rendered in the frontend.
431	*
432	* The dynamic portion of the hook name, `$element_type`, refers to the element type.
433	*
434	* @since 1.0.0
435	*
436	* @param Element_Base $this The element.
437	*/
438	do_action( "elementor/frontend/{$element_type}/before_render", $this );
439
440	ob_start();
441
442	if ( $this->has_own_method( '_print_content', self::class ) ) {
443	Plugin::$instance->modules_manager->get_modules( 'dev-tools' )->deprecation->deprecated_function( '_print_content', '3.1.0', __CLASS__ . '::print_content()' );
444
445	$this->_print_content();
446	} else {
447	$this->print_content();
448	}
449
450	$content = ob_get_clean();
451
452	$should_render = ( ! empty( $content ) \|\| $this->should_print_empty() );
453
454	/**
455	* Should the element be rendered for frontend
456	*
457	* Filters if the element should be rendered on frontend.
458	*
459	* @since 2.3.3
460	*
461	* @param bool true The element.
462	* @param Element_Base $this The element.
463	*/
464	$should_render = apply_filters( "elementor/frontend/{$element_type}/should_render", $should_render, $this );
465
466	if ( $should_render ) {
467	if ( $this->has_own_method( '_add_render_attributes', self::class ) ) {
468	Plugin::$instance->modules_manager->get_modules( 'dev-tools' )->deprecation->deprecated_function( '_add_render_attributes', '3.1.0', __CLASS__ . '::add_render_attributes()' );
469
470	$this->_add_render_attributes();
471	} else {
472	$this->add_render_attributes();
473	}
474
475	$this->before_render();
476	// PHPCS - The content has already been escaped by the `render` method.
477	echo $content; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
478	$this->after_render();
479
480	$this->enqueue_scripts();
481	$this->enqueue_styles();
482	}
483
484	/**
485	* After frontend element render.
486	*
487	* Fires after Elementor element is rendered in the frontend.
488	*
489	* The dynamic portion of the hook name, `$element_type`, refers to the element type.
490	*
491	* @since 1.0.0
492	*
493	* @param Element_Base $this The element.
494	*/
495	do_action( "elementor/frontend/{$element_type}/after_render", $this );
496
497	/**
498	* After frontend element render.
499	*
500	* Fires after Elementor element is rendered in the frontend.
501	*
502	* @since 2.3.0
503	*
504	* @param Element_Base $this The element.
505	*/
506	do_action( 'elementor/frontend/after_render', $this );
507	}
508
509	/**
510	* Get the element raw data.
511	*
512	* Retrieve the raw element data, including the id, type, settings, child
513	* elements and whether it is an inner element.
514	*
515	* The data with the HTML used always to display the data, but the Elementor
516	* editor uses the raw data without the HTML in order not to render the data
517	* again.
518	*
519	* @since 1.0.0
520	* @access public
521	*
522	* @param bool $with_html_content Optional. Whether to return the data with
523	* HTML content or without. Used for caching.
524	* Default is false, without HTML.
525	*
526	* @return array Element raw data.
527	*/
528	public function get_raw_data( $with_html_content = false ) {
529	$data = $this->get_data();
530
531	$elements = [];
532
533	foreach ( $this->get_children() as $child ) {
534	$elements[] = $child->get_raw_data( $with_html_content );
535	}
536
537	return [
538	'id' => $this->get_id(),
539	'elType' => $data['elType'],
540	'settings' => $data['settings'],
541	'elements' => $elements,
542	'isInner' => $data['isInner'],
543	];
544	}
545
546	public function get_data_for_save() {
547	$data = $this->get_raw_data();
548
549	$elements = [];
550
551	foreach ( $this->get_children() as $child ) {
552	$elements[] = $child->get_data_for_save();
553	}
554
555	if ( ! empty( $elements ) ) {
556	$data['elements'] = $elements;
557	}
558
559	if ( ! empty( $data['settings'] ) ) {
560	$data['settings'] = $this->on_save( $data['settings'] );
561	}
562
563	return $data;
564	}
565
566	/**
567	* Get unique selector.
568	*
569	* Retrieve the unique selector of the element. Used to set a unique HTML
570	* class for each HTML element. This way Elementor can set custom styles for
571	* each element.
572	*
573	* @since 1.0.0
574	* @access public
575	*
576	* @return string Unique selector.
577	*/
578	public function get_unique_selector() {
579	return '.elementor-element-' . $this->get_id();
580	}
581
582	/**
583	* Is type instance.
584	*
585	* Used to determine whether the element is an instance of that type or not.
586	*
587	* @since 1.0.0
588	* @access public
589	*
590	* @return bool Whether the element is an instance of that type.
591	*/
592	public function is_type_instance() {
593	return $this->is_type_instance;
594	}
595
596	/**
597	* On Import Replace Dynamic Content.
598	*
599	* @since 3.6.0
600	* @access public
601	*
602	* @return array Element data.
603	*/
604	public static function on_import_replace_dynamic_content( $config, $map_old_new_post_ids ) {
605	$tags_manager = Plugin::$instance->dynamic_tags;
606
607	if ( isset( $config['settings'][ $tags_manager::DYNAMIC_SETTING_KEY ] ) ) {
608	foreach ( $config['settings'][ $tags_manager::DYNAMIC_SETTING_KEY ] as $dynamic_name => $dynamic_value ) {
609	$tag_config = $tags_manager->tag_text_to_tag_data( $dynamic_value );
610	$tag_instance = $tags_manager->create_tag( $tag_config['id'], $tag_config['name'], $tag_config['settings'] );
611
612	if ( $tag_instance ) {
613	$tag_config = $tag_instance->on_import_replace_dynamic_content( $tag_config, $map_old_new_post_ids );
614	$config['settings'][ $tags_manager::DYNAMIC_SETTING_KEY ][ $dynamic_name ] = $tags_manager->tag_data_to_tag_text( $tag_config['id'], $tag_config['name'], $tag_config['settings'] );
615	}
616	}
617	}
618
619	return $config;
620	}
621
622	/**
623	* Add render attributes.
624	*
625	* Used to add attributes to the current element wrapper HTML tag.
626	*
627	* @since 1.3.0
628	* @access protected
629	* @deprecated 3.1.0
630	*/
631	protected function _add_render_attributes() {
632	Plugin::$instance->modules_manager->get_modules( 'dev-tools' )->deprecation->deprecated_function( __METHOD__, '3.1.0', __CLASS__ . '::add_render_attributes()' );
633
634	return $this->add_render_attributes();
635	}
636
637	/**
638	* Add render attributes.
639	*
640	* Used to add attributes to the current element wrapper HTML tag.
641	*
642	* @since 3.1.0
643	* @access protected
644	*/
645	protected function add_render_attributes() {
646	$id = $this->get_id();
647
648	$settings = $this->get_settings_for_display();
649	$frontend_settings = $this->get_frontend_settings();
650	$controls = $this->get_controls();
651
652	$this->add_render_attribute( '_wrapper', [
653	'class' => [
654	'elementor-element',
655	'elementor-element-' . $id,
656	],
657	'data-id' => $id,
658	'data-element_type' => $this->get_type(),
659	] );
660
661	$class_settings = [];
662
663	foreach ( $settings as $setting_key => $setting ) {
664	if ( isset( $controls[ $setting_key ]['prefix_class'] ) ) {
665	$class_settings[ $setting_key ] = $setting;
666	}
667	}
668
669	foreach ( $class_settings as $setting_key => $setting ) {
670	if ( empty( $setting ) && '0' !== $setting ) {
671	continue;
672	}
673
674	$this->add_render_attribute( '_wrapper', 'class', $controls[ $setting_key ]['prefix_class'] . $setting );
675	}
676
677	$_animation = ! empty( $settings['_animation'] );
678	$animation = ! empty( $settings['animation'] );
679	$has_animation = $_animation && 'none' !== $settings['_animation'] \|\| $animation && 'none' !== $settings['animation'];
680
681	if ( $has_animation ) {
682	$is_static_render_mode = Plugin::$instance->frontend->is_static_render_mode();
683
684	if ( ! $is_static_render_mode ) {
685	// Hide the element until the animation begins
686	$this->add_render_attribute( '_wrapper', 'class', 'elementor-invisible' );
687	}
688	}
689
690	if ( ! empty( $settings['_element_id'] ) ) {
691	$this->add_render_attribute( '_wrapper', 'id', trim( $settings['_element_id'] ) );
692	}
693
694	if ( $frontend_settings ) {
695	$this->add_render_attribute( '_wrapper', 'data-settings', wp_json_encode( $frontend_settings ) );
696	}
697
698	/**
699	* After element attribute rendered.
700	*
701	* Fires after the attributes of the element HTML tag are rendered.
702	*
703	* @since 2.3.0
704	*
705	* @param Element_Base $this The element.
706	*/
707	do_action( 'elementor/element/after_add_attributes', $this );
708	}
709
710	/**
711	* Add Hidden Device Controls
712	*
713	* Adds controls for hiding elements within certain devices' viewport widths. Adds a control for each active device.
714	*
715	* @since 3.4.0
716	* @access protected
717	*/
718	protected function add_hidden_device_controls() {
719	// The 'Hide On X' controls are displayed from largest to smallest, while the method returns smallest to largest.
720	$active_devices = Plugin::$instance->breakpoints->get_active_devices_list( [ 'reverse' => true ] );
721	$active_breakpoints = Plugin::$instance->breakpoints->get_active_breakpoints();
722
723	foreach ( $active_devices as $breakpoint_key ) {
724	$label = 'desktop' === $breakpoint_key ? __( 'Desktop', 'elementor' ) : $active_breakpoints[ $breakpoint_key ]->get_label();
725
726	$this->add_control(
727	'hide_' . $breakpoint_key,
728	[
729	/* translators: %s: Device name. */
730	'label' => sprintf( __( 'Hide On %s', 'elementor' ), $label ),
731	'type' => Controls_Manager::SWITCHER,
732	'default' => '',
733	'prefix_class' => 'elementor-',
734	'label_on' => __( 'Hide', 'elementor' ),
735	'label_off' => __( 'Show', 'elementor' ),
736	'return_value' => 'hidden-' . $breakpoint_key,
737	]
738	);
739	}
740	}
741
742	/**
743	* Get default data.
744	*
745	* Retrieve the default element data. Used to reset the data on initialization.
746	*
747	* @since 1.0.0
748	* @access protected
749	*
750	* @return array Default data.
751	*/
752	protected function get_default_data() {
753	$data = parent::get_default_data();
754
755	return array_merge(
756	$data, [
757	'elements' => [],
758	'isInner' => false,
759	]
760	);
761	}
762
763	/**
764	* Print element content.
765	*
766	* Output the element final HTML on the frontend.
767	*
768	* @since 1.0.0
769	* @access protected
770	*/
771	protected function _print_content() {
772	Plugin::$instance->modules_manager->get_modules( 'dev-tools' )->deprecation->deprecated_function( __METHOD__, '3.1.0', __CLASS__ . '::print_content()' );
773
774	$this->print_content();
775	}
776
777	/**
778	* Print element content.
779	*
780	* Output the element final HTML on the frontend.
781	*
782	* @since 3.1.0
783	* @access protected
784	*/
785	protected function print_content() {
786	foreach ( $this->get_children() as $child ) {
787	$child->print_element();
788	}
789	}
790
791	/**
792	* Get initial config.
793	*
794	* Retrieve the current element initial configuration.
795	*
796	* Adds more configuration on top of the controls list and the tabs assigned
797	* to the control. This method also adds element name, type, icon and more.
798	*
799	* @since 2.9.0
800	* @access protected
801	*
802	* @return array The initial config.
803	*/
804	protected function get_initial_config() {
805	$config = [
806	'name' => $this->get_name(),
807	'elType' => $this->get_type(),
808	'title' => $this->get_title(),
809	'icon' => $this->get_icon(),
810	'reload_preview' => $this->is_reload_preview_required(),
811	];
812
813	if ( preg_match( '/^' . __NAMESPACE__ . '(Pro)?\\\\/', get_called_class() ) ) {
814	$config['help_url'] = $this->get_help_url();
815	} else {
816	$config['help_url'] = $this->get_custom_help_url();
817	}
818
819	if ( ! $this->is_editable() ) {
820	$config['editable'] = false;
821	}
822
823	return $config;
824	}
825
826	/**
827	* A Base method for sanitizing the settings before save.
828	* This method is meant to be overridden by the element.
829	*/
830	protected function on_save( array $settings ) {
831	return $settings;
832	}
833
834	/**
835	* Get child type.
836	*
837	* Retrieve the element child type based on element data.
838	*
839	* @since 2.0.0
840	* @access private
841	*
842	* @param array $element_data Element ID.
843	*
844	* @return Element_Base\|false Child type or false if type not found.
845	*/
846	private function get_child_type( $element_data ) {
847	$child_type = $this->_get_default_child_type( $element_data );
848
849	// If it's not a valid widget ( like a deactivated plugin )
850	if ( ! $child_type ) {
851	return false;
852	}
853
854	/**
855	* Element child type.
856	*
857	* Filters the child type of the element.
858	*
859	* @since 1.0.0
860	*
861	* @param Element_Base $child_type The child element.
862	* @param array $element_data The original element ID.
863	* @param Element_Base $this The original element.
864	*/
865	$child_type = apply_filters( 'elementor/element/get_child_type', $child_type, $element_data, $this );
866
867	return $child_type;
868	}
869
870	/**
871	* Initialize children.
872	*
873	* Initializing the element child elements.
874	*
875	* @since 2.0.0
876	* @access private
877	*/
878	private function init_children() {
879	$this->children = [];
880
881	$children_data = $this->get_data( 'elements' );
882
883	if ( ! $children_data ) {
884	return;
885	}
886
887	foreach ( $children_data as $child_data ) {
888	if ( ! $child_data ) {
889	continue;
890	}
891
892	$this->add_child( $child_data );
893	}
894	}
895
896	/**
897	* Element base constructor.
898	*
899	* Initializing the element base class using `$data` and `$args`.
900	*
901	* The `$data` parameter is required for a normal instance because of the
902	* way Elementor renders data when initializing elements.
903	*
904	* @since 1.0.0
905	* @access public
906	*
907	* @param array $data Optional. Element data. Default is an empty array.
908	* @param array\|null $args Optional. Element default arguments. Default is null.
909	**/
910	public function __construct( array $data = [], array $args = null ) {
911	if ( $data ) {
912	$this->is_type_instance = false;
913	} elseif ( $args ) {
914	$this->default_args = $args;
915	}
916
917	parent::__construct( $data );
918	}
919	}
920