elementor / includes / base / element-base.php

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

892 lines 21.2 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, $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	/**
547	* Get unique selector.
548	*
549	* Retrieve the unique selector of the element. Used to set a unique HTML
550	* class for each HTML element. This way Elementor can set custom styles for
551	* each element.
552	*
553	* @since 1.0.0
554	* @access public
555	*
556	* @return string Unique selector.
557	*/
558	public function get_unique_selector() {
559	return '.elementor-element-' . $this->get_id();
560	}
561
562	/**
563	* Is type instance.
564	*
565	* Used to determine whether the element is an instance of that type or not.
566	*
567	* @since 1.0.0
568	* @access public
569	*
570	* @return bool Whether the element is an instance of that type.
571	*/
572	public function is_type_instance() {
573	return $this->is_type_instance;
574	}
575
576	/**
577	* On Import Replace Dynamic Content.
578	*
579	* @since 3.6.0
580	* @access public
581	*
582	* @return array Element data.
583	*/
584	public static function on_import_replace_dynamic_content( $config, $map_old_new_post_ids ) {
585	$tags_manager = Plugin::$instance->dynamic_tags;
586
587	if ( isset( $config['settings'][ $tags_manager::DYNAMIC_SETTING_KEY ] ) ) {
588	foreach ( $config['settings'][ $tags_manager::DYNAMIC_SETTING_KEY ] as $dynamic_name => $dynamic_value ) {
589	$tag_config = $tags_manager->tag_text_to_tag_data( $dynamic_value );
590	$tag_instance = $tags_manager->create_tag( $tag_config['id'], $tag_config['name'], $tag_config['settings'] );
591
592	if ( $tag_instance ) {
593	$tag_config = $tag_instance->on_import_replace_dynamic_content( $tag_config, $map_old_new_post_ids );
594	$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'] );
595	}
596	}
597	}
598
599	return $config;
600	}
601
602	/**
603	* Add render attributes.
604	*
605	* Used to add attributes to the current element wrapper HTML tag.
606	*
607	* @since 1.3.0
608	* @access protected
609	* @deprecated 3.1.0
610	*/
611	protected function _add_render_attributes() {
612	Plugin::$instance->modules_manager->get_modules( 'dev-tools' )->deprecation->deprecated_function( __METHOD__, '3.1.0', __CLASS__ . '::add_render_attributes()' );
613
614	return $this->add_render_attributes();
615	}
616
617	/**
618	* Add render attributes.
619	*
620	* Used to add attributes to the current element wrapper HTML tag.
621	*
622	* @since 3.1.0
623	* @access protected
624	*/
625	protected function add_render_attributes() {
626	$id = $this->get_id();
627
628	$settings = $this->get_settings_for_display();
629	$frontend_settings = $this->get_frontend_settings();
630	$controls = $this->get_controls();
631
632	$this->add_render_attribute( '_wrapper', [
633	'class' => [
634	'elementor-element',
635	'elementor-element-' . $id,
636	],
637	'data-id' => $id,
638	'data-element_type' => $this->get_type(),
639	] );
640
641	$class_settings = [];
642
643	foreach ( $settings as $setting_key => $setting ) {
644	if ( isset( $controls[ $setting_key ]['prefix_class'] ) ) {
645	$class_settings[ $setting_key ] = $setting;
646	}
647	}
648
649	foreach ( $class_settings as $setting_key => $setting ) {
650	if ( empty( $setting ) && '0' !== $setting ) {
651	continue;
652	}
653
654	$this->add_render_attribute( '_wrapper', 'class', $controls[ $setting_key ]['prefix_class'] . $setting );
655	}
656
657	$_animation = ! empty( $settings['_animation'] );
658	$animation = ! empty( $settings['animation'] );
659	$has_animation = $_animation && 'none' !== $settings['_animation'] \|\| $animation && 'none' !== $settings['animation'];
660
661	if ( $has_animation ) {
662	$is_static_render_mode = Plugin::$instance->frontend->is_static_render_mode();
663
664	if ( ! $is_static_render_mode ) {
665	// Hide the element until the animation begins
666	$this->add_render_attribute( '_wrapper', 'class', 'elementor-invisible' );
667	}
668	}
669
670	if ( ! empty( $settings['_element_id'] ) ) {
671	$this->add_render_attribute( '_wrapper', 'id', trim( $settings['_element_id'] ) );
672	}
673
674	if ( $frontend_settings ) {
675	$this->add_render_attribute( '_wrapper', 'data-settings', wp_json_encode( $frontend_settings ) );
676	}
677
678	/**
679	* After element attribute rendered.
680	*
681	* Fires after the attributes of the element HTML tag are rendered.
682	*
683	* @since 2.3.0
684	*
685	* @param Element_Base $this The element.
686	*/
687	do_action( 'elementor/element/after_add_attributes', $this );
688	}
689
690	/**
691	* Add Hidden Device Controls
692	*
693	* Adds controls for hiding elements within certain devices' viewport widths. Adds a control for each active device.
694	*
695	* @since 3.4.0
696	* @access protected
697	*/
698	protected function add_hidden_device_controls() {
699	// The 'Hide On X' controls are displayed from largest to smallest, while the method returns smallest to largest.
700	$active_devices = Plugin::$instance->breakpoints->get_active_devices_list( [ 'reverse' => true ] );
701	$active_breakpoints = Plugin::$instance->breakpoints->get_active_breakpoints();
702
703	foreach ( $active_devices as $breakpoint_key ) {
704	$label = 'desktop' === $breakpoint_key ? __( 'Desktop', 'elementor' ) : $active_breakpoints[ $breakpoint_key ]->get_label();
705
706	$this->add_control(
707	'hide_' . $breakpoint_key,
708	[
709	/* translators: %s: Device name. */
710	'label' => sprintf( __( 'Hide On %s', 'elementor' ), $label ),
711	'type' => Controls_Manager::SWITCHER,
712	'default' => '',
713	'prefix_class' => 'elementor-',
714	'label_on' => 'Hide',
715	'label_off' => 'Show',
716	'return_value' => 'hidden-' . $breakpoint_key,
717	]
718	);
719	}
720	}
721
722	/**
723	* Get default data.
724	*
725	* Retrieve the default element data. Used to reset the data on initialization.
726	*
727	* @since 1.0.0
728	* @access protected
729	*
730	* @return array Default data.
731	*/
732	protected function get_default_data() {
733	$data = parent::get_default_data();
734
735	return array_merge(
736	$data, [
737	'elements' => [],
738	'isInner' => false,
739	]
740	);
741	}
742
743	/**
744	* Print element content.
745	*
746	* Output the element final HTML on the frontend.
747	*
748	* @since 1.0.0
749	* @access protected
750	*/
751	protected function _print_content() {
752	Plugin::$instance->modules_manager->get_modules( 'dev-tools' )->deprecation->deprecated_function( __METHOD__, '3.1.0', __CLASS__ . '::print_content()' );
753
754	$this->print_content();
755	}
756
757	/**
758	* Print element content.
759	*
760	* Output the element final HTML on the frontend.
761	*
762	* @since 3.1.0
763	* @access protected
764	*/
765	protected function print_content() {
766	foreach ( $this->get_children() as $child ) {
767	$child->print_element();
768	}
769	}
770
771	/**
772	* Get initial config.
773	*
774	* Retrieve the current element initial configuration.
775	*
776	* Adds more configuration on top of the controls list and the tabs assigned
777	* to the control. This method also adds element name, type, icon and more.
778	*
779	* @since 2.9.0
780	* @access protected
781	*
782	* @return array The initial config.
783	*/
784	protected function get_initial_config() {
785	$config = [
786	'name' => $this->get_name(),
787	'elType' => $this->get_type(),
788	'title' => $this->get_title(),
789	'icon' => $this->get_icon(),
790	'reload_preview' => $this->is_reload_preview_required(),
791	];
792
793	if ( preg_match( '/^' . __NAMESPACE__ . '(Pro)?\\\\/', get_called_class() ) ) {
794	$config['help_url'] = $this->get_help_url();
795	} else {
796	$config['help_url'] = $this->get_custom_help_url();
797	}
798
799	if ( ! $this->is_editable() ) {
800	$config['editable'] = false;
801	}
802
803	return $config;
804	}
805
806	/**
807	* Get child type.
808	*
809	* Retrieve the element child type based on element data.
810	*
811	* @since 2.0.0
812	* @access private
813	*
814	* @param array $element_data Element ID.
815	*
816	* @return Element_Base\|false Child type or false if type not found.
817	*/
818	private function get_child_type( $element_data ) {
819	$child_type = $this->_get_default_child_type( $element_data );
820
821	// If it's not a valid widget ( like a deactivated plugin )
822	if ( ! $child_type ) {
823	return false;
824	}
825
826	/**
827	* Element child type.
828	*
829	* Filters the child type of the element.
830	*
831	* @since 1.0.0
832	*
833	* @param Element_Base $child_type The child element.
834	* @param array $element_data The original element ID.
835	* @param Element_Base $this The original element.
836	*/
837	$child_type = apply_filters( 'elementor/element/get_child_type', $child_type, $element_data, $this );
838
839	return $child_type;
840	}
841
842	/**
843	* Initialize children.
844	*
845	* Initializing the element child elements.
846	*
847	* @since 2.0.0
848	* @access private
849	*/
850	private function init_children() {
851	$this->children = [];
852
853	$children_data = $this->get_data( 'elements' );
854
855	if ( ! $children_data ) {
856	return;
857	}
858
859	foreach ( $children_data as $child_data ) {
860	if ( ! $child_data ) {
861	continue;
862	}
863
864	$this->add_child( $child_data );
865	}
866	}
867
868	/**
869	* Element base constructor.
870	*
871	* Initializing the element base class using `$data` and `$args`.
872	*
873	* The `$data` parameter is required for a normal instance because of the
874	* way Elementor renders data when initializing elements.
875	*
876	* @since 1.0.0
877	* @access public
878	*
879	* @param array $data Optional. Element data. Default is an empty array.
880	* @param array\|null $args Optional. Element default arguments. Default is null.
881	**/
882	public function __construct( array $data = [], array $args = null ) {
883	if ( $data ) {
884	$this->is_type_instance = false;
885	} elseif ( $args ) {
886	$this->default_args = $args;
887	}
888
889	parent::__construct( $data );
890	}
891	}
892