elementor / core / breakpoints / manager.php

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

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