added a bit of documentation

core/Plugin/ViewDataTable.php

@@ -29,16 +29,11 @@ use Piwik\ViewDataTable\RequestConfig as VizRequest;
 
 /**
  * This class is used to load (from the API) and customize the output of a given DataTable.
- * The main() method will create an object implementing ViewInterface
- * You can customize the dataTable using the disable* methods.
  *
- * You can also customize the dataTable rendering using row metadata:
- * - 'html_label_prefix': If this metadata is present on a row, it's contents will be prepended
- *                        the label in the HTML output.
- * - 'html_label_suffix': If this metadata is present on a row, it's contents will be appended
- *                        after the label in the HTML output.
+ * You can build your own ViewDataTable by extending this class and implementing the buildView() method which defines
+ * which data should be loaded and which view should be rendered.
  *
- * Example:
+ * Example usage:
  * In the Controller of the plugin VisitorInterest
  * <pre>
  *    function getNumberOfVisitsPerVisitDuration( $fetch = false)
@@ -87,7 +82,8 @@ abstract class ViewDataTable implements ViewInterface
     protected $request;
 
     /**
-     * Default constructor.
+     * Constructor. Initializes the default config, requestConfig and the request itself. After configuring some
+     * mandatory properties reports can modify the view by listening to the hook 'ViewDataTable.configure'.
      */
     public function __construct($controllerAction, $apiMethodToRequestDataTable)
     {
@@ -137,11 +133,23 @@ abstract class ViewDataTable implements ViewInterface
         $this->overrideViewPropertiesWithQueryParams();
     }
 
+    /**
+     * Returns the default config. Custom viewDataTables can change the default config to their needs by either
+     * modifying this config or creating an own Config class that extends the default Config.
+     *
+     * @return \Piwik\ViewDataTable\Config
+     */
     public static function getDefaultConfig()
     {
         return new VizConfig();
     }
 
+    /**
+     * Returns the default request config. Custom viewDataTables can change the default config to their needs by either
+     * modifying this config or creating an own RequestConfig class that extends the default RequestConfig.
+     *
+     * @return \Piwik\ViewDataTable\RequestConfig
+     */
     public static function getDefaultRequestConfig()
     {
         return new VizRequest();
@@ -161,8 +169,8 @@ abstract class ViewDataTable implements ViewInterface
     }
 
     /**
-     * Returns the viewDataTable ID for this DataTable visualization. Derived classes
-     * should declare a const ID field with the viewDataTable ID.
+     * Returns the viewDataTable ID for this DataTable visualization. Derived classes  should declare a const ID field
+     * with the viewDataTable ID.
      *
      * @throws \Exception
      * @return string
@@ -179,6 +187,13 @@ abstract class ViewDataTable implements ViewInterface
        return $id;
     }
 
+    /**
+     * Detects whether the viewDataTable or one of its ancestors has the given id.
+     *
+     * @param  string $viewDataTableId
+     *
+     * @return bool
+     */
     public function isViewDataTableId($viewDataTableId)
     {
         $myIds = ViewDataTableManager::getIdsWithInheritance(get_called_class());
@@ -224,7 +239,7 @@ abstract class ViewDataTable implements ViewInterface
     }
 
     /**
-     * Convenience function. Calls main() & renders the view that gets built.
+     * Requests all needed data and renders the view.
      *
      * @return string The result of rendering.
      */
@@ -278,6 +293,11 @@ abstract class ViewDataTable implements ViewInterface
         return Common::getRequestVar($name, $defaultValue, $type);
     }
 
+    /**
+     * Determine if the view data table requests a single data table or not.
+     *
+     * @return bool
+     */
     public function isRequestingSingleDataTable()
     {
         $requestArray = $this->request->getRequestArray() + $_GET + $_POST;
@@ -295,6 +315,14 @@ abstract class ViewDataTable implements ViewInterface
         return true;
     }
 
+    /**
+     * Here you can define whether your visualization can display a specific data table or not. For instance you may
+     * only display your visualization in case a single data table is requested. If the method returns true, the footer
+     * icon will be displayed.
+     *
+     * @param  ViewDataTable $view
+     * @return bool
+     */
     public static function canDisplayViewDataTable(ViewDataTable $view)
     {
         return $view->config->show_all_views_icons;

core/Plugin/Visualization.php

@@ -29,11 +29,12 @@ use Piwik\Site;
 use Piwik\View;
 
 /**
- * Base class for all DataTable visualizations. Different visualizations are used to
- * handle different values of the viewDataTable query parameter. Each one will display
- * DataTable data in a different way.
+ * Base class for all DataTable visualizations. A Visualization is a special kind of ViewDataTable that comes with some
+ * handy hooks. Different visualizations are used to handle different values of the viewDataTable query parameter.
+ * Each one will display DataTable data in a different way.
  *
  * TODO: must be more in depth
+ * @api
  */
 class Visualization extends ViewDataTable
 {
@@ -52,11 +53,6 @@ class Visualization extends ViewDataTable
         parent::__construct($controllerAction, $apiMethodToRequestDataTable);
     }
 
-    protected function init()
-    {
-        // do your init stuff here, do not overwrite constructor
-    }
-
     protected function buildView()
     {
         $this->overrideSomeConfigPropertiesIfNeeded();
@@ -128,6 +124,13 @@ class Visualization extends ViewDataTable
         }
     }
 
+    /**
+     * Assigns a template variable. All assigned variables are available in the twig view template afterwards. You can
+     * assign either one variable by setting $vars and $value or an array of key/value pairs.
+     *
+     * @param array|string $vars
+     * @param mixed  $value
+     */
     public function assignTemplateVar($vars, $value = null)
     {
         if (is_string($vars)) {
@@ -390,34 +393,44 @@ class Visualization extends ViewDataTable
         return $javascriptVariablesToSet;
     }
 
-    public function beforeRender()
-    {
-        // make sure config properties have a specific value because it can be changed by a report or by request params
-        // like $this->config->showFooterColumns = true;
-    }
-
+    /**
+     * Hook that is intended to change the request config that is sent to the API.
+     */
     public function beforeLoadDataTable()
     {
-        // change request
-        // like defining $this->requestConfig->filter_column
     }
 
+    /**
+     * Hook that is executed before generic filters like "filter_limit" and "filter_offset" are applied
+     */
     public function beforeGenericFiltersAreAppliedToLoadedDataTable()
     {
 
     }
 
+    /**
+     * This hook is executed after generic filters like "filter_limit" and "filter_offset" are applied
+     */
     public function afterGenericFiltersAreAppliedToLoadedDataTable()
     {
 
     }
 
+    /**
+     * This hook is executed after the data table is loaded and after all filteres are applied.
+     * Format the data that you want to pass to the view here.
+     */
     public function afterAllFilteresAreApplied()
     {
-        // filter and format requested data here
-        // $dataTable ...
+    }
 
-        // $this->generator = new GeneratorFoo($dataTable);
+    /**
+     * Hook to make sure config properties have a specific value because the default config can be changed by a
+     * report or by request ($_GET and $_POST) params.
+     */
+    public function beforeRender()
+    {
+        // eg $this->config->showFooterColumns = true;
     }
 
     /**

core/ViewDataTable/Manager.php

@@ -116,6 +116,29 @@ class Manager
         return $result;
     }
 
+    /**
+     * This method determines the default set of footer icons to display below a report.
+     *
+     * $result has the following format:
+     *
+     * ```
+     * array(
+     *     array( // footer icon group 1
+     *         'class' => 'footerIconGroup1CssClass',
+     *         'buttons' => array(
+     *             'id' => 'myid',
+     *             'title' => 'My Tooltip',
+     *             'icon' => 'path/to/my/icon.png'
+     *         )
+     *     ),
+     *     array( // footer icon group 2
+     *         'class' => 'footerIconGroup2CssClass',
+     *         'buttons' => array(...)
+     *     ),
+     *     ...
+     * )
+     * ```
+     */
     public static function configureFooterIcons(ViewDataTable $view)
     {
         $result = array();