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
|
<?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\Plugin;
use Piwik\Common;
use Piwik\Development;
use Piwik\Menu\MenuAdmin;
use Piwik\Menu\MenuTop;
use Piwik\Plugin\Manager as PluginManager;
use Piwik\Plugins\UsersManager\UserPreferences;
/**
* Base class of all plugin menu providers. Plugins that define their own menu items can extend this class to easily
* add new items, to remove or to rename existing items.
*
* Descendants of this class can overwrite any of these methods. Each method will be executed only once per request
* and cached for any further menu requests.
*
* For an example, see the {@link https://github.com/piwik/piwik/blob/master/plugins/ExampleUI/Menu.php} plugin.
*
* @api
* @since 2.4.0
*/
class Menu
{
public function __construct()
{
// Constructor kept for BC (because called in implementations)
}
private function getModule()
{
$className = get_class($this);
$className = explode('\\', $className);
return $className[2];
}
/**
* Generates a URL for the default action of the plugin controller.
*
* Example:
* ```
* $menu->addItem('MyPlugin_MyPlugin', '', $this->urlForDefaultAction(), $orderId = 30);
* // will add a menu item that leads to the default action of the plugin controller when a user clicks on it.
* // The default action is usually the `index` action - meaning the `index()` method the controller -
* // but the default action can be customized within a controller
* ```
*
* @param array $additionalParams Optional URL parameters that will be appended to the URL
* @return array
*
* @since 2.7.0
* @api
*/
protected function urlForDefaultAction($additionalParams = array())
{
$params = (array) $additionalParams;
$params['action'] = '';
$params['module'] = $this->getModule();
return $params;
}
/**
* Generates a URL for the given action. In your plugin controller you have to create a method with the same name
* as this method will be executed when a user clicks on the menu item. If you want to generate a URL for the
* action of another module, meaning not your plugin, you should use the method {@link urlForModuleAction()}.
*
* @param string $controllerAction The name of the action that should be executed within your controller
* @param array $additionalParams Optional URL parameters that will be appended to the URL
* @return array
*
* @since 2.7.0
* @api
*/
protected function urlForAction($controllerAction, $additionalParams = array())
{
$module = $this->getModule();
$this->checkisValidCallable($module, $controllerAction);
$params = (array) $additionalParams;
$params['action'] = $controllerAction;
$params['module'] = $module;
return $params;
}
/**
* Generates a URL for the given action of the given module. We usually do not recommend to use this method as you
* should make sure the method of that module actually exists. If the plugin owner of that module changes the method
* in a future version your link might no longer work. If you want to link to an action of your controller use the
* method {@link urlForAction()}. Note: We will generate a link only if the given module is installed and activated.
*
* @param string $module The name of the module/plugin the action belongs to. The module name is case sensitive.
* @param string $controllerAction The name of the action that should be executed within your controller
* @param array $additionalParams Optional URL parameters that will be appended to the URL
* @return array|null Returns null if the given module is either not installed or not activated. Returns the array
* of query parameter names and values to the given module action otherwise.
*
* @since 2.7.0
* // not API for now
*/
protected function urlForModuleAction($module, $controllerAction, $additionalParams = array())
{
$this->checkisValidCallable($module, $controllerAction);
$pluginManager = PluginManager::getInstance();
if (!$pluginManager->isPluginLoaded($module) ||
!$pluginManager->isPluginActivated($module)) {
return null;
}
$params = (array) $additionalParams;
$params['action'] = $controllerAction;
$params['module'] = $module;
return $params;
}
/**
* Generates a URL to the given action of the current module, and it will also append some URL query parameters from the
* User preferences: idSite, period, date. If you do not need the parameters idSite, period and date to be generated
* use {@link urlForAction()} instead.
*
* @param string $controllerAction The name of the action that should be executed within your controller
* @param array $additionalParams Optional URL parameters that will be appended to the URL
* @return array Returns the array of query parameter names and values to the given module action and idSite date and period.
*
*/
protected function urlForActionWithDefaultUserParams($controllerAction, $additionalParams = array())
{
$module = $this->getModule();
return $this->urlForModuleActionWithDefaultUserParams($module, $controllerAction, $additionalParams);
}
/**
* Generates a URL to the given action of the given module, and it will also append some URL query parameters from the
* User preferences: idSite, period, date. If you do not need the parameters idSite, period and date to be generated
* use {@link urlForModuleAction()} instead.
*
* @param string $module The name of the module/plugin the action belongs to. The module name is case sensitive.
* @param string $controllerAction The name of the action that should be executed within your controller
* @param array $additionalParams Optional URL parameters that will be appended to the URL
* @return array|null Returns the array of query parameter names and values to the given module action and idSite date and period.
* Returns null if the module or action is invalid.
*
*/
protected function urlForModuleActionWithDefaultUserParams($module, $controllerAction, $additionalParams = array())
{
$urlModuleAction = $this->urlForModuleAction($module, $controllerAction);
$date = Common::getRequestVar('date', false);
if ($date) {
$urlModuleAction['date'] = $date;
}
$period = Common::getRequestVar('period', false);
if ($period) {
$urlModuleAction['period'] = $period;
}
// We want the current query parameters to override the user's defaults
return array_merge(
$this->urlForDefaultUserParams(),
$urlModuleAction,
$additionalParams
);
}
/**
* Returns the &idSite=X&period=Y&date=Z query string fragment,
* fetched from current logged-in user's preferences.
*
* @param bool $websiteId
* @param bool $defaultPeriod
* @param bool $defaultDate
* @return array eg ['idSite' => 1, 'period' => 'day', 'date' => '2012-02-03']
* @throws \Exception in case a website was not specified and a default website id could not be found
*/
public function urlForDefaultUserParams($websiteId = false, $defaultPeriod = false, $defaultDate = false)
{
$userPreferences = new UserPreferences();
if (empty($websiteId)) {
$websiteId = $userPreferences->getDefaultWebsiteId();
}
if (empty($websiteId)) {
throw new \Exception("A website ID was not specified and a website to default to could not be found.");
}
if (empty($defaultDate)) {
$defaultDate = $userPreferences->getDefaultDate();
}
if (empty($defaultPeriod)) {
$defaultPeriod = $userPreferences->getDefaultPeriod(false);
}
return array(
'idSite' => $websiteId,
'period' => $defaultPeriod,
'date' => $defaultDate,
);
}
/**
* Configures the top menu which is supposed to contain analytics related items such as the
* "All Websites Dashboard".
*/
public function configureTopMenu(MenuTop $menu)
{
}
/**
* Configures the admin menu which is supposed to contain only administration related items such as
* "Websites", "Users" or "Settings".
*/
public function configureAdminMenu(MenuAdmin $menu)
{
}
private function checkisValidCallable($module, $action)
{
if (!Development::isEnabled()) {
return;
}
$prefix = 'Menu item added in ' . get_class($this) . ' will fail when being selected. ';
if (!is_string($action)) {
Development::error($prefix . 'No valid action is specified. Make sure the defined action that should be executed is a string.');
}
$reportAction = lcfirst(substr($action, 4));
if (ReportsProvider::factory($module, $reportAction)) {
return;
}
$controllerClass = '\\Piwik\\Plugins\\' . $module . '\\Controller';
if (!Development::methodExists($controllerClass, $action)) {
Development::error($prefix . 'The defined action "' . $action . '" does not exist in ' . $controllerClass . '". Make sure to define such a method.');
}
if (!Development::isCallableMethod($controllerClass, $action)) {
Development::error($prefix . 'The defined action "' . $action . '" is not callable on "' . $controllerClass . '". Make sure the method is public.');
}
}
}
|