elementor / core / breakpoints / manager.php

manager.php in Elementor Website Builder – more than just a page builder 3.20.3, at core/breakpoints/manager.php

538 lines 15.4 KB

Raw Download Zip

1	<?php
2	namespace Elementor\Core\Breakpoints;
3
4	use Elementor\Core\Base\Module;
5	use Elementor\Core\Kits\Documents\Tabs\Settings_Layout;
6	use Elementor\Core\Responsive\Files\Frontend;
7	use Elementor\Modules\DevTools\Deprecation;
8	use Elementor\Plugin;
9
10	if ( ! defined( 'ABSPATH' ) ) {
11	exit; // Exit if accessed directly.
12	}
13
14	class Manager extends Module {
15
16	const BREAKPOINT_SETTING_PREFIX = 'viewport_';
17	const BREAKPOINT_KEY_MOBILE = 'mobile';
18	const BREAKPOINT_KEY_MOBILE_EXTRA = 'mobile_extra';
19	const BREAKPOINT_KEY_TABLET = 'tablet';
20	const BREAKPOINT_KEY_TABLET_EXTRA = 'tablet_extra';
21	const BREAKPOINT_KEY_LAPTOP = 'laptop';
22	const BREAKPOINT_KEY_DESKTOP = 'desktop';
23	const BREAKPOINT_KEY_WIDESCREEN = 'widescreen';
24
25	/**
26	* Breakpoints
27	*
28	* An array containing instances of the all of the system's available breakpoints.
29	*
30	* @since 3.2.0
31	* @access private
32	*
33	* @var Breakpoint[]
34	*/
35	private $breakpoints;
36
37	/**
38	* Active Breakpoints
39	*
40	* An array containing instances of the enabled breakpoints.
41	*
42	* @since 3.2.0
43	* @access private
44	*
45	* @var Breakpoint[]
46	*/
47	private $active_breakpoints;
48
49	/**
50	* Responsive Control Duplication Mode.
51	*
52	* Determines the current responsive control generation mode.
53	* Options are:
54	* -- 'on': Responsive controls are duplicated in `add_responsive_control()`.
55	* -- 'off': Responsive controls are NOT duplicated in `add_responsive_control()`.
56	* -- 'dynamic': Responsive controls are only duplicated if their config contains `'dynamic' => 'active' => true`.
57	*
58	* When generating Post CSS, the mode is set to 'on'. When generating Dynamic CSS, the mode is set to 'dynamic'.
59	*
60	* default value is 'off'.
61	*
62	* @since 3.4.0
63	* @access private
64	*
65	* @var string
66	*/
67	private $responsive_control_duplication_mode = 'off';
68
69	private $icons_map;
70
71	/**
72	* Has Custom Breakpoints
73	*
74	* A flag that holds a cached value that indicates if there are active custom-breakpoints.
75	*
76	* @since 3.5.0
77	* @access private
78	*
79	* @var boolean
80	*/
81	private $has_custom_breakpoints;
82
83	public function get_name() {
84	return 'breakpoints';
85	}
86
87	/**
88	* Get Breakpoints
89	*
90	* Retrieve the array containing instances of all breakpoints existing in the system, or a single breakpoint if a
91	* name is passed.
92	*
93	* @since 3.2.0
94	*
95	* @param $breakpoint_name
96	* @return Breakpoint[]\|Breakpoint
97	*/
98	public function get_breakpoints( $breakpoint_name = null ) {
99	if ( ! $this->breakpoints ) {
100	$this->init_breakpoints();
101	}
102	return self::get_items( $this->breakpoints, $breakpoint_name );
103	}
104
105	/**
106	* Get Active Breakpoints
107	*
108	* Retrieve the array of --enabled-- breakpoints, or a single breakpoint if a name is passed.
109	*
110	* @since 3.2.0
111	*
112	* @param string\|null $breakpoint_name
113	* @return Breakpoint[]\|Breakpoint
114	*/
115	public function get_active_breakpoints( $breakpoint_name = null ) {
116	if ( ! $this->active_breakpoints ) {
117	$this->init_active_breakpoints();
118	}
119
120	return self::get_items( $this->active_breakpoints, $breakpoint_name );
121	}
122
123	/**
124	* Get Active Devices List
125	*
126	* Retrieve an array containing the keys of all active devices, including 'desktop'.
127	*
128	* @since 3.2.0
129	*
130	* @param array $args
131	* @return array
132	*/
133	public function get_active_devices_list( $args = [] ) {
134	$default_args = [
135	'add_desktop' => true,
136	'reverse' => false,
137	'desktop_first' => false,
138	];
139
140	$args = array_merge( $default_args, $args );
141
142	$active_devices = array_keys( Plugin::$instance->breakpoints->get_active_breakpoints() );
143
144	if ( $args['add_desktop'] ) {
145	// Insert the 'desktop' device in the correct position.
146	if ( ! $args['desktop_first'] && in_array( 'widescreen', $active_devices, true ) ) {
147	$widescreen_index = array_search( 'widescreen', $active_devices, true );
148
149	array_splice( $active_devices, $widescreen_index, 0, [ 'desktop' ] );
150	} else {
151	$active_devices[] = 'desktop';
152	}
153	}
154
155	if ( $args['reverse'] ) {
156	$active_devices = array_reverse( $active_devices );
157	}
158
159	return $active_devices;
160	}
161
162	/** Has Custom Breakpoints
163	*
164	* Checks whether there are currently custom breakpoints saved in the database.
165	* Returns true if there are breakpoint values saved in the active kit.
166	* If the user has activated any additional custom breakpoints (mobile extra, tablet extra, laptop, widescreen) -
167	* that is considered as having custom breakpoints.
168	*
169	* @since 3.2.0
170	*
171	* @return boolean
172	*/
173	public function has_custom_breakpoints() {
174	if ( isset( $this->has_custom_breakpoints ) ) {
175	return $this->has_custom_breakpoints;
176	}
177
178	$breakpoints = $this->get_active_breakpoints();
179
180	$additional_breakpoints = [
181	self::BREAKPOINT_KEY_MOBILE_EXTRA,
182	self::BREAKPOINT_KEY_TABLET_EXTRA,
183	self::BREAKPOINT_KEY_LAPTOP,
184	self::BREAKPOINT_KEY_WIDESCREEN,
185	];
186
187	foreach ( $breakpoints as $breakpoint_name => $breakpoint ) {
188	if ( in_array( $breakpoint_name, $additional_breakpoints, true ) ) {
189	$this->has_custom_breakpoints = true;
190
191	return true;
192	}
193
194	/** @var Breakpoint $breakpoint */
195	if ( $breakpoint->is_custom() ) {
196	$this->has_custom_breakpoints = true;
197
198	return true;
199	}
200	}
201
202	$this->has_custom_breakpoints = false;
203
204	return false;
205	}
206
207	/**
208	* Get Device Min Breakpoint
209	*
210	* For a given device, return the minimum possible breakpoint. Except for the cases of mobile and widescreen
211	* devices, A device's min breakpoint is determined by the previous device's max breakpoint + 1px.
212	*
213	* @since 3.2.0
214	*
215	* @param string $device_name
216	* @return int the min breakpoint of the passed device
217	*/
218	public function get_device_min_breakpoint( $device_name ) {
219	if ( 'desktop' === $device_name ) {
220	return $this->get_desktop_min_point();
221	}
222
223	$active_breakpoints = $this->get_active_breakpoints();
224	$current_device_breakpoint = $active_breakpoints[ $device_name ];
225
226	// Since this method is called multiple times, usage of class variables is to memory and processing time.
227	// Get only the keys for active breakpoints.
228	$breakpoint_keys = array_keys( $active_breakpoints );
229
230	if ( $breakpoint_keys[0] === $device_name ) {
231	// For the lowest breakpoint, the min point is always 320.
232	$min_breakpoint = 320;
233	} elseif ( 'min' === $current_device_breakpoint->get_direction() ) {
234	// 'min-width' breakpoints only have a minimum point. The breakpoint value itself the device min point.
235	$min_breakpoint = $current_device_breakpoint->get_value();
236	} else {
237	// This block handles all other devices.
238	$device_name_index = array_search( $device_name, $breakpoint_keys, true );
239
240	$previous_index = $device_name_index - 1;
241	$previous_breakpoint_key = $breakpoint_keys[ $previous_index ];
242	/** @var Breakpoint $previous_breakpoint */
243	$previous_breakpoint = $active_breakpoints[ $previous_breakpoint_key ];
244
245	$min_breakpoint = $previous_breakpoint->get_value() + 1;
246	}
247
248	return $min_breakpoint;
249	}
250
251	/**
252	* Get Desktop Min Breakpoint
253	*
254	* Returns the minimum possible breakpoint for the default (desktop) device.
255	*
256	* @since 3.2.0
257	*
258	* @return int the min breakpoint of the passed device
259	*/
260	public function get_desktop_min_point() {
261	$active_breakpoints = $this->get_active_breakpoints();
262	$desktop_previous_device = $this->get_desktop_previous_device_key();
263
264	return $active_breakpoints[ $desktop_previous_device ]->get_value() + 1;
265	}
266
267	public function refresh() {
268	unset( $this->has_custom_breakpoints );
269
270	$this->init_breakpoints();
271	$this->init_active_breakpoints();
272	}
273
274	/**
275	* Get Responsive Icons Classes Map
276	*
277	* If a $device parameter is passed, this method retrieves the device's icon class list (the ones attached to the `<i>`
278	* element). If no parameter is passed, it returns an array of devices containing each device's icon class list.
279	*
280	* This method was created because 'mobile_extra' and 'tablet_extra' breakpoint icons need to be tilted by 90
281	* degrees, and this tilt is achieved in CSS via the class `eicon-tilted`.
282	*
283	* @since 3.4.0
284	*
285	* @return array\|string
286	*/
287	public function get_responsive_icons_classes_map( $device = null ) {
288	if ( ! $this->icons_map ) {
289	$this->icons_map = [
290	'mobile' => 'eicon-device-mobile',
291	'mobile_extra' => 'eicon-device-mobile eicon-tilted',
292	'tablet' => 'eicon-device-tablet',
293	'tablet_extra' => 'eicon-device-tablet eicon-tilted',
294	'laptop' => 'eicon-device-laptop',
295	'desktop' => 'eicon-device-desktop',
296	'widescreen' => 'eicon-device-wide',
297	];
298	}
299
300	return self::get_items( $this->icons_map, $device );
301	}
302
303	/**
304	* Get Default Config
305	*
306	* Retrieve the default breakpoints config array. The 'selector' property is used for CSS generation (the
307	* Stylesheet::add_device() method).
308	*
309	* @return array
310	*/
311	public static function get_default_config() {
312	return [
313	self::BREAKPOINT_KEY_MOBILE => [
314	'label' => esc_html__( 'Mobile Portrait', 'elementor' ),
315	'default_value' => 767,
316	'direction' => 'max',
317	],
318	self::BREAKPOINT_KEY_MOBILE_EXTRA => [
319	'label' => esc_html__( 'Mobile Landscape', 'elementor' ),
320	'default_value' => 880,
321	'direction' => 'max',
322	],
323	self::BREAKPOINT_KEY_TABLET => [
324	'label' => esc_html__( 'Tablet Portrait', 'elementor' ),
325	'default_value' => 1024,
326	'direction' => 'max',
327	],
328	self::BREAKPOINT_KEY_TABLET_EXTRA => [
329	'label' => esc_html__( 'Tablet Landscape', 'elementor' ),
330	'default_value' => 1200,
331	'direction' => 'max',
332	],
333	self::BREAKPOINT_KEY_LAPTOP => [
334	'label' => esc_html__( 'Laptop', 'elementor' ),
335	'default_value' => 1366,
336	'direction' => 'max',
337	],
338	self::BREAKPOINT_KEY_WIDESCREEN => [
339	'label' => esc_html__( 'Widescreen', 'elementor' ),
340	'default_value' => 2400,
341	'direction' => 'min',
342	],
343	];
344	}
345
346	/**
347	* Get Breakpoints Config
348	*
349	* Iterates over an array of all of the system's breakpoints (both active and inactive), queries each breakpoint's
350	* class instance, and generates an array containing data on each breakpoint: its label, current value, direction
351	* ('min'/'max') and whether it is enabled or not.
352	*
353	* @return array
354	*/
355	public function get_breakpoints_config() {
356	$breakpoints = $this->get_breakpoints();
357
358	$config = [];
359
360	foreach ( $breakpoints as $breakpoint_name => $breakpoint ) {
361	$config[ $breakpoint_name ] = [
362	'label' => $breakpoint->get_label(),
363	'value' => $breakpoint->get_value(),
364	'default_value' => $breakpoint->get_default_value(),
365	'direction' => $breakpoint->get_direction(),
366	'is_enabled' => $breakpoint->is_enabled(),
367	];
368	}
369
370	return $config;
371	}
372
373	/**
374	* Get Responsive Control Duplication Mode
375	*
376	* Retrieve the value of the $responsive_control_duplication_mode private class variable.
377	* See the variable's PHPDoc for details.
378	*
379	* @since 3.4.0
380	* @access public
381	*/
382	public function get_responsive_control_duplication_mode() {
383	return $this->responsive_control_duplication_mode;
384	}
385
386	/**
387	* Set Responsive Control Duplication Mode
388	*
389	* Sets the value of the $responsive_control_duplication_mode private class variable.
390	* See the variable's PHPDoc for details.
391	*
392	* @since 3.4.0
393	*
394	* @access public
395	* @param string $mode
396	*/
397	public function set_responsive_control_duplication_mode( $mode ) {
398	$this->responsive_control_duplication_mode = $mode;
399	}
400
401	/**
402	* Get Stylesheet Templates Path
403	*
404	* @since 3.2.0
405	* @access public
406	* @static
407	*/
408	public static function get_stylesheet_templates_path() {
409	return ELEMENTOR_ASSETS_PATH . 'css/templates/';
410	}
411
412	/**
413	* Compile Stylesheet Templates
414	*
415	* @since 3.2.0
416	* @access public
417	* @static
418	*/
419	public static function compile_stylesheet_templates() {
420	foreach ( self::get_stylesheet_templates() as $file_name => $template_path ) {
421	$file = new Frontend( $file_name, $template_path );
422
423	$file->update();
424	}
425	}
426
427	/**
428	* Init Breakpoints
429	*
430	* Creates the breakpoints array, containing instances of each breakpoint. Returns an array of ALL breakpoints,
431	* both enabled and disabled.
432	*
433	* @since 3.2.0
434	*/
435	private function init_breakpoints() {
436	$breakpoints = [];
437
438	$setting_prefix = self::BREAKPOINT_SETTING_PREFIX;
439
440	$active_breakpoint_keys = [
441	$setting_prefix . self::BREAKPOINT_KEY_MOBILE,
442	$setting_prefix . self::BREAKPOINT_KEY_TABLET,
443	];
444
445	if ( Plugin::$instance->experiments->is_feature_active( 'additional_custom_breakpoints' ) ) {
446	$kit_active_id = Plugin::$instance->kits_manager->get_active_id();
447	// Get the breakpoint settings saved in the kit directly from the DB to avoid initializing the kit too early.
448	$raw_kit_settings = get_post_meta( $kit_active_id, '_elementor_page_settings', true );
449
450	// If there is an existing kit with an active breakpoints value saved, use it.
451	if ( isset( $raw_kit_settings[ Settings_Layout::ACTIVE_BREAKPOINTS_CONTROL_ID ] ) ) {
452	$active_breakpoint_keys = $raw_kit_settings[ Settings_Layout::ACTIVE_BREAKPOINTS_CONTROL_ID ];
453	}
454	}
455
456	$default_config = self::get_default_config();
457
458	foreach ( $default_config as $breakpoint_name => $breakpoint_config ) {
459	$args = [ 'name' => $breakpoint_name ] + $breakpoint_config;
460
461	// Make sure the two default breakpoints (mobile, tablet) are always enabled.
462	if ( self::BREAKPOINT_KEY_MOBILE === $breakpoint_name \|\| self::BREAKPOINT_KEY_TABLET === $breakpoint_name ) {
463	// Make sure the default Mobile and Tablet breakpoints are always enabled.
464	$args['is_enabled'] = true;
465	} else {
466	// If the breakpoint is in the active breakpoints array, make sure it's instantiated as enabled.
467	$args['is_enabled'] = in_array( $setting_prefix . $breakpoint_name, $active_breakpoint_keys, true );
468	}
469
470	$breakpoints[ $breakpoint_name ] = new Breakpoint( $args );
471	}
472
473	$this->breakpoints = $breakpoints;
474	}
475
476	/**
477	* Init Active Breakpoints
478	*
479	* Create/Refresh the array of --enabled-- breakpoints.
480	*
481	* @since 3.2.0
482	*/
483	private function init_active_breakpoints() {
484	$this->active_breakpoints = array_filter( $this->get_breakpoints(), function( $breakpoint ) {
485	/** @var Breakpoint $breakpoint */
486	return $breakpoint->is_enabled();
487	} );
488	}
489
490	private function get_desktop_previous_device_key() {
491	$config_array_keys = array_keys( $this->get_active_breakpoints() );
492	$num_of_devices = count( $config_array_keys );
493
494	// If the widescreen breakpoint is active, the device that's previous to desktop is the last one before
495	// widescreen.
496	if ( self::BREAKPOINT_KEY_WIDESCREEN === $config_array_keys[ $num_of_devices - 1 ] ) {
497	$desktop_previous_device = $config_array_keys[ $num_of_devices - 2 ];
498	} else {
499	// If the widescreen breakpoint isn't active, we just take the last device returned by the config.
500	$desktop_previous_device = $config_array_keys[ $num_of_devices - 1 ];
501	}
502
503	return $desktop_previous_device;
504	}
505
506	/**
507	* Get Stylesheet Templates
508	*
509	* @since 3.2.0
510	* @access private
511	* @static
512	*/
513	private static function get_stylesheet_templates() {
514	$templates_paths = glob( self::get_stylesheet_templates_path() . '*.css' );
515
516	$templates = [];
517
518	foreach ( $templates_paths as $template_path ) {
519	$file_name = 'custom-' . basename( $template_path );
520
521	$templates[ $file_name ] = $template_path;
522	}
523
524	$deprecated_hook = 'elementor/core/responsive/get_stylesheet_templates';
525	$replacement_hook = 'elementor/core/breakpoints/get_stylesheet_template';
526
527	/**
528	* @type Deprecation $deprecation_module
529	*/
530	$deprecation_module = Plugin::$instance->modules_manager->get_modules( 'dev-tools' )->deprecation;
531
532	// TODO: REMOVE THIS DEPRECATED HOOK IN ELEMENTOR v3.10.0/v4.0.0
533	$templates = $deprecation_module->apply_deprecated_filter( $deprecated_hook, [ $templates ], '3.2.0', $replacement_hook );
534
535	return apply_filters( $replacement_hook, $templates );
536	}
537	}
538