elementor / includes / base / element-base.php

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

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