refs #5192 some more menu api tweaks. MenuReporting is not 100% good since it is in core and should not know whether are actions, referrers and visitors item but it is very convenient for developers. Once we have DI we could add those methods there

19 files changed, 114 insertions, 49 deletions

diff --git a/core/Menu/MenuAdmin.php b/core/Menu/MenuAdmin.php
index ad4c6c4108..7aa358c206 100644
--- a/core/Menu/MenuAdmin.php
+++ b/core/Menu/MenuAdmin.php
@@ -49,11 +49,11 @@ class MenuAdmin extends MenuAbstract
     }
 
     /**
-     * See {@link add()}. Adds a new menu item to the development section.
+     * See {@link add()}. Adds a new menu item to the development section of the admin menu.
      * @param string $menuName
      * @param array $url
      * @param int $order
-     * @param bool $tooltip
+     * @param bool|string $tooltip
      * @api
      */
     public function addDevelopmentItem($menuName, $url, $order = 50, $tooltip = false)
@@ -62,11 +62,11 @@ class MenuAdmin extends MenuAbstract
     }
 
     /**
-     * See {@link add()}. Adds a new menu item to the development section.
+     * See {@link add()}. Adds a new menu item to the diagnostic section of the admin menu.
      * @param string $menuName
      * @param array $url
      * @param int $order
-     * @param bool $tooltip
+     * @param bool|string $tooltip
      * @api
      */
     public function addDiagnosticItem($menuName, $url, $order = 50, $tooltip = false)
@@ -75,11 +75,11 @@ class MenuAdmin extends MenuAbstract
     }
 
     /**
-     * See {@link add()}. Adds a new menu item to the development section.
+     * See {@link add()}. Adds a new menu item to the platform section of the admin menu.
      * @param string $menuName
      * @param array $url
      * @param int $order
-     * @param bool $tooltip
+     * @param bool|string $tooltip
      * @api
      */
     public function addPlatformItem($menuName, $url, $order = 50, $tooltip = false)
@@ -88,11 +88,11 @@ class MenuAdmin extends MenuAbstract
     }
 
     /**
-     * See {@link add()}. Adds a new menu item to the development section.
+     * See {@link add()}. Adds a new menu item to the settings section of the admin menu.
      * @param string $menuName
      * @param array $url
      * @param int $order
-     * @param bool $tooltip
+     * @param bool|string $tooltip
      * @api
      */
     public function addSettingsItem($menuName, $url, $order = 50, $tooltip = false)
@@ -101,11 +101,11 @@ class MenuAdmin extends MenuAbstract
     }
 
     /**
-     * See {@link add()}. Adds a new menu item to the development section.
+     * See {@link add()}. Adds a new menu item to the manage section of the admin menu.
      * @param string $menuName
      * @param array $url
      * @param int $order
-     * @param bool $tooltip
+     * @param bool|string $tooltip
      * @api
      */
     public function addManageItem($menuName, $url, $order = 50, $tooltip = false)
diff --git a/core/Menu/MenuReporting.php b/core/Menu/MenuReporting.php
index c5a3c1da1e..bb47815305 100644
--- a/core/Menu/MenuReporting.php
+++ b/core/Menu/MenuReporting.php
@@ -33,6 +33,46 @@ use Piwik\Plugin\Report;
  */
 class MenuReporting extends MenuAbstract
 {
+
+    /**
+     * See {@link add()}. Adds a new menu item to the visitors section of the reporting menu.
+     * @param string $menuName
+     * @param array $url
+     * @param int $order
+     * @param bool|string $tooltip
+     * @api
+     */
+    public function addVisitorsItem($menuName, $url, $order = 50, $tooltip = false)
+    {
+        $this->add('General_Visitors', $menuName, $url, true, $order, $tooltip);
+    }
+
+    /**
+     * See {@link add()}. Adds a new menu item to the actions section of the reporting menu.
+     * @param string $menuName
+     * @param array $url
+     * @param int $order
+     * @param bool|string $tooltip
+     * @api
+     */
+    public function addActionsItem($menuName, $url, $order = 50, $tooltip = false)
+    {
+        $this->add('General_Actions', $menuName, $url, true, $order, $tooltip);
+    }
+
+    /**
+     * See {@link add()}. Adds a new menu item to the referrers section of the reporting menu.
+     * @param string $menuName
+     * @param array $url
+     * @param int $order
+     * @param bool|string $tooltip
+     * @api
+     */
+    public function addReferrersItem($menuName, $url, $order = 50, $tooltip = false)
+    {
+        $this->add('Referrers_Referrers', $menuName, $url, true, $order, $tooltip);
+    }
+
     /**
      * Returns if the URL was found in the menu.
      *
diff --git a/core/Menu/MenuUser.php b/core/Menu/MenuUser.php
index 318e8b3f0f..a174f8692b 100755
--- a/core/Menu/MenuUser.php
+++ b/core/Menu/MenuUser.php
@@ -32,6 +32,32 @@ class MenuUser extends MenuAbstract
 {
 
     /**
+     * See {@link add()}. Adds a new menu item to the manage section of the user menu.
+     * @param string $menuName
+     * @param array $url
+     * @param int $order
+     * @param bool|string $tooltip
+     * @api
+     */
+    public function addManageItem($menuName, $url, $order = 50, $tooltip = false)
+    {
+        $this->add('CoreAdminHome_MenuManage', $menuName, $url, true, $order, $tooltip);
+    }
+
+    /**
+     * See {@link add()}. Adds a new menu item to the platform section of the user menu.
+     * @param string $menuName
+     * @param array $url
+     * @param int $order
+     * @param bool|string $tooltip
+     * @api
+     */
+    public function addPlatformItem($menuName, $url, $order = 50, $tooltip = false)
+    {
+        $this->add('CorePluginsAdmin_MenuPlatform', $menuName, $url, true, $order, $tooltip);
+    }
+
+    /**
      * Triggers the Menu.User.addItems hook and returns the menu.
      *
      * @return Array
diff --git a/plugins/API/Menu.php b/plugins/API/Menu.php
index 330fdd2519..0020ecf1c4 100644
--- a/plugins/API/Menu.php
+++ b/plugins/API/Menu.php
@@ -29,7 +29,7 @@ class Menu extends \Piwik\Plugin\Menu
         $apiUrlParams = array('module' => 'API', 'action' => 'listAllAPI', 'segment' => false);
         $tooltip      = Piwik::translate('API_TopLinkTooltip');
 
-        $menu->add('CorePluginsAdmin_MenuPlatform', 'General_API', $apiUrlParams, true, 6, $tooltip);
+        $menu->addPlatformItem('General_API', $apiUrlParams, 6, $tooltip);
     }
 
     private function addTopMenuMobileApp(MenuTop $menu)
diff --git a/plugins/Actions/Menu.php b/plugins/Actions/Menu.php
index 3e8a113bb2..8804fabe0d 100644
--- a/plugins/Actions/Menu.php
+++ b/plugins/Actions/Menu.php
@@ -19,11 +19,11 @@ class Menu extends \Piwik\Plugin\Menu
             'action' => 'menuGetPageUrls'
         );
 
-        $menu->add('General_Actions', '', $urlParams, true, 15);
+        $menu->addActionsItem('', $urlParams, 15);
 
         $actions = new Actions();
         if ($actions->isSiteSearchEnabled()) {
-            $menu->add('General_Actions', 'Actions_SubmenuSitesearch', array('module' => 'Actions', 'action' => 'indexSiteSearch'), true, 5);
+            $menu->addActionsItem('Actions_SubmenuSitesearch', array('module' => 'Actions', 'action' => 'indexSiteSearch'), 5);
         }
     }
 
diff --git a/plugins/DevicesDetection/Menu.php b/plugins/DevicesDetection/Menu.php
index b956942d52..e37c62e75f 100644
--- a/plugins/DevicesDetection/Menu.php
+++ b/plugins/DevicesDetection/Menu.php
@@ -27,6 +27,6 @@ class Menu extends \Piwik\Plugin\Menu
 
     public function configureReportingMenu(MenuReporting $menu)
     {
-        $menu->add('General_Visitors', 'DevicesDetection_submenu', array('module' => 'DevicesDetection', 'action' => 'index'));
+        $menu->addVisitorsItem('DevicesDetection_submenu', array('module' => 'DevicesDetection', 'action' => 'index'));
     }
 }
diff --git a/plugins/Events/Menu.php b/plugins/Events/Menu.php
index df171dc488..01c60cabe6 100644
--- a/plugins/Events/Menu.php
+++ b/plugins/Events/Menu.php
@@ -16,6 +16,6 @@ class Menu extends \Piwik\Plugin\Menu
 {
     public function configureReportingMenu(MenuReporting $menu)
     {
-        $menu->add('General_Actions', 'Events_Events', array('module' => 'Events', 'action' => 'index'), true, 30);
+        $menu->addActionsItem('Events_Events', array('module' => 'Events', 'action' => 'index'), 30);
     }
 }
diff --git a/plugins/ExamplePlugin/Menu.php b/plugins/ExamplePlugin/Menu.php
index 1a4ed8300f..2a3ed266f2 100644
--- a/plugins/ExamplePlugin/Menu.php
+++ b/plugins/ExamplePlugin/Menu.php
@@ -22,19 +22,21 @@ class Menu extends \Piwik\Plugin\Menu
 {
     public function configureReportingMenu(MenuReporting $menu)
     {
+        // with custom category 'UI Framework'
         // $menu->add('UI Framework', '', array('module' => 'ExamplePlugin', 'action' => ''), true, $orderId = 30);
         // $menu->add('UI Framework', 'Report 1', array('module' => 'ExamplePlugin', 'action' => 'report1'), true, $orderId = 30);
+        // or reusing an existing category
+        // $menu->addVisitorsItem('Report 1', array('module' => 'ExamplePlugin', 'action' => 'report1'), $orderId = 30);
+        // $menu->addActionsItem('Report 1', array('module' => 'ExamplePlugin', 'action' => 'report1'), $orderId = 30);
     }
 
     public function configureAdminMenu(MenuAdmin $menu)
     {
+        // with custom category
         // $menu->add('General_Settings', 'My Admin Item', array('module' => 'ExamplePlugin', 'action' => ''), true, $orderId = 30);
-        // or
+        // or reusing an existing category
         // $menu->addSettingsItem('My Admin Item', array('module' => 'ExamplePlugin', 'action' => ''), $orderId = 30);
-        // $menu->addManageItem('My Admin Item', array('module' => 'ExamplePlugin', 'action' => ''), $orderId = 30);
         // $menu->addPlatformItem('My Admin Item', array('module' => 'ExamplePlugin', 'action' => ''), $orderId = 30);
-        // $menu->addDiagnosticItem('My Admin Item', array('module' => 'ExamplePlugin', 'action' => ''), $orderId = 30);
-        // $menu->addDevelopmentItem('My Admin Item', array('module' => 'ExamplePlugin', 'action' => ''), $orderId = 30);
     }
 
     public function configureTopMenu(MenuTop $menu)
@@ -44,6 +46,10 @@ class Menu extends \Piwik\Plugin\Menu
 
     public function configureUserMenu(MenuUser $menu)
     {
+        // with custom category
         // $menu->add('CoreAdminHome_MenuManage', 'My User Item', array('module' => 'ExamplePlugin', 'action' => ''), true, $orderId = 30);
+        // or reusing an existing category
+        // $menu->addManageItem('My User Item', array('module' => 'ExamplePlugin', 'action' => ''), $orderId = 30);
+        // $menu->addPlatformItem('My User Item', array('module' => 'ExamplePlugin', 'action' => ''), $orderId = 30);
     }
 }
diff --git a/plugins/ExampleUI/Menu.php b/plugins/ExampleUI/Menu.php
index 8714c3eddc..06c4bccf8e 100644
--- a/plugins/ExampleUI/Menu.php
+++ b/plugins/ExampleUI/Menu.php
@@ -36,7 +36,7 @@ class Menu extends \Piwik\Plugin\Menu
     public function configureUserMenu(MenuUser $menu)
     {
         $urlParams = array('module' => 'ExampleUI', 'action' => 'notifications');
-        $menu->add('CorePluginsAdmin_MenuPlatform', 'UI Notifications', $urlParams, $displayedForCurrentUser = true, $order = 3);
+        $menu->addPlatformItem('UI Notifications', $urlParams, $order = 3);
     }
 
 
diff --git a/plugins/Live/Reports/GetLastVisitsDetails.php b/plugins/Live/Reports/GetLastVisitsDetails.php
index 24ef81d617..9c2b4373e3 100644
--- a/plugins/Live/Reports/GetLastVisitsDetails.php
+++ b/plugins/Live/Reports/GetLastVisitsDetails.php
@@ -29,9 +29,10 @@ class GetLastVisitsDetails extends Base
 
     public function configureReportingMenu(MenuReporting $menu)
     {
-        $url = array('module' => $this->module, 'action' => 'indexVisitorLog');
-
-        $menu->add('General_Visitors', $this->widgetTitle, $url, $this->isEnabled(), $order = 5);
+        if ($this->isEnabled()) {
+            $url = array('module' => $this->module, 'action' => 'indexVisitorLog');
+            $menu->addVisitorsItem($this->widgetTitle, $url, $order = 5);
+        }
     }
 
     public function configureWidget(WidgetsList $widget)
diff --git a/plugins/Referrers/Menu.php b/plugins/Referrers/Menu.php
index fc7aaf5820..60768d7c2f 100644
--- a/plugins/Referrers/Menu.php
+++ b/plugins/Referrers/Menu.php
@@ -14,9 +14,9 @@ class Menu extends \Piwik\Plugin\Menu
 {
     public function configureReportingMenu(MenuReporting $menu)
     {
-        $menu->add('Referrers_Referrers', '', array('module' => 'Referrers', 'action' => 'index'), true, 20);
-        $menu->add('Referrers_Referrers', 'General_Overview', array('module' => 'Referrers', 'action' => 'index'), true, 1);
-        $menu->add('Referrers_Referrers', 'Referrers_SubmenuSearchEngines', array('module' => 'Referrers', 'action' => 'getSearchEnginesAndKeywords'), true, 2);
-        $menu->add('Referrers_Referrers', 'Referrers_SubmenuWebsites', array('module' => 'Referrers', 'action' => 'indexWebsites'), true, 3);
+        $menu->addReferrersItem('', array('module' => 'Referrers', 'action' => 'index'), 20);
+        $menu->addReferrersItem('General_Overview', array('module' => 'Referrers', 'action' => 'index'), 1);
+        $menu->addReferrersItem('Referrers_SubmenuSearchEngines', array('module' => 'Referrers', 'action' => 'getSearchEnginesAndKeywords'), 2);
+        $menu->addReferrersItem('Referrers_SubmenuWebsites', array('module' => 'Referrers', 'action' => 'indexWebsites'), 3);
     }
 }
diff --git a/plugins/ScheduledReports/Menu.php b/plugins/ScheduledReports/Menu.php
index afde618614..26aafad2ad 100644
--- a/plugins/ScheduledReports/Menu.php
+++ b/plugins/ScheduledReports/Menu.php
@@ -24,18 +24,10 @@ class Menu extends \Piwik\Plugin\Menu
             \Piwik\Plugin\Manager::getInstance()->isPluginActivated('MobileMessaging')
                 ? 'MobileMessaging_TopLinkTooltip' : 'ScheduledReports_TopLinkTooltip');
 
-        $menu->add(
-            'CoreAdminHome_MenuManage',
-            null,
-            array('module' => '', 'action' => '', 'segment' => false),
-            true,
-            10
-        );
-        $menu->add(
-            'CoreAdminHome_MenuManage',
+        $menu->addManageItem(null, array('module' => '', 'action' => '', 'segment' => false), 10);
+        $menu->addManageItem(
             $this->getTopMenuTranslationKey(),
             array('module' => 'ScheduledReports', 'action' => 'index', 'segment' => false),
-            true,
             13,
             $tooltip
         );
diff --git a/plugins/UserCountry/Menu.php b/plugins/UserCountry/Menu.php
index 505ae68c97..41e259a618 100644
--- a/plugins/UserCountry/Menu.php
+++ b/plugins/UserCountry/Menu.php
@@ -25,6 +25,6 @@ class Menu extends \Piwik\Plugin\Menu
 
     public function configureReportingMenu(MenuReporting $menu)
     {
-        $menu->add('General_Visitors', 'UserCountry_SubmenuLocations', array('module' => 'UserCountry', 'action' => 'index'));
+        $menu->addVisitorsItem('UserCountry_SubmenuLocations', array('module' => 'UserCountry', 'action' => 'index'));
     }
 }
diff --git a/plugins/UserCountryMap/Menu.php b/plugins/UserCountryMap/Menu.php
index fe7b979135..298eda1e17 100644
--- a/plugins/UserCountryMap/Menu.php
+++ b/plugins/UserCountryMap/Menu.php
@@ -14,7 +14,7 @@ class Menu extends \Piwik\Plugin\Menu
 {
     public function configureReportingMenu(MenuReporting $menu)
     {
-        $menu->add('General_Visitors', 'UserCountryMap_RealTimeMap',
-                   array('module' => 'UserCountryMap', 'action' => 'realtimeWorldMap'), true, $order = 70);
+        $menu->addVisitorsItem('UserCountryMap_RealTimeMap',
+                   array('module' => 'UserCountryMap', 'action' => 'realtimeWorldMap'), $order = 70);
     }
 }
diff --git a/plugins/UserSettings/Menu.php b/plugins/UserSettings/Menu.php
index 00f59f2544..5b442e5e09 100644
--- a/plugins/UserSettings/Menu.php
+++ b/plugins/UserSettings/Menu.php
@@ -14,6 +14,6 @@ class Menu extends \Piwik\Plugin\Menu
 {
     public function configureReportingMenu(MenuReporting $menu)
     {
-        $menu->add('General_Visitors', 'General_Settings', array('module' => 'UserSettings', 'action' => 'index'));
+        $menu->addVisitorsItem('General_Settings', array('module' => 'UserSettings', 'action' => 'index'));
     }
 }
diff --git a/plugins/VisitFrequency/Menu.php b/plugins/VisitFrequency/Menu.php
index ad8000bed2..8759cf751d 100644
--- a/plugins/VisitFrequency/Menu.php
+++ b/plugins/VisitFrequency/Menu.php
@@ -14,7 +14,7 @@ class Menu extends \Piwik\Plugin\Menu
 {
     public function configureReportingMenu(MenuReporting $menu)
     {
-        $menu->add('General_Visitors', 'VisitFrequency_SubmenuFrequency',
-                   array('module' => 'VisitFrequency', 'action' => 'index'), true, $order = 55);
+        $menu->addVisitorsItem('VisitFrequency_SubmenuFrequency',
+                   array('module' => 'VisitFrequency', 'action' => 'index'), $order = 55);
     }
 }
diff --git a/plugins/VisitTime/Menu.php b/plugins/VisitTime/Menu.php
index ab3dce5b55..db221a4eda 100644
--- a/plugins/VisitTime/Menu.php
+++ b/plugins/VisitTime/Menu.php
@@ -14,7 +14,7 @@ class Menu extends \Piwik\Plugin\Menu
 {
     public function configureReportingMenu(MenuReporting $menu)
     {
-        $menu->add('General_Visitors', 'VisitTime_SubmenuTimes',
-                   array('module' => 'VisitTime', 'action' => 'index'), true, $order = 65);
+        $menu->addVisitorsItem('VisitTime_SubmenuTimes',
+                   array('module' => 'VisitTime', 'action' => 'index'), $order = 65);
     }
 }
diff --git a/plugins/VisitsSummary/Menu.php b/plugins/VisitsSummary/Menu.php
index e79a338d9c..1b87e46be9 100644
--- a/plugins/VisitsSummary/Menu.php
+++ b/plugins/VisitsSummary/Menu.php
@@ -14,7 +14,7 @@ class Menu extends \Piwik\Plugin\Menu
 {
     public function configureReportingMenu(MenuReporting $menu)
     {
-        $menu->add('General_Visitors', '', array('module' => 'VisitsSummary', 'action' => 'index'), true, 10);
-        $menu->add('General_Visitors', 'General_Overview', array('module' => 'VisitsSummary', 'action' => 'index'), true, 1);
+        $menu->addVisitorsItem('', array('module' => 'VisitsSummary', 'action' => 'index'), 10);
+        $menu->addVisitorsItem('General_Overview', array('module' => 'VisitsSummary', 'action' => 'index'), 1);
     }
 }
diff --git a/plugins/Widgetize/Menu.php b/plugins/Widgetize/Menu.php
index c4db230565..954df309e5 100644
--- a/plugins/Widgetize/Menu.php
+++ b/plugins/Widgetize/Menu.php
@@ -18,8 +18,8 @@ class Menu extends \Piwik\Plugin\Menu
         $tooltip   = Piwik::translate('Widgetize_TopLinkTooltip');
         $urlParams = array('module' => 'Widgetize', 'action' => 'index', 'segment' => false);
 
-        $menu->add('CorePluginsAdmin_MenuPlatform', null, $urlParams, true, 50, $tooltip);
-        $menu->add('CorePluginsAdmin_MenuPlatform', 'General_Widgets', $urlParams, true, 5, $tooltip);
+        $menu->addPlatformItem(null, $urlParams, 50, $tooltip);
+        $menu->addPlatformItem('General_Widgets', $urlParams, 5, $tooltip);
     }
 
 }