refs #5192 some more menu api tweaks. MenuReporting is not 100% good since it...

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

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)

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.
      *

core/Menu/MenuUser.php

@@ -31,6 +31,32 @@ namespace Piwik\Menu;
 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.
      *

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)

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);
         }
     }
 

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'));
     }
 }

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);
     }
 }

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);
     }
 }

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);
     }
 
 

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)

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);
     }
 }

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
         );

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'));
     }
 }

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);
     }
 }

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'));
     }
 }

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);
     }
 }

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);
     }
 }

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);
     }
 }

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);
     }
 
 }