diff options
Diffstat (limited to 'core/Category/Subcategory.php')
| -rw-r--r-- | core/Category/Subcategory.php | 146 |
1 files changed, 146 insertions, 0 deletions
diff --git a/core/Category/Subcategory.php b/core/Category/Subcategory.php new file mode 100644 index 0000000000..7b6854f95c --- /dev/null +++ b/core/Category/Subcategory.php @@ -0,0 +1,146 @@ +<?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\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; + } +}
\ No newline at end of file |