refs #6140 easier way to define URLs for menu items and introducing a method to addItem without boolean parameter

2 files changed, 116 insertions, 3 deletions

diff --git a/core/Menu/MenuAbstract.php b/core/Menu/MenuAbstract.php
index 2ccf6fda28..1fe1152c98 100644
--- a/core/Menu/MenuAbstract.php
+++ b/core/Menu/MenuAbstract.php
@@ -77,16 +77,32 @@ abstract class MenuAbstract extends Singleton
      *                                         current user. If false, the entry will not be added.
      * @param int $order The order hint.
      * @param bool|string $tooltip An optional tooltip to display or false to display the tooltip.
-     * @api
+     *
+     * @deprecated since 2.7.0 Use {@link addItem() instead}. Method will be removed in Piwik 3.0
      */
     public function add($menuName, $subMenuName, $url, $displayedForCurrentUser = true, $order = 50, $tooltip = false)
     {
         if (!$displayedForCurrentUser) {
-            // TODO this parameter should be removed and instead menu items should be only added if it is supposed to be
-            // displayed. Won't do it now to stay backward compatible. For Piwik 3.0 we should do it.
             return;
         }
 
+        $this->addItem($menuName, $subMenuName, $url, $order, $tooltip);
+    }
+
+    /**
+     * Adds a new entry to the menu.
+     *
+     * @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 int $order The order hint.
+     * @param bool|string $tooltip An optional tooltip to display or false to display the tooltip.
+     * @since 2.7.0
+     * @api
+     */
+    public function addItem($menuName, $subMenuName, $url, $order = 50, $tooltip = false)
+    {
         // make sure the idSite value used is numeric (hack-y fix for #3426)
         if (!is_numeric(Common::getRequestVar('idSite', false))) {
             $idSites = API::getInstance()->getSitesIdWithAtLeastViewAccess();
diff --git a/core/Plugin/Menu.php b/core/Plugin/Menu.php
index 9f7240b1f3..b6892a79f2 100644
--- a/core/Plugin/Menu.php
+++ b/core/Plugin/Menu.php
@@ -12,6 +12,7 @@ use Piwik\Menu\MenuAdmin;
 use Piwik\Menu\MenuReporting;
 use Piwik\Menu\MenuTop;
 use Piwik\Menu\MenuUser;
+use Piwik\Plugin\Manager as PluginManager;
 
 /**
  * Base class of all plugin menu providers. Plugins that define their own menu items can extend this class to easily
@@ -27,6 +28,102 @@ use Piwik\Menu\MenuUser;
  */
 class Menu
 {
+    protected $module = '';
+
+    /**
+     * @ignore
+     */
+    public function __construct()
+    {
+        $this->module = $this->getModule();
+    }
+
+    private function getModule()
+    {
+        $className = get_class($this);
+        $className = explode('\\', $className);
+
+        return $className[2];
+    }
+
+    /**
+     * Generates a URL for the default action of the plugin controller.
+     *
+     * Example:
+     * ```
+     * $menu->addItem('UI Framework', '', $this->urlForDefaultAction(), $orderId = 30);
+     * // will add a menu item that leads to the default action of the plugin controller when a user clicks on it.
+     * // The default action is usually the `index` action - meaning the `index()` method the controller -
+     * // but the default action can be customized within a controller
+     * ```
+     *
+     * @param  array $additionalParams  Optional URL parameters that will be appended to the URL
+     * @return array
+     *
+     * @since 2.7.0
+     * @api
+     */
+    protected function urlForDefaultAction($additionalParams = array())
+    {
+        $params = (array) $additionalParams;
+        $params['action'] = '';
+        $params['module'] = $this->module;
+
+        return $params;
+    }
+
+    /**
+     * Generates a URL for the given action. In your plugin controller you have to create a method with the same name
+     * as this method will be executed when a user clicks on the menu item. If you want to generate a URL for the
+     * action of another module, meaning not your plugin, you should use the method {@link urlForModuleAction()}.
+     *
+     * @param  string $controllerAction  The name of the action that should be executed within your controller
+     * @param  array  $additionalParams  Optional URL parameters that will be appended to the URL
+     * @return array
+     *
+     * @since 2.7.0
+     * @api
+     */
+    protected function urlForAction($controllerAction, $additionalParams = array())
+    {
+        $params = (array) $additionalParams;
+        $params['action'] = $controllerAction;
+        $params['module'] = $this->module;
+
+        return $params;
+    }
+
+    /**
+     * Generates a URL for the given action of the given module. We usually do not recommend to use this method as you
+     * should make sure the method of that module actually exists. If the plugin owner of that module changes the method
+     * in a future version your link might no longer work. If you want to link to an action of your controller use the
+     * method {@link urlForAction()}. Note: We will generate a link only if the given module is installed and activated.
+     *
+     * @param  string $module            The name of the module/plugin the action belongs to. The module name is case sensitive.
+     * @param  string $controllerAction  The name of the action that should be executed within your controller
+     * @param  array  $additionalParams  Optional URL parameters that will be appended to the URL
+     * @return array|null   Returns null if the given module is either not installed or not activated. Returns the URL
+     *                      to the given module action otherwise.
+     *
+     * @since 2.7.0
+     * // not API for now
+     */
+    protected function urlForModuleAction($module, $controllerAction, $additionalParams = array())
+    {
+        $pluginManager = PluginManager::getInstance();
+
+        if (!$pluginManager->isPluginLoaded($module) ||
+            !$pluginManager->isPluginActivated($module)) {
+            return null;
+        }
+
+        $params = (array) $additionalParams;
+        $params['action'] = $controllerAction;
+        $params['module'] = $module;
+
+        return $params;
+    }
+
     /**
      * Configures the reporting menu which should only contain links to reports of a specific site such as
      * "Search Engines", "Page Titles" or "Locations & Provider".