1<?php 2/** 3 * Matomo - free/libre analytics platform 4 * 5 * @link https://matomo.org 6 * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later 7 */ 8namespace Piwik\Category; 9 10/** 11 * Base type for subcategories. 12 * 13 * All widgets within a subcategory will be rendered in the Piwik reporting UI under the same page. By default 14 * you do not have to specify any subcategory as they are created automatically. Only create a subcategory if you 15 * want to change the name for a specific subcategoryId or if you want to specify a different order so the subcategory 16 * appears eg at a different order in the reporting menu. It also affects the order of reports in 17 * `API.getReportMetadata` and wherever we display any reports. 18 * 19 * To define a subcategory just place a subclass within the `Categories` folder of your plugin. 20 * 21 * Subcategories can also be added through the {@hook Subcategory.addSubcategories} event. 22 * 23 * @api since Piwik 3.0.0 24 */ 25class Subcategory 26{ 27 /** 28 * The id of the subcategory, see eg {@link Piwik\Widget\WidgetConfig::setSubcategoryId()`} or 29 * {@link Piwik\Report\getSubcategoryId()}. The id will be used in the Piwik reporting URL and as the name 30 * in the Piwik reporting submenu. If you want to define a different URL and name, specify a {@link $name}. 31 * For example you might want to have the actual GoalId (eg '4') in the URL but the actual goal name in the 32 * submenu (eg 'Downloads'). In this case one should specify `$id=4;$name='Downloads'`. 33 * 34 * @var string eg 'General_Overview' or 'VisitTime_ByServerTimeWidgetName'. 35 */ 36 protected $id = ''; 37 38 /** 39 * The id of the category the subcategory belongs to, must be specified. 40 * See {@link Piwik\Widget\WidgetConfig::setCategoryId()`} or {@link Piwik\Report\getCategoryId()}. 41 * 42 * @var string A translation key eg 'General_Visits' or 'Goals_Goals' 43 */ 44 protected $categoryId = ''; 45 46 /** 47 * The name that shall be used in the menu etc, defaults to the specified {@link $id}. See {@link $id}. 48 * @var string 49 */ 50 protected $name = ''; 51 52 /** 53 * The order of the subcategory. The lower the value the earlier a widget or a report will be displayed. 54 * @var int 55 */ 56 protected $order = 99; 57 58 /** 59 * Sets (overwrites) the id of the subcategory see {@link $id}. 60 * 61 * @param string $id A translation key eg 'General_Overview'. 62 * @return static 63 */ 64 public function setId($id) 65 { 66 $this->id = $id; 67 return $this; 68 } 69 70 /** 71 * Get the id of the subcategory. 72 * @return string 73 */ 74 public function getId() 75 { 76 return $this->id; 77 } 78 79 /** 80 * Get the specified categoryId see {@link $categoryId}. 81 * 82 * @return string 83 */ 84 public function getCategoryId() 85 { 86 return $this->categoryId; 87 } 88 89 /** 90 * Sets (overwrites) the categoryId see {@link $categoryId}. 91 * 92 * @param string $categoryId 93 * @return static 94 */ 95 public function setCategoryId($categoryId) 96 { 97 $this->categoryId = $categoryId; 98 return $this; 99 } 100 101 /** 102 * Sets (overwrites) the name see {@link $name} and {@link $id}. 103 * 104 * @param string $name A translation key eg 'General_Overview'. 105 * @return static 106 */ 107 public function setName($name) 108 { 109 $this->name = $name; 110 return $this; 111 } 112 113 /** 114 * Get the name of the subcategory. 115 * @return string 116 */ 117 public function getName() 118 { 119 if (!empty($this->name)) { 120 return $this->name; 121 } 122 123 return $this->id; 124 } 125 126 /** 127 * Sets (overwrites) the order see {@link $order}. 128 * 129 * @param int $order 130 * @return static 131 */ 132 public function setOrder($order) 133 { 134 $this->order = (int) $order; 135 return $this; 136 } 137 138 /** 139 * Get the order of the subcategory. 140 * @return int 141 */ 142 public function getOrder() 143 { 144 return $this->order; 145 } 146 147 /** 148 * Get the help text (if any) for this category. 149 * @return null 150 */ 151 public function getHelp() 152 { 153 return null; 154 } 155} 156