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
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
|
<?php
/**
* Piwik - free/libre analytics platform
*
* @link http://piwik.org
* @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
*
*/
namespace Piwik\Widget;
use Piwik\Piwik;
use Exception;
/**
* Configures a widget. Use this class to configure a {@link Piwik\Widget\Widget`} or to
* add a widget to the WidgetsList via {@link WidgetsList::addWidget}.
*
* @api since Piwik 3.0.0
*/
class WidgetConfig
{
protected $categoryId = '';
protected $subcategoryId = '';
protected $module = '';
protected $action = '';
protected $parameters = array();
protected $middlewareParameters = array();
protected $name = '';
protected $order = 99;
protected $isEnabled = true;
protected $isWidgetizable = true;
/**
* Set the id of the category the widget belongs to.
* @param string $categoryId Usually a translation key, eg 'General_Visits', 'Goals_Goals', ...
* @return static
*/
public function setCategoryId($categoryId)
{
$this->categoryId = $categoryId;
return $this;
}
/**
* Get the id of the category the widget belongs to.
* @return string
*/
public function getCategoryId()
{
return $this->categoryId;
}
/**
* Set the id of the subcategory the widget belongs to. If a subcategory is specified, the widget
* will be shown in the Piwik reporting UI. The subcategoryId will be used as a translation key for
* the submenu item.
*
* @param string $subcategoryId Usually a translation key, eg 'General_Overview', 'Actions_Pages', ...
* @return static
*/
public function setSubcategoryId($subcategoryId)
{
$this->subcategoryId = $subcategoryId;
return $this;
}
public function getSubcategoryId()
{
return $this->subcategoryId;
}
/**
* Set the module (aka plugin name) of the widget. The correct module is usually detected automatically and
* not needed to be configured manually.
*
* @param string $module eg 'CoreHome'
* @return static
*/
public function setModule($module)
{
$this->module = $module;
return $this;
}
public function getModule()
{
return $this->module;
}
/**
* Set the action of the widget that shall be used in the URL to render the widget.
* The correct action is usually detected automatically and not needed to be configured manually.
*
* @param string $action eg 'renderMyWidget'
* @return static
*/
public function setAction($action)
{
$this->action = $action;
return $this;
}
public function getAction()
{
return $this->action;
}
/**
* Sets (overwrites) the parameters of the widget. These parameters will be added to the URL when rendering the
* widget. You can access these parameters via `Piwik\Common::getRequestVar(...)`.
*
* @param array $parameters eg. ('urlparam' => 'urlvalue')
* @return static
*/
public function setParameters($parameters)
{
$this->parameters = $parameters;
return $this;
}
/**
* Add new parameters and only overwrite parameters that have the same name. See {@link setParameters()}
*
* @param array $parameters eg. ('urlparam' => 'urlvalue')
* @return static
*/
public function addParameters($parameters)
{
$this->parameters = array_merge($this->parameters, $parameters);
return $this;
}
/**
* Get all URL parameters needed to render this widget.
* @return array Eg ('urlparam' => 'urlvalue').
*/
public function getParameters()
{
$defaultParams = array(
'module' => $this->getModule(),
'action' => $this->getAction()
);
return $defaultParams + $this->parameters;
}
/**
* Set the name of the widget.
*
* @param string $name Usually a translation key, eg 'VisitTime_ByServerTimeWidgetName'
* @return static
*/
public function setName($name)
{
$this->name = $name;
return $this;
}
/**
* Get the name of the widget.
*
* @return string
*/
public function getName()
{
return $this->name;
}
/**
* Set the order of the widget.
*
* @param int $order eg. 5
* @return static
*/
public function setOrder($order)
{
$this->order = (int) $order;
return $this;
}
/**
* Returns the order of the widget.
* @return int
*/
public function getOrder()
{
return $this->order;
}
/**
* Defines whether a widget is enabled or not. For instance some widgets might not be available to every user or
* might depend on a setting (such as Ecommerce) of a site. In such a case you can perform any checks and then
* return `true` or `false`. If your report is only available to users having super user access you can do the
* following: `return Piwik::hasUserSuperUserAccess();`
* @return bool
* @api
*/
public function isEnabled()
{
return $this->isEnabled;
}
/**
* Enable / disable the widget. See {@link isEnabled()}
*
* @param bool $isEnabled
* @return static
*/
public function setIsEnabled($isEnabled)
{
$this->isEnabled = (bool) $isEnabled;
return $this;
}
/**
* Enables the widget. See {@link isEnabled()}
*/
public function enable()
{
$this->setIsEnabled(true);
}
/**
* Disables the widget. See {@link isEnabled()}
*/
public function disable()
{
$this->setIsEnabled(false);
}
/**
* This method checks whether the widget is available, see {@link isEnabled()}. If not, it triggers an exception
* containing a message that will be displayed to the user. You can overwrite this message in case you want to
* customize the error message. Eg.
* ```
* if (!$this->isEnabled()) {
* throw new Exception('Setting XYZ is not enabled or the user has not enough permission');
* }
* ```
* @throws \Exception
* @api
*/
public function checkIsEnabled()
{
if (!$this->isEnabled()) {
throw new Exception(Piwik::translate('General_ExceptionWidgetNotEnabled'));
}
}
/**
* Returns the unique id of an widget based on module, action and the set parameters.
*
* @return string
*/
public function getUniqueId()
{
$parameters = $this->getParameters();
unset($parameters['module']);
unset($parameters['action']);
return WidgetsList::getWidgetUniqueId($this->getModule(), $this->getAction(), $parameters);
}
/**
* Sets the widget as not widgetizable {@link isWidgetizeable()}.
*
* @return static
*/
public function setIsNotWidgetizable()
{
$this->isWidgetizable = false;
return $this;
}
/**
* Sets the widget as widgetizable {@link isWidgetizeable()}.
*
* @return static
*/
public function setIsWidgetizable()
{
$this->isWidgetizable = true;
return $this;
}
/**
* Detect whether the widget is widgetizable meaning it won't be able to add it to the dashboard and it won't
* be possible to export the widget via an iframe if it is not widgetizable. This is usually not needed but useful
* when you eg want to display a widget within the Piwik UI but not want to have it widgetizable.
*
* @return bool
*/
public function isWidgetizeable()
{
return $this->isWidgetizable;
}
/**
* If middleware parameters are specified, the corresponding action will be executed before showing the
* actual widget in the UI. Only if this action (can be a controller method or API method) returns JSON `true`
* the widget will be actually shown. It is similar to `isEnabled()` but the specified action is performed each
* time the widget is requested in the UI whereas `isEnabled` is only checked once on the inital page load when
* we load the inital list of widgets. So if your widget's visibility depends on archived data
* (aka idSite/period/date) you should specify middle parameters. This has mainly two reasons:
*
* - This way the inital page load time is faster as we won't have to request archived data on the initial page
* load for widgets that are potentially never shown.
* - We execute that action every time before showing it. As the initial list of widgets is loaded on page load
* it is possible that some archives have no data yet, but at a later time there might be actually archived data.
* As we never reload the initial list of widgets we would still not show the widget even there we should. Example:
* On page load there are no conversions, a few minutes later there might be conversions. As the middleware is
* executed before showing it, we detect correctly that there are now conversions whereas `isEnabled` is only
* checked once on the initial Piwik page load.
*
* @param array $parameters URL parameters eg array('module' => 'Goals', 'action' => 'Conversions')
* @return static
*/
public function setMiddlewareParameters($parameters)
{
$this->middlewareParameters = $parameters;
return $this;
}
/**
* Get defined middleware parameters (if any).
*
* @return array
*/
public function getMiddlewareParameters()
{
return $this->middlewareParameters;
}
}
|