blob: 22836f6591767cc0edc6831b680a588c6e37aa29 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
<?php
/**
* Matomo - free/libre analytics platform
*
* @link https://matomo.org
* @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
*
*/
namespace Piwik\Plugins\Tour\Engagement;
use Piwik\Piwik;
use Piwik\Settings\Storage\Backend\PluginSettingsTable;
/**
* Defines a new challenge which a super user needs to complete in order to become a "Matomo expert".
* Plugins can add new challenges by listening to the {@hook Tour.filterChallenges} event.
*
* @since 3.10.0
* @api
*/
abstract class Challenge
{
const APPENDIX_SKIPPED = '_skipped';
const APPENDIX_COMPLETED = '_completed';
private static $settings = null;
public function __construct()
{
}
/**
* The human readable name that will be shown in the onboarding widget. Should be max 3 or 4 words and represent an
* action, like "Add a report"
* @return string
*/
abstract public function getName();
/**
* A short unique ID that represents this challenge, for example "add_report".
* @return string
*/
abstract public function getId();
/**
* By default, we attribute a challenge as soon as it was completed manually by calling `$challenge->setCompleted()`.
*
* If we can detect whether a particular user has already completed a challenge in the past then we mark it automatically
* as completed. We can detect this automatically eg by querying the DB and check if a particular login has for example
* created a segment etc. We do this only if the query is supposed to be fast. Otherwise we would fallback to the manual
* way.
*
* @return bool
*/
public function isCompleted()
{
return $this->hasAttribute(self::APPENDIX_COMPLETED);
}
/**
* By default challenges are enabled, if is not appropriate to display a challenge at this time because some condition
* has not been met then the challenge can be set as disabled by overriding this method. The constructor code will
* still be run every time the challenges are loaded. To disable a challenge based on plugin availablilty it is better
* to add a check to the Piwik\Plugins\Tour\Engagement::getChallenges() method
*
* @return false
*/
public function isDisabled()
{
return false;
}
/**
* A detailed description that describes the value of the action the user needs to complete, or some tips on how
* to complete this challenge. Will be shown when hovering a challenge name.
* @return string
*/
public function getDescription()
{
return '';
}
/**
* A URL that has more information about how to complete the given event or a URL within the Matomo app to directly
* complete a challenge. For example "add_user" challenge could directly link to the user management.
* @return string
*/
public function getUrl()
{
return '';
}
private function getPluginSettingsInstance()
{
return new PluginSettingsTable('Tour', Piwik::getCurrentUserLogin());
}
private function getSettings()
{
if (!isset(self::$settings)) {
$pluginSettings = $this->getPluginSettingsInstance();
self::$settings = $pluginSettings->load();
}
return self::$settings;
}
public static function clearCache()
{
self::$settings = null;
}
/**
* Detect if the challenge was skipped.
* @ignore
* @return bool
*/
public function isSkipped()
{
return $this->hasAttribute(self::APPENDIX_SKIPPED);
}
/**
* Skip this challenge.
* @ignore
* @return bool
*/
public function skipChallenge()
{
$this->storeAttribute(self::APPENDIX_SKIPPED);
}
/**
* Set this challenge was completed successfully by the current user. Only works for a super user.
* @return bool
*/
public function setCompleted()
{
$this->storeAttribute(self::APPENDIX_COMPLETED);
}
private function hasAttribute($appendix)
{
$settings = $this->getSettings();
if (!empty($settings[$this->getId() . $appendix])) {
return true;
}
return false;
}
private function storeAttribute($appendix)
{
if (!Piwik::hasUserSuperUserAccess()) {
return;
}
$pluginSettings = $this->getPluginSettingsInstance();
$settings = $pluginSettings->load();
if (empty($settings[$this->getId() . $appendix])) {
$settings[$this->getId() . $appendix] = '1';
$pluginSettings->save($settings);
self::clearCache();
}
}
}
|
