master-addons / inc / traits / widget-assets-trait.php

widget-assets-trait.php in Master Addons for Elementor – Elementor Addons, Widgets, Mega Menu Builder, Popup Builder, Widget Builder & Template Kits 3.1.9, at inc/traits/widget-assets-trait.php

232 lines 7.6 KB

Raw Download Zip

1	<?php
2
3	/**
4	* Widget Assets Trait
5	*
6	* Provides automatic asset dependency resolution and help URL for Elementor widgets.
7	* Uses Config as the single source of truth for widget configuration.
8	*
9	* Looks up config by class name (not widget name) to handle mismatches
10	* between widget get_name() and config keys.
11	*
12	* Asset handle detection:
13	* - Assets starting with 'ma-' or 'jltma-' → widget assets → 'master-addons-*' handle
14	* - Vendor assets (from 'vendors' array) → vendor handles → 'jltma-*' handle
15	* - Other assets (gridder, font-awesome-5-all, etc.) → use handle directly
16	*
17	* Fallback behavior:
18	* - If 'assets' not defined in config, derives CSS from config key (e.g., 'ma-tooltip' → 'master-addons-tooltip')
19	*
20	* Example config:
21	* 'ma-image-filter-gallery' => [
22	* 'class' => 'MasterAddons\Addons\Filterable_Image_Gallery',
23	* 'demo_url' => 'https://master-addons.com/demos/image-gallery/',
24	* 'assets' => [
25	* 'css' => true,
26	* 'js' => true,
27	* 'vendors' => ['fancybox', 'isotope', 'tilt', 'tippy'],
28	* ],
29	* ]
30	*
31	* Results in:
32	* get_style_depends() → ['jltma-fancybox', 'jltma-tippy', 'master-addons-image-filter-gallery']
33	* get_script_depends() → ['jltma-fancybox', 'jltma-isotope', 'jltma-tilt', 'jltma-tippy', 'master-addons-image-filter-gallery']
34	* get_help_url() → 'https://master-addons.com/demos/image-gallery/'
35	*
36	* @package MasterAddons\Inc\Traits
37	* @since 2.1.0
38	*/
39
40	namespace MasterAddons\Inc\Traits;
41
42	use MasterAddons\Inc\Admin\Config;
43	use MasterAddons\Inc\Classes\Assets_Manager;
44
45	trait Widget_Assets_Trait
46	{
47	/**
48	* Cached config lookup result
49	*
50	* @var array\|null
51	*/
52	private $_widget_config_cache = null;
53
54	/**
55	* Get the widget's config from Config (by class name)
56	*
57	* @return array\|null Array with 'key' and 'config', or null
58	*/
59	protected function get_widget_config()
60	{
61	if ($this->_widget_config_cache === null) {
62	$this->_widget_config_cache = Config::get_addon_by_class(get_class($this)) ?: false;
63	}
64
65	return $this->_widget_config_cache ?: null;
66	}
67
68	/**
69	* Get the config key for this widget
70	*
71	* @return string\|null Config key (e.g., 'ma-counter-up')
72	*/
73	protected function get_config_key()
74	{
75	$config = $this->get_widget_config();
76	return $config ? $config['key'] : null;
77	}
78
79	/**
80	* Convert asset name to WordPress registered handle
81	*
82	* Auto-detects asset type:
83	* - 'ma-' or 'jltma-' → widget asset → 'master-addons-*' handle
84	* - Others (gridder, font-awesome, etc.) → vendor/external → use as-is
85	*
86	* @param string $asset_name Asset name from config
87	* @return string WordPress registered handle
88	*/
89	protected function asset_to_handle($asset_name)
90	{
91	// Check if it's a widget asset (starts with ma- or jltma-)
92	if (preg_match('/^(ma-\|jltma-)/', $asset_name)) {
93	// Strip prefix, then add master-addons- prefix
94	$handle_name = preg_replace('/^(ma-\|jltma-)/', '', $asset_name);
95	return 'master-addons-' . $handle_name;
96	}
97
98	// Vendor/external asset - use handle directly as registered
99	return $asset_name;
100	}
101
102	/**
103	* Get style dependencies from unified config
104	*
105	* Automatically resolves CSS dependencies based on the widget's class
106	* and the asset definitions in Config. Also includes vendor CSS.
107	*
108	* Fallback: If no assets defined, derives from config key.
109	*
110	* @return array Array of registered style handles to enqueue
111	*/
112	public function get_style_depends()
113	{
114	$config = $this->get_widget_config();
115	$styles = [];
116
117	if ($config) {
118	// Add vendor CSS dependencies first (they should load before widget CSS)
119	if (!empty($config['config']['assets']['vendors'])) {
120	foreach ((array) $config['config']['assets']['vendors'] as $vendor) {
121	$vendor_config = Assets_Manager::get($vendor);
122	if ($vendor_config && !empty($vendor_config['files']['css'])) {
123	$styles[] = 'jltma-' . $vendor;
124	}
125	}
126	}
127
128	if (!empty($config['config']['assets']['css'])) {
129	// Handle 'css' => true format (auto-map to widget key)
130	if ($config['config']['assets']['css'] === true) {
131	$styles[] = $this->asset_to_handle($config['key']);
132	} else {
133	// Use explicitly defined CSS assets
134	foreach ((array) $config['config']['assets']['css'] as $css) {
135	$styles[] = $this->asset_to_handle($css);
136	}
137	}
138	} elseif (empty($config['config']['assets'])) {
139	// Fallback: derive from config key if no assets defined at all
140	$styles[] = $this->asset_to_handle($config['key']);
141	}
142	}
143
144	return $styles;
145	}
146
147	/**
148	* Get script dependencies from unified config
149	*
150	* Automatically resolves JS dependencies based on the widget's class
151	* and the asset definitions in Config. Also includes vendor JS.
152	*
153	* @return array Array of registered script handles to enqueue
154	*/
155	public function get_script_depends()
156	{
157	$config = $this->get_widget_config();
158	$scripts = [];
159
160	if ($config) {
161	// Add vendor JS dependencies first (they should load before widget JS)
162	if (!empty($config['config']['assets']['vendors'])) {
163	foreach ((array) $config['config']['assets']['vendors'] as $vendor) {
164	$vendor_config = Assets_Manager::get($vendor);
165	if ($vendor_config && !empty($vendor_config['files']['js'])) {
166	$scripts[] = 'jltma-' . $vendor;
167	}
168	}
169	}
170
171	if (!empty($config['config']['assets']['js'])) {
172	// Handle 'js' => true format (auto-map to widget key)
173	if ($config['config']['assets']['js'] === true) {
174	$scripts[] = $this->asset_to_handle($config['key']);
175	} else {
176	foreach ((array) $config['config']['assets']['js'] as $js) {
177	$scripts[] = $this->asset_to_handle($js);
178	}
179	}
180	}
181	}
182
183	return $scripts;
184	}
185
186	/**
187	* Get help URL from config's demo_url
188	*
189	* Provides the documentation/demo URL for the widget.
190	*
191	* @return string Help URL or empty string if not defined
192	*/
193	public function get_help_url()
194	{
195	$config = $this->get_widget_config();
196	return $config ? ($config['config']['demo_url'] ?? '') : '';
197	}
198
199	/**
200	* Check if this widget has any registered styles
201	*
202	* @return bool
203	*/
204	public function has_style_depends()
205	{
206	return !empty($this->get_style_depends());
207	}
208
209	/**
210	* Check if this widget has any registered scripts
211	*
212	* @return bool
213	*/
214	public function has_script_depends()
215	{
216	return !empty($this->get_script_depends());
217	}
218
219	/**
220	* Get the widget's assets configuration from Config
221	*
222	* Useful for debugging or advanced customization.
223	*
224	* @return array Assets configuration array
225	*/
226	public function get_widget_assets_config()
227	{
228	$config = $this->get_widget_config();
229	return $config ? ($config['config']['assets'] ?? []) : [];
230	}
231	}
232