vikbooking / admin / helpers / admin_widget.php

admin_widget.php in VikBooking Hotel Booking Engine & PMS trunk, at admin/helpers/admin_widget.php

676 lines 16.0 KB

Raw Download Zip

1	<?php
2	/**
3	* @package VikBooking
4	* @subpackage com_vikbooking
5	* @author Alessio Gaggii - e4j - Extensionsforjoomla.com
6	* @copyright Copyright (C) 2018 e4j - Extensionsforjoomla.com. All rights reserved.
7	* @license GNU General Public License version 2 or later; see LICENSE
8	* @link https://vikwp.com
9	*/
10
11	defined('ABSPATH') or die('No script kiddies please!');
12
13	/**
14	* Admin Widget parent Class of all sub-classes.
15	*
16	* @since 1.14 (J) - 1.4.0 (WP)
17	*/
18	abstract class VikBookingAdminWidget
19	{
20	/**
21	* The name of the widget.
22	*
23	* @var string
24	*/
25	protected $widgetName = null;
26
27	/**
28	* The description of the widget.
29	*
30	* @var string
31	*/
32	protected $widgetDescr = '';
33
34	/**
35	* The icon of the widget in HTML.
36	*
37	* @var string
38	*
39	* @since 1.15.0 (J) - 1.5.0 (WP)
40	*/
41	protected $widgetIcon = '';
42
43	/**
44	* The style name of the widget.
45	*
46	* @var string
47	*
48	* @since 1.15.0 (J) - 1.5.0 (WP)
49	*/
50	protected $widgetStyleName = 'regular';
51
52	/**
53	* The widget settings.
54	*
55	* @var mixed
56	*/
57	protected $widgetSettings = null;
58
59	/**
60	* The VBO application object.
61	*
62	* @var object
63	*/
64	protected $vbo_app = null;
65
66	/**
67	* The date format.
68	*
69	* @var string
70	*/
71	protected $df = '';
72
73	/**
74	* The date separator.
75	*
76	* @var string
77	*/
78	protected $datesep = '';
79
80	/**
81	* Whether the multitask panel
82	* is invoking the widget.
83	*
84	* @var bool
85	*/
86	protected $is_multitask = false;
87
88	/**
89	* The widget identifier.
90	*
91	* @var string
92	*/
93	protected $widgetId = null;
94
95	/**
96	* The widget multitask options registry.
97	*
98	* @var VBOMultitaskOptions
99	*
100	* @since 1.16.5 (J) - 1.6.5 (WP)
101	*/
102	protected $options;
103
104	/**
105	* Class constructors should define some vars for the widget in use.
106	*/
107	public function __construct()
108	{
109	$this->vbo_app = VikBooking::getVboApplication();
110	$this->datesep = VikBooking::getDateSeparator(true);
111
112	$nowdf = VikBooking::getDateFormat(true);
113	if ($nowdf == "%d/%m/%Y") {
114	$this->df = 'd/m/Y';
115	} elseif ($nowdf == "%m/%d/%Y") {
116	$this->df = 'm/d/Y';
117	} else {
118	$this->df = 'Y/m/d';
119	}
120
121	$this->options = VBOMultitaskOptions::getInstance();
122	}
123
124	/**
125	* Tells if the admin-widget can be installed on the current environment.
126	*
127	* @return bool
128	*
129	* @since 1.16.10 (J) - 1.6.10 (WP)
130	*/
131	public function preflight()
132	{
133	/**
134	* Trigger event to let external plugins to choose whether this widget should be supported or not.
135	*
136	* @param string $widgetId The widget identifier.
137	*
138	* @return bool False to drop support to this widget.
139	*
140	* @since 1.18 (J) - 1.8 (WP)
141	*/
142	$results = VBOFactory::getPlatform()->getDispatcher()->filter('onPreflightAdminWidget', [$this->widgetId]);
143
144	// supported only in case none of the plugins attached to this event returned FALSE
145	return !in_array(false, $results, true);
146	}
147
148	/**
149	* Returns the admin-widget priority for a custom ordering.
150	*
151	* @return int
152	*
153	* @since 1.16.10 (J) - 1.6.10 (WP)
154	*/
155	public function getPriority()
156	{
157	return 10;
158	}
159
160	/**
161	* Gets the name of the current widget.
162	*
163	* @return string the widget name.
164	*/
165	public function getName()
166	{
167	return $this->widgetName;
168	}
169
170	/**
171	* Gets the description for the current widget.
172	*
173	* @return string the widget description.
174	*/
175	public function getDescription()
176	{
177	return $this->widgetDescr;
178	}
179
180	/**
181	* Gets the icon for the current widget.
182	*
183	* @return string the widget HTML string icon.
184	*/
185	public function getIcon()
186	{
187	return !empty($this->widgetIcon) ? $this->widgetIcon : $this->getDefaultIcon();
188	}
189
190	/**
191	* Gets the style name for the current widget.
192	*
193	* @return string the widget style name.
194	*/
195	public function getStyleName()
196	{
197	return $this->widgetStyleName;
198	}
199
200	/**
201	* Gets the identifier of the current widget.
202	*
203	* @return string the widget identifier.
204	*/
205	public function getIdentifier()
206	{
207	if (!$this->widgetId) {
208	// fetch widget ID from class name
209	$this->widgetId = preg_replace("/^VikBookingAdminWidget/i", '', get_class($this));
210	// place an underscore between each camelCase
211	$this->widgetId = strtolower(preg_replace("/([a-z])([A-Z])/", '$1_$2', $this->widgetId));
212	$this->widgetId = strtolower($this->widgetId);
213	}
214
215	return $this->widgetId;
216	}
217
218	/**
219	* Turns on/off the flag to detect multitask rendering.
220	*
221	* @param bool $in true if in multitask panel, or false.
222	*
223	* @return self
224	*
225	* @since 1.15.0 (J) - 1.5.0 (WP)
226	*/
227	public function setInMultitask($in = false)
228	{
229	$this->is_multitask = (bool)$in;
230
231	return $this;
232	}
233
234	/**
235	* Default method to preload the necessary assets of the widget.
236	* Extending classes needing certain assets to be available should
237	* override this method and let it load the CSS/JS assets.
238	* Useful to avoid JS errors during the AJAX generation of a widget.
239	*
240	* The method can also be helpful for a widget to register watch data.
241	* For example, the last ID retrieved of a certain record can be used
242	* to receive it back during the periodic data-watching and be able
243	* to detect if a new event has occurred to fire a browser notification.
244	*
245	* @return mixed watch-data object or null.
246	*
247	* @since 1.15.0 (J) - 1.5.0 (WP)
248	*/
249	public function preload()
250	{
251	return null;
252	}
253
254	/**
255	* Default method to return a list of watch-data and new browser notifications.
256	* Extending classes needing to periodically watch for new events and capable
257	* of emitting browser notifications, can override this method. The last data
258	* to watch should be returned during the preloading. To be used with list().
259	*
260	* @param ?VBONotificationWatchdata $watch_data the preloaded watch-data object.
261	*
262	* @return array data object to watch next and notifications array.
263	*
264	* @see preload()
265	*
266	* @since 1.15.0 (J) - 1.5.0 (WP)
267	*/
268	public function getNotifications(?VBONotificationWatchdata $watch_data = null)
269	{
270	$watch_next = null;
271	$notifications = null;
272
273	return [$watch_next, $notifications];
274	}
275
276	/**
277	* Default method to return a list of browser events to dispatch.
278	* Extending classes needing to periodically watch for new events
279	* and capable of emitting browser events, can override this method.
280	*
281	* @param ?VBONotificationWatchdata $watch_data the preloaded watch-data object.
282	*
283	* @return array list of browser events to emit.
284	*
285	* @see preload()
286	*
287	* @since 1.16.8 (J) - 1.6.8 (WP)
288	*/
289	public function getNotificationEvents(?VBONotificationWatchdata $watch_data = null)
290	{
291	return [];
292	}
293
294	/**
295	* Binds the widget options at runtime when multitask data is available.
296	* Options live on a separate layer than regular multitask data.
297	*
298	* @param VBOMultitaskData\|VBOMultitaskOptions\|array\|object $options options to bind.
299	*
300	* @return self
301	*
302	* @since 1.16.5 (J) - 1.6.5 (WP)
303	*/
304	public function bindOptions($options)
305	{
306	if ($options instanceof VBOMultitaskData) {
307	// set options by extracting them from multitask data
308	$this->options->setProperties($options->getDataOptions());
309	} elseif ($options instanceof VBOMultitaskOptions) {
310	// replace options with given instance
311	$this->options = $options;
312	} elseif (is_array($options) \|\| is_object($options)) {
313	// bind new options
314	$this->options = VBOMultitaskOptions::getInstance($options);
315	}
316
317	return $this;
318	}
319
320	/**
321	* Gets all widget options previously set through Multitask data.
322	* Options live on a separate layer than regular Multitask data.
323	*
324	* @param bool $public true to get only the public options.
325	*
326	* @return array associative list of options, if any.
327	*
328	* @since 1.16.5 (J) - 1.6.5 (WP)
329	*/
330	public function getOptions($public = false)
331	{
332	return $this->options->getProperties($public);
333	}
334
335	/**
336	* Proxy to access the multitask options object.
337	*
338	* @return VBOMultitaskOptions
339	*
340	* @since 1.16.5 (J) - 1.6.5 (WP)
341	*/
342	public function options()
343	{
344	return $this->options;
345	}
346
347	/**
348	* Sets a widget option value.
349	*
350	* @param string $key the option key identifier.
351	* @param mixed $value the option value to set.
352	*
353	* @return self
354	*
355	* @since 1.16.5 (J) - 1.6.5 (WP)
356	*/
357	public function setOption($key, $value)
358	{
359	$this->options->set($key, $value);
360
361	return $this;
362	}
363
364	/**
365	* Gets the value for the given widget option key.
366	*
367	* @param string $key the option key identifier.
368	* @param mixed $default the default value to get.
369	*
370	* @return mixed
371	*
372	* @since 1.16.5 (J) - 1.6.5 (WP)
373	*/
374	public function getOption($key, $default = null)
375	{
376	return $this->options->get($key, $default);
377	}
378
379	/**
380	* Returns an associative array with the current widget details.
381	* Method's visibility should never change from public, because
382	* the controller may call it, and widgets may override it.
383	*
384	* @return array
385	*
386	* @since 1.16.7 (J) - 1.6.7 (WP)
387	*/
388	public function getWidgetDetails()
389	{
390	return [
391	'id' => $this->getIdentifier(),
392	'name' => $this->getName(),
393	'descr' => $this->getDescription(),
394	'icon' => $this->getIcon(),
395	'style' => $this->getStyleName(),
396	];
397	}
398
399	/**
400	* Extending Classes should define this method to render the actual
401	* output of the admin widget. Multitask data can be passed along.
402	*
403	* @param ?VBOMultitaskData $data optional multitask data object.
404	*
405	* @since 1.15.0 (J) - 1.5.0 (WP) type hint added for $data argument.
406	*/
407	abstract public function render(?VBOMultitaskData $data = null);
408
409	/**
410	* Returns the default icon for a widget.
411	*
412	* @return string the default widget icon HTML string.
413	*/
414	protected function getDefaultIcon()
415	{
416	return '<i class="' . VikBookingIcons::i('cube') . '"></i>';
417	}
418
419	/**
420	* Tells the widget if its being rendered via AJAX.
421	*
422	* @return bool true if rendering is being made via AJAX.
423	*/
424	protected function isAjaxRendering()
425	{
426	$widget_id = VikRequest::getString('widget_id', '', 'request');
427	$call = VikRequest::getString('call', '', 'request');
428
429	return ($widget_id == $this->getIdentifier() && $call == 'render');
430	}
431
432	/**
433	* Tells the widget if its being rendered in the multitask panel.
434	* This kind of rendering could be in an AJAX context or in a regular
435	* loading flow. Use the apposite method to see if it's an AJAX rendering.
436	*
437	* @return bool true if rendering is handled by the multitask panel.
438	*
439	* @since 1.15.0 (J) - 1.5.0 (WP)
440	*/
441	protected function isMultitaskRendering()
442	{
443	$multitask = VikRequest::getInt('multitask', 0, 'request');
444
445	return ($multitask > 0 \|\| $this->is_multitask === true);
446	}
447
448	/**
449	* Tells the widget if VCM is available.
450	*
451	* @return bool true if Vik Channel Manager is available.
452	*
453	* @since 1.16.0 (J) - 1.6.0 (WP)
454	*/
455	protected function hasChannelManager()
456	{
457	return is_file(VCM_SITE_PATH . DIRECTORY_SEPARATOR . 'helpers' . DIRECTORY_SEPARATOR . 'lib.vikchannelmanager.php');
458	}
459
460	/**
461	* Gets the configuration parameter name for the widget's settings.
462	*
463	* @return string the param name of the settings record.
464	*/
465	protected function getSettingsParamName()
466	{
467	return 'admin_widget_' . $this->getIdentifier();
468	}
469
470	/**
471	* Loads the widget's settings from the configuration table, if any.
472	* If no record found for this widget, an empty record will be inserted.
473	*
474	* @return mixed the widget settings.
475	*/
476	protected function loadSettings()
477	{
478	$dbo = JFactory::getDbo();
479
480	$param_name = $this->getSettingsParamName();
481
482	$q = "SELECT `setting` FROM `#__vikbooking_config` WHERE `param`=" . $dbo->quote($param_name);
483	$dbo->setQuery($q, 0, 1);
484	$settings = $dbo->loadResult();
485
486	if (!$settings) {
487	return null;
488	}
489
490	if (in_array(substr($settings, 0, 1), array('{', '['))) {
491	// we have detected a JSON string, try to decoded it
492	$decoded = json_decode($settings);
493	if (function_exists('json_last_error') && json_last_error()) {
494	// json is broken, reset settings and return null
495	$this->resetSettings();
496	return null;
497	}
498	// return the decoded settings
499	return $decoded;
500	}
501
502	// return the plain db value otherwise
503	return $settings;
504	}
505
506	/**
507	* Updates the widget's settings in the configuration table.
508	*
509	* @param mixed $data the settings to store, must be a scalar.
510	*
511	* @return bool true on success, false otherwise.
512	*/
513	protected function updateSettings($data)
514	{
515	if ($data === null \|\| !is_scalar($data)) {
516	return false;
517	}
518
519	$param_name = $this->getSettingsParamName();
520
521	$config = VBOFactory::getConfig();
522	$config->set($param_name, $data);
523
524	return true;
525	}
526
527	/**
528	* Resets the settings of the widget.
529	*
530	* @return bool
531	*/
532	public function resetSettings()
533	{
534	$dbo = JFactory::getDbo();
535
536	$param_name = $this->getSettingsParamName();
537
538	$q = "SELECT `setting` FROM `#__vikbooking_config` WHERE `param`=" . $dbo->quote($param_name) . ";";
539	$dbo->setQuery($q);
540	$dbo->execute();
541	if (!$dbo->getNumRows()) {
542	// settings never used
543	return false;
544	}
545
546	$q = "DELETE FROM `#__vikbooking_config` WHERE `param`=" . $dbo->quote($param_name) . ";";
547	$dbo->setQuery($q);
548	$dbo->execute();
549
550	return true;
551	}
552
553	/**
554	* Method invoked during AJAX requests for removing an instance of this widget.
555	* By default we try to unset the passed instance index from the settings array.
556	* If the widget does not use settings, nothing is done. Widgets could override this method.
557	*
558	* @return bool true if settings needed to be updated, false otherwise.
559	*/
560	public function removeInstance()
561	{
562	$settings = $this->loadSettings();
563	if ($settings === null \|\| !is_array($settings)) {
564	return false;
565	}
566
567	$widget_instance = VikRequest::getInt('widget_instance', -1, 'request');
568
569	if (!isset($settings[$widget_instance])) {
570	// settings index not found
571	return false;
572	}
573
574	// splice the array to remove the requested settings instance
575	array_splice($settings, $widget_instance, 1);
576
577	// update widget's settings
578	$this->updateSettings(json_encode($settings));
579
580	return true;
581	}
582
583	/**
584	* Method invoked during AJAX requests for moving an instance of this widget.
585	* This occurs when dragging and dropping the same type of widget to a different position.
586	* If the widget does not use settings, nothing is done. Widgets could override this method.
587	*
588	* @return bool true if settings needed to be updated, false otherwise.
589	*/
590	public function sortInstance()
591	{
592	$settings = $this->loadSettings();
593	if ($settings === null \|\| !is_array($settings)) {
594	return false;
595	}
596
597	$widget_index_old = VikRequest::getInt('widget_index_old', -1, 'request');
598	$widget_index_new = VikRequest::getInt('widget_index_new', -1, 'request');
599
600	if (!isset($settings[$widget_index_old]) \|\| !isset($settings[$widget_index_new])) {
601	// settings index not found
602	return false;
603	}
604
605	// move the settings requested from the old index to the new index
606	$extracted = array_splice($settings, $widget_index_old, 1);
607	array_splice($settings, $widget_index_new, 0, $extracted);
608
609	// update widget's settings
610	$this->updateSettings(json_encode($settings));
611
612	return true;
613	}
614
615	/**
616	* Returns the name of the user currently logged in.
617	*
618	* @return string the name of the current user.
619	*/
620	protected function getLoggedUserName()
621	{
622	$user = JFactory::getUser();
623	$name = $user->name;
624
625	return $name;
626	}
627
628	/**
629	* Rewrites a given URI to perform an AJAX request.
630	*
631	* @param string $uri the optional URI plus query to force.
632	*
633	* @return string the proper AJAX uri for the current platform.
634	*
635	* @since 1.15.0 (J) - 1.5.0 (WP)
636	*/
637	protected function getExecWidgetAjaxUri($uri = '')
638	{
639	if (empty($uri)) {
640	$uri = 'index.php?option=com_vikbooking&task=exec_admin_widget';
641	}
642
643	return VikBooking::ajaxUrl($uri);
644	}
645
646	/**
647	* Returns the date format in VBO of a particular type.
648	*
649	* @param string $type
650	*
651	* @return string
652	*
653	* @since 1.15.0 (J) - 1.5.0 (WP)
654	*/
655	protected function getDateFormat($type = 'date')
656	{
657	if ($this->df == 'd/m/Y') {
658	$juidf = 'dd/mm/yy';
659	} elseif ($this->df == 'm/d/Y') {
660	$juidf = 'mm/dd/yy';
661	} else {
662	$juidf = 'yy/mm/dd';
663	}
664
665	switch ($type) {
666	case 'jui':
667	return $juidf;
668	case 'joomla':
669	case 'wordpress':
670	return VikBooking::getDateFormat(true);
671	default:
672	return $this->df;
673	}
674	}
675	}
676