From c70f21f0877ef1ae1df73637c200682f6b68fbd2 Mon Sep 17 00:00:00 2001 From: diosmosis Date: Wed, 23 Oct 2013 07:01:41 -0400 Subject: Refs #4200, document core/Menu/*.php and core/Period/Range.php and remove Range::removePeriod and replace w/ Date::addPeriod. --- core/Menu/MenuAbstract.php | 23 ++++++++++++++++------- core/Menu/MenuAdmin.php | 34 ++++++++++++++++++++++++++-------- core/Menu/MenuMain.php | 23 ++++++++++++++++++++--- core/Menu/MenuTop.php | 41 +++++++++++++++++++++++++++++++---------- 4 files changed, 93 insertions(+), 28 deletions(-) (limited to 'core/Menu') diff --git a/core/Menu/MenuAbstract.php b/core/Menu/MenuAbstract.php index c141e617bb..e5293d5733 100644 --- a/core/Menu/MenuAbstract.php +++ b/core/Menu/MenuAbstract.php @@ -15,6 +15,12 @@ use Piwik\Plugins\SitesManager\API; use Piwik\Singleton; /** + * Base class for classes that manage one of Piwik's menus. + * + * There are three menus in Piwik, the main menu, the top menu and the admin menu. + * Each menu has a class that manages the rendering of it. Each class invokes + * a different event to allow plugins to add new menu items. + * * @package Piwik_Menu * @static \Piwik\Menu\MenuAbstract getInstance() */ @@ -45,12 +51,15 @@ abstract class MenuAbstract extends Singleton /** * Adds a new entry to the menu. * - * @param string $menuName - * @param string $subMenuName - * @param string $url - * @param bool $displayedForCurrentUser - * @param int $order - * @param bool|string $tooltip Tooltip to display. + * @param string $menuName The menu's category name. Can be a translation token. + * @param string $subMenuName The menu item's name. Can be a translation token. + * @param string|array $url The URL the admin menu entry should link to, or an array of query parameters + * that can be used to build the URL. + * @param boolean $displayedForCurrentUser Whether this menu entry should be displayed for the + * current user. If false, the entry will not be added. + * @param int $order The order hint. + * @param false|string $tooltip An optional tooltip to display. + * @api */ public function add($menuName, $subMenuName, $url, $displayedForCurrentUser = true, $order = 50, $tooltip = false) { @@ -224,4 +233,4 @@ abstract class MenuAbstract extends Singleton } return ($itemOne['_order'] < $itemTwo['_order']) ? -1 : 1; } -} +} \ No newline at end of file diff --git a/core/Menu/MenuAdmin.php b/core/Menu/MenuAdmin.php index eb3576d37e..eedd155b11 100644 --- a/core/Menu/MenuAdmin.php +++ b/core/Menu/MenuAdmin.php @@ -13,17 +13,36 @@ namespace Piwik\Menu; use Piwik\Piwik; /** + * Contains menu entries for the Admin menu. Plugins can subscribe to the + * [Menu.Admin.addItems](#) event to add new pages to the admin menu. + * + * **Example** + * + * // add a new page in an observer to Menu.Admin.addItems + * public function addAdminMenuItem() + * { + * MenuAdmin::getInstance()->add( + * 'MyPlugin_MyTranslatedAdminMenuCategory', + * 'MyPlugin_MyTranslatedAdminPageName', + * array('module' => 'MyPlugin', 'action' => 'index'), + * Piwik::isUserHasSomeAdminAccess(), + * $order = 2 + * ); + * } + * * @package Piwik_Menu */ class MenuAdmin extends MenuAbstract { /** - * Adds a new AdminMenu entry. + * Adds a new AdminMenu entry under the 'Settings' category. * - * @param string $adminMenuName - * @param string $url - * @param boolean $displayedForCurrentUser - * @param int $order + * @param string $adminMenuName The name of the admin menu entry. Can be a translation token. + * @param string|array $url The URL the admin menu entry should link to, or an array of query parameters + * that can be used to build the URL. + * @param boolean $displayedForCurrentUser Whether this menu entry should be displayed for the + * current user. If false, the entry will not be added. + * @param int $order The order hint. * @api */ public static function addEntry($adminMenuName, $url, $displayedForCurrentUser = true, $order = 20) @@ -70,7 +89,7 @@ class MenuAdmin extends MenuAbstract * * @return boolean */ - function getCurrentAdminMenuName() + public function getCurrentAdminMenuName() { $menu = MenuAdmin::getInstance()->getMenu(); $currentModule = Piwik::getModule(); @@ -87,5 +106,4 @@ class MenuAdmin extends MenuAbstract } return false; } -} - +} \ No newline at end of file diff --git a/core/Menu/MenuMain.php b/core/Menu/MenuMain.php index 4146559fcd..490eaece4c 100644 --- a/core/Menu/MenuMain.php +++ b/core/Menu/MenuMain.php @@ -11,9 +11,27 @@ namespace Piwik\Menu; use Piwik\Piwik; - /** + * Contains menu entries for the Main menu (the menu displayed under the Piwik logo). + * Plugins can subscribe to the [Menu.Reporting.addItems](#) event to add new pages to + * the main menu. + * + * **Example** + * + * // add a new page in an observer to Menu.Admin.addItems + * public function addMainMenuItem() + * { + * MenuMain::getInstance()->add( + * 'MyPlugin_MyTranslatedMenuCategory', + * 'MyPlugin_MyTranslatedMenuName', + * array('module' => 'MyPlugin', 'action' => 'index'), + * Piwik::isUserHasSomeAdminAccess(), + * $order = 2 + * ); + * } + * * @package Piwik_Menu + * @api */ class MenuMain extends MenuAbstract { @@ -71,5 +89,4 @@ class MenuMain extends MenuAbstract } return parent::getMenu(); } -} - +} \ No newline at end of file diff --git a/core/Menu/MenuTop.php b/core/Menu/MenuTop.php index ab2d312799..376985823e 100644 --- a/core/Menu/MenuTop.php +++ b/core/Menu/MenuTop.php @@ -13,6 +13,24 @@ use Piwik\Piwik; /** + * Contains menu entries for the Top menu (the menu at the very top of the page). + * Plugins can subscribe to the [Menu.Top.addItems](#) event to add new pages to + * the top menu. + * + * **Example** + * + * // add a new page in an observer to Menu.Admin.addItems + * public function addTopMenuItem() + * { + * MenuTop::getInstance()->add( + * 'MyPlugin_MyTranslatedMenuCategory', + * 'MyPlugin_MyTranslatedMenuName', + * array('module' => 'MyPlugin', 'action' => 'index'), + * Piwik::isUserHasSomeAdminAccess(), + * $order = 2 + * ); + * } + * * @package Piwik_Menu */ class MenuTop extends MenuAbstract @@ -20,20 +38,23 @@ class MenuTop extends MenuAbstract /** * Adds a new entry to the TopMenu. * - * @param string $topMenuName - * @param string $data - * @param boolean $displayedForCurrentUser - * @param int $order - * @param bool $isHTML - * @param bool|string $tooltip Tooltip to display. + * @param string $topMenuName The menu item name. Can be a translation token. + * @param string|array $url The URL the admin menu entry should link to, or an array of query parameters + * that can be used to build the URL. If `$isHTML` is true, this can be a string with + * HTML that is simply embedded. + * @param boolean $displayedForCurrentUser Whether this menu entry should be displayed for the + * current user. If false, the entry will not be added. + * @param int $order The order hint. + * @param bool $isHTML Whether `$url` is an HTML string or a URL that will be rendered as a link. + * @param bool|string $tooltip Optional tooltip to display. * @api */ - public static function addEntry($topMenuName, $data, $displayedForCurrentUser = true, $order = 10, $isHTML = false, $tooltip = false) + public static function addEntry($topMenuName, $url, $displayedForCurrentUser = true, $order = 10, $isHTML = false, $tooltip = false) { if ($isHTML) { - MenuTop::getInstance()->addHtml($topMenuName, $data, $displayedForCurrentUser, $order, $tooltip); + MenuTop::getInstance()->addHtml($topMenuName, $url, $displayedForCurrentUser, $order, $tooltip); } else { - MenuTop::getInstance()->add($topMenuName, null, $data, $displayedForCurrentUser, $order, $tooltip); + MenuTop::getInstance()->add($topMenuName, null, $url, $displayedForCurrentUser, $order, $tooltip); } } @@ -92,4 +113,4 @@ class MenuTop extends MenuAbstract } return parent::getMenu(); } -} +} \ No newline at end of file -- cgit v1.2.3