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
|
<?php
/**
* Piwik - 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\Annotations;
use Piwik\API\Request;
use Piwik\Common;
use Piwik\Date;
use Piwik\View;
/**
* Controller for the Annotations plugin.
*
*/
class Controller extends \Piwik\Plugin\Controller
{
/**
* Controller action that returns HTML displaying annotations for a site and
* specific date range.
*
* Query Param Input:
* - idSite: The ID of the site to get annotations for. Only one allowed.
* - date: The date to get annotations for. If lastN is not supplied, this is the start date,
* otherwise the start date in the last period.
* - period: The period type.
* - lastN: If supplied, the last N # of periods will be included w/ the range specified
* by date + period.
*
* Output:
* - HTML displaying annotations for a specific range.
*
* @param bool $fetch True if the annotation manager should be returned as a string,
* false if it should be echo-ed.
* @param bool|string $date Override for 'date' query parameter.
* @param bool|string $period Override for 'period' query parameter.
* @param bool|string $lastN Override for 'lastN' query parameter.
* @return string|void
*/
public function getAnnotationManager($fetch = false, $date = false, $period = false, $lastN = false)
{
$this->checkSitePermission();
if ($date === false) {
$date = Common::getRequestVar('date', false);
}
if ($period === false) {
$period = Common::getRequestVar('period', 'day');
}
if ($lastN === false) {
$lastN = Common::getRequestVar('lastN', false);
}
// create & render the view
$view = new View('@Annotations/getAnnotationManager');
$allAnnotations = Request::processRequest(
'Annotations.getAll', array('date' => $date, 'period' => $period, 'lastN' => $lastN));
$view->annotations = empty($allAnnotations[$this->idSite]) ? array() : $allAnnotations[$this->idSite];
$view->period = $period;
$view->lastN = $lastN;
list($startDate, $endDate) = API::getDateRangeForPeriod($date, $period, $lastN);
$view->startDate = $startDate->toString();
$view->endDate = $endDate->toString();
if ($startDate->toString() !== $endDate->toString()) {
$view->selectedDate = Date::today()->toString();
} else {
$view->selectedDate = $endDate->toString();
}
$dateFormat = Date::DATE_FORMAT_SHORT;
$view->startDatePretty = $startDate->getLocalized($dateFormat);
$view->endDatePretty = $endDate->getLocalized($dateFormat);
$view->canUserAddNotes = AnnotationList::canUserAddNotesFor($this->idSite);
return $view->render();
}
/**
* Controller action that modifies an annotation and returns HTML displaying
* the modified annotation.
*
* Query Param Input:
* - idSite: The ID of the site the annotation belongs to. Only one ID is allowed.
* - idNote: The ID of the annotation.
* - date: The new date value for the annotation. (optional)
* - note: The new text for the annotation. (optional)
* - starred: Either 1 or 0. Whether the note should be starred or not. (optional)
*
* Output:
* - HTML displaying modified annotation.
*
* If an optional query param is not supplied, that part of the annotation is
* not modified.
*/
public function saveAnnotation()
{
if ($_SERVER["REQUEST_METHOD"] == "POST") {
$this->checkTokenInUrl();
$view = new View('@Annotations/saveAnnotation');
// NOTE: permissions checked in API method
// save the annotation
$view->annotation = Request::processRequest("Annotations.save");
return $view->render();
}
}
/**
* Controller action that adds a new annotation for a site and returns new
* annotation manager HTML for the site and date range.
*
* Query Param Input:
* - idSite: The ID of the site to add an annotation to.
* - date: The date for the new annotation.
* - note: The text of the annotation.
* - starred: Either 1 or 0, whether the annotation should be starred or not.
* Defaults to 0.
* - managerDate: The date for the annotation manager. If a range is given, the start
* date is used for the new annotation.
* - managerPeriod: For rendering the annotation manager. @see self::getAnnotationManager
* for more info.
* - lastN: For rendering the annotation manager. @see self::getAnnotationManager
* for more info.
* Output:
* - @see self::getAnnotationManager
*/
public function addAnnotation()
{
if ($_SERVER["REQUEST_METHOD"] == "POST") {
$this->checkTokenInUrl();
// the date used is for the annotation manager HTML that gets echo'd. we
// use this date for the new annotation, unless it is a date range, in
// which case we use the first date of the range.
$date = Common::getRequestVar('date');
if (strpos($date, ',') !== false) {
$date = reset(explode(',', $date));
}
// add the annotation. NOTE: permissions checked in API method
Request::processRequest("Annotations.add", array('date' => $date));
$managerDate = Common::getRequestVar('managerDate', false);
$managerPeriod = Common::getRequestVar('managerPeriod', false);
return $this->getAnnotationManager($fetch = true, $managerDate, $managerPeriod);
}
}
/**
* Controller action that deletes an annotation and returns new annotation
* manager HTML for the site & date range.
*
* Query Param Input:
* - idSite: The ID of the site this annotation belongs to.
* - idNote: The ID of the annotation to delete.
* - date: For rendering the annotation manager. @see self::getAnnotationManager
* for more info.
* - period: For rendering the annotation manager. @see self::getAnnotationManager
* for more info.
* - lastN: For rendering the annotation manager. @see self::getAnnotationManager
* for more info.
*
* Output:
* - @see self::getAnnotationManager
*/
public function deleteAnnotation()
{
if ($_SERVER["REQUEST_METHOD"] == "POST") {
$this->checkTokenInUrl();
// delete annotation. NOTE: permissions checked in API method
Request::processRequest("Annotations.delete");
return $this->getAnnotationManager($fetch = true);
}
}
/**
* Controller action that echo's HTML that displays marker icons for an
* evolution graph's x-axis. The marker icons still need to be positioned
* by the JavaScript.
*
* Query Param Input:
* - idSite: The ID of the site this annotation belongs to. Only one is allowed.
* - date: The date to check for annotations. If lastN is not supplied, this is
* the start of the date range used to check for annotations. If supplied,
* this is the start of the last period in the date range.
* - period: The period type.
* - lastN: If supplied, the last N # of periods are included in the date range
* used to check for annotations.
*
* Output:
* - HTML that displays marker icons for an evolution graph based on the
* number of annotations & starred annotations in the graph's date range.
*/
public function getEvolutionIcons()
{
// get annotation the count
$annotationCounts = Request::processRequest(
"Annotations.getAnnotationCountForDates", array('getAnnotationText' => 1));
// create & render the view
$view = new View('@Annotations/getEvolutionIcons');
$view->annotationCounts = reset($annotationCounts); // only one idSite allowed for this action
return $view->render();
}
}
|