added missing widgets PHPdoc, fix a bug in widget generator where namespace was not generated correct, generate a translation key for widget category in case user has not chosen an existing one, added an example to template that demonstrates how to remove a widget

3 files changed, 65 insertions, 16 deletions

diff --git a/core/Plugin/Widgets.php b/core/Plugin/Widgets.php
index ef8b059b77..3199e7a80b 100644
--- a/core/Plugin/Widgets.php
+++ b/core/Plugin/Widgets.php
@@ -14,9 +14,9 @@ use Piwik\WidgetsList;
 
 /**
  * Base class of all plugin widget providers. Plugins that define their own widgets can extend this class to easily
- * add new widgets, to remove or to rename existing items.
+ * add new widgets or to remove widgets defined by other plugins.
  *
- * For an example, see the {@link https://github.com/piwik/piwik/blob/master/plugins/ExampleRssWidget/Widget.php} plugin.
+ * For an example, see the {@link https://github.com/piwik/piwik/blob/master/plugins/ExamplePlugin/Widgets.php} plugin.
  *
  * @api
  */
@@ -27,11 +27,17 @@ class Widgets
 
     private $module = '';
 
+    /**
+     * @ignore
+     */
     public function __construct()
     {
         $this->module = $this->getModule();
     }
 
+    /**
+     * @ignore
+     */
     public function getCategory()
     {
         return $this->category;
@@ -46,16 +52,23 @@ class Widgets
     }
 
     /**
+     * Adds a widget. You can add a widget by calling this method and passing the name of the widget as well as a method
+     * name that will be executed to render the widget. The method can be defined either directly here in this widget
+     * class or in the controller in case you want to reuse the same action for instance in the menu etc.
      * @api
      */
     protected function addWidget($name, $method, $parameters = array())
     {
-        // to be developer friendly we could check whether such a method exists (in controller or widget) and if
-        // not throw an exception so the developer does not have to handle with typos etc. I do not want to do this
-        // right now because of performance but if we add a development setting in config we could do such check
         $this->addWidgetWithCustomCategory($this->category, $name, $method, $parameters);
     }
 
+    /**
+     * Adds a widget with a custom category. By default all widgets that you define in your class will be added under
+     * the same category which is defined in the {@link $category} property. Sometimes you may have a widget that
+     * belongs to a different category where this method comes handy. It does the same as {@link addWidget()} but
+     * allows you to define the category name as well.
+     * @api
+     */
     protected function addWidgetWithCustomCategory($category, $name, $method, $parameters = array())
     {
         $this->checkIsValidWidget($name, $method);
@@ -68,12 +81,17 @@ class Widgets
     }
 
     /**
+     * Here you can add one or multiple widgets. To do so call the method {@link addWidget()} or
+     * {@link addWidgetWithCustomCategory()}.
      * @api
      */
     protected function init()
     {
     }
 
+    /**
+     * @ignore
+     */
     public function getWidgets()
     {
         $this->widgets = array();
@@ -84,7 +102,12 @@ class Widgets
     }
 
     /**
-     * Configures the widgets. Here you can for instance remove widgets.
+     * Allows you to configure previously added widgets.
+     * For instance you can remove any widgets defined by any plugin by calling the
+     * {@link \Piwik\WidgetsList::remove()} method.
+     *
+     * @param WidgetsList $widgetsList
+     * @api
      */
     public function configureWidgetsList(WidgetsList $widgetsList)
     {
@@ -93,12 +116,16 @@ class Widgets
 
     /**
      * @return \Piwik\Plugin\Widgets[]
+     * @ignore
      */
     public static function getAllWidgets()
     {
         return PluginManager::getInstance()->findComponents('Widgets', 'Piwik\\Plugin\\Widgets');
     }
 
+    /**
+     * @ignore
+     */
     public static function factory($module, $action)
     {
         if (empty($module) || empty($action)) {
diff --git a/plugins/CoreConsole/Commands/GenerateWidget.php b/plugins/CoreConsole/Commands/GenerateWidget.php
index 53552e6844..31468921ad 100644
--- a/plugins/CoreConsole/Commands/GenerateWidget.php
+++ b/plugins/CoreConsole/Commands/GenerateWidget.php
@@ -33,6 +33,11 @@ class GenerateWidget extends GeneratePluginBase
         $pluginName = $this->getPluginName($input, $output);
         $category   = $this->getCategory($input, $output);
 
+        if ($category === Piwik::translate($category)) {
+            // no translation found...
+            $category = $this->makeTranslationIfPossible($pluginName, $category);
+        }
+
         $exampleFolder  = PIWIK_INCLUDE_PATH . '/plugins/ExamplePlugin';
         $replace        = array('ExamplePlugin'    => $pluginName,
                                 'Example Category' => $category);
@@ -47,6 +52,19 @@ class GenerateWidget extends GeneratePluginBase
         ));
     }
 
+    protected function getExistingCategories()
+    {
+        $categories = array();
+        foreach (Widgets::getAllWidgets() as $widget) {
+            if ($widget->getCategory()) {
+                $categories[] = Piwik::translate($widget->getCategory());
+            }
+        }
+        $categories = array_values(array_unique($categories));
+
+        return $categories;
+    }
+
     /**
      * @param InputInterface $input
      * @param OutputInterface $output
@@ -63,15 +81,8 @@ class GenerateWidget extends GeneratePluginBase
             return $category;
         };
 
-        $category = $input->getOption('category');
-
-        $categories = array();
-        foreach (Widgets::getAllWidgets() as $widget) {
-            if ($widget->getCategory()) {
-                $categories[] = Piwik::translate($widget->getCategory());
-            }
-        }
-        $categories = array_values(array_unique($categories));
+        $category   = $input->getOption('category');
+        $categories = $this->getExistingCategories();
 
         if (empty($category)) {
             $dialog = $this->getHelperSet()->get('dialog');
diff --git a/plugins/ExamplePlugin/Widgets.php b/plugins/ExamplePlugin/Widgets.php
index 2d0e607fa8..82a4446c3f 100644
--- a/plugins/ExamplePlugin/Widgets.php
+++ b/plugins/ExamplePlugin/Widgets.php
@@ -9,6 +9,7 @@
 namespace Piwik\Plugins\ExamplePlugin;
 
 use Piwik\View;
+use Piwik\WidgetsList;
 
 /**
  * This class allows you to add your own widgets to the Piwik platform. In case you want to remove widgets from another
@@ -26,7 +27,7 @@ class Widgets extends \Piwik\Plugin\Widgets
     protected $category = 'Example Category';
 
     /**
-     * Here you can add one or multiple widgets. You can add a widget by calling the method "addWidget" and pass the
+     * Here you can add one or multiple widgets. You can add a widget by calling the method "addWidget()" and pass the
      * name of the widget as well as a method name that should be called to render the widget. The method can be
      * defined either directly here in this widget class or in the controller in case you want to reuse the same action
      * for instance in the menu etc.
@@ -53,4 +54,14 @@ class Widgets extends \Piwik\Plugin\Widgets
         return 'My Widget Text';
     }
 
+    /**
+     * Here you can remove any widgets defined by any plugin.
+     *
+     * @param WidgetsList $widgetsList
+     */
+    public function configureWidgetsList(WidgetsList $widgetsList)
+    {
+        // $widgetsList->remove('NameOfWidgetCategory'); // will remove all widgets having this category
+        // $widgetsList->remove('NameOfWidgetCategory', 'Widget name'); // will only remove a specific widget
+    }
 }