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

1 files changed, 97 insertions, 0 deletions

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