elementor / core / breakpoints / manager.php

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

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