blob: 5831d23bbbbb825f440885493896029cceb5ddb1 (
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
|
<?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\Category;
/**
* Base type for subcategories.
*
* All widgets within a subcategory will be rendered in the Piwik reporting UI under the same page. By default
* you do not have to specify any subcategory as they are created automatically. Only create a subcategory if you
* want to change the name for a specific subcategoryId or if you want to specifiy a different order so the subcategory
* appears eg at a different order in the reporting menu. It also affects the order of reports in
* `API.getReportMetadata` and wherever we display any reports.
*
* To define a subcategory just place a subclass within the `Categories` folder of your plugin.
*
* Subcategories can also be added through the {@hook Subcategory.addSubcategories} event.
*
* @api since Piwik 3.0.0
*/
class Subcategory
{
/**
* The id of the subcategory, see eg {@link Piwik\Widget\WidgetConfig::setSubcategoryId()`} or
* {@link Piwik\Report\getSubcategoryId()}. The id will be used in the Piwik reporting URL and as the name
* in the Piwik reporting submenu. If you want to define a different URL and name, specify a {@link $name}.
* For example you might want to have the actual GoalId (eg '4') in the URL but the actual goal name in the
* submenu (eg 'Downloads'). In this case one should specify `$id=4;$name='Downloads'`.
*
* @var string eg 'General_Overview' or 'VisitTime_ByServerTimeWidgetName'.
*/
protected $id = '';
/**
* The id of the category the subcategory belongs to, must be specified.
* See {@link Piwik\Widget\WidgetConfig::setCategoryId()`} or {@link Piwik\Report\getCategoryId()}.
*
* @var string A translation key eg 'General_Visits' or 'Goals_Goals'
*/
protected $categoryId = '';
/**
* The name that shall be used in the menu etc, defaults to the specified {@link $id}. See {@link $id}.
* @var string
*/
protected $name = '';
/**
* The order of the subcategory. The lower the value the earlier a widget or a report will be displayed.
* @var int
*/
protected $order = 99;
/**
* Sets (overwrites) the id of the subcategory see {@link $id}.
*
* @param string $id A translation key eg 'General_Overview'.
* @return static
*/
public function setId($id)
{
$this->id = $id;
return $this;
}
/**
* Get the id of the subcategory.
* @return string
*/
public function getId()
{
return $this->id;
}
/**
* Get the specifed categoryId see {@link $categoryId}.
*
* @return string
*/
public function getCategoryId()
{
return $this->categoryId;
}
/**
* Sets (overwrites) the categoryId see {@link $categoryId}.
*
* @param string $categoryId
* @return static
*/
public function setCategoryId($categoryId)
{
$this->categoryId = $categoryId;
return $this;
}
/**
* Sets (overwrites) the name see {@link $name} and {@link $id}.
*
* @param string $name A translation key eg 'General_Overview'.
* @return static
*/
public function setName($name)
{
$this->name = $name;
return $this;
}
/**
* Get the name of the subcategory.
* @return string
*/
public function getName()
{
if (!empty($this->name)) {
return $this->name;
}
return $this->id;
}
/**
* Sets (overwrites) the order see {@link $order}.
*
* @param int $order
* @return static
*/
public function setOrder($order)
{
$this->order = (int) $order;
return $this;
}
/**
* Get the order of the subcategory.
* @return int
*/
public function getOrder()
{
return $this->order;
}
}
|