diff options
Diffstat (limited to 'core/Plugin/ViewDataTable.php')
| -rw-r--r-- | core/Plugin/ViewDataTable.php | 84 |
1 files changed, 42 insertions, 42 deletions
diff --git a/core/Plugin/ViewDataTable.php b/core/Plugin/ViewDataTable.php index fe603b159d..14b2f979f7 100644 --- a/core/Plugin/ViewDataTable.php +++ b/core/Plugin/ViewDataTable.php @@ -22,64 +22,64 @@ use Piwik\ViewDataTable\RequestConfig as VizRequest; /** * The base class of all report visualizations. - * + * * ViewDataTable instances load analytics data via Piwik's Reporting API and then output some * type of visualization of that data. - * + * * Visualizations can be in any format. HTML-based visualizations should extend * {@link Visualization}. Visualizations that use other formats, such as visualizations * that output an image, should extend ViewDataTable directly. * * ### Creating ViewDataTables - * + * * ViewDataTable instances are not created via the new operator, instead the {@link Piwik\ViewDataTable\Factory} * class is used. - * + * * The specific subclass to create is determined, first, by the **viewDataTable** query paramater. * If this parameter is not set, then the default visualization type for the report being * displayed is used. * * ### Configuring ViewDataTables - * + * * **Display properties** - * + * * ViewDataTable output can be customized by setting one of many available display * properties. Display properties are stored as fields in {@link Piwik\ViewDataTable\Config} objects. * ViewDataTables store a {@link Piwik\ViewDataTable\Config} object in the {@link $config} field. - * + * * Display properties can be set at any time before rendering. - * + * * **Request properties** - * + * * Request properties are similar to display properties in the way they are set. They are, * however, not used to customize ViewDataTable instances, but in the request to Piwik's * API when loading analytics data. - * + * * Request properties are set by setting the fields of a {@link Piwik\ViewDataTable\RequestConfig} object stored in * the {@link $requestConfig} field. They can be set at any time before rendering. * Setting them after data is loaded will have no effect. - * + * * **Customizing how reports are displayed** - * + * * Each individual report should be rendered in its own controller method. There are two * ways to render a report within its controller method. You can either: - * + * * 1. manually create and configure a ViewDataTable instance * 2. invoke {@link Piwik\Plugin\Controller::renderReport} and configure the ViewDataTable instance * in the {@hook ViewDataTable.configure} event. - * + * * ViewDataTable instances are configured by setting and modifying display properties and request * properties. - * + * * ### Creating new visualizations - * + * * New visualizations can be created by extending the ViewDataTable class or one of its * descendants. To learn more [read our guide on creating new visualizations](/guides/visualizing-report-data#creating-new-visualizations). - * + * * ### Examples - * + * * **Manually configuring a ViewDataTable** - * + * * // a controller method that displays a single report * public function myReport() * { @@ -89,18 +89,18 @@ use Piwik\ViewDataTable\RequestConfig as VizRequest; * // ... * return $view->render(); * } - * + * * **Using {@link Piwik\Plugin\Controller::renderReport}** - * + * * First, a controller method that displays a single report: - * + * * public function myReport() * { * return $this->renderReport(__FUNCTION__);` * } - * + * * Then the event handler for the {@hook ViewDataTable.configure} event: - * + * * public function configureViewDataTable(ViewDataTable $view) * { * switch ($view->requestConfig->apiMethodToRequestDataTable) { @@ -111,32 +111,32 @@ use Piwik\ViewDataTable\RequestConfig as VizRequest; * break; * } * } - * + * * **Using custom configuration objects in a new visualization** - * + * * class MyVisualizationConfig extends Piwik\ViewDataTable\Config * { * public $my_new_property = true; * } - * + * * class MyVisualizationRequestConfig extends Piwik\ViewDataTable\RequestConfig * { * public $my_new_property = false; * } - * + * * class MyVisualization extends Piwik\Plugin\ViewDataTable * { * public static function getDefaultConfig() * { * return new MyVisualizationConfig(); * } - * + * * public static function getDefaultRequestConfig() * { * return new MyVisualizationRequestConfig(); * } * } - * + * * * @api */ @@ -153,14 +153,14 @@ abstract class ViewDataTable implements ViewInterface /** * Contains display properties for this visualization. - * + * * @var \Piwik\ViewDataTable\Config */ public $config; /** * Contains request properties for this visualization. - * + * * @var \Piwik\ViewDataTable\RequestConfig */ public $requestConfig; @@ -229,10 +229,10 @@ abstract class ViewDataTable implements ViewInterface /** * Triggered during {@link ViewDataTable} construction. Subscribers should customize * the view based on the report that is being displayed. - * + * * Plugins that define their own reports must subscribe to this event in order to * specify how the Piwik UI should display the report. - * + * * **Example** * * // event handler @@ -245,7 +245,7 @@ abstract class ViewDataTable implements ViewInterface * break; * } * } - * + * * @param ViewDataTable $view The instance to configure. */ Piwik::postEvent('ViewDataTable.configure', array($this)); @@ -283,12 +283,12 @@ abstract class ViewDataTable implements ViewInterface /** * Returns the default config instance. - * + * * Visualizations that define their own display properties should override this method and * return an instance of their new {@link Piwik\ViewDataTable\Config} descendant. * * See the last example {@link ViewDataTable here} for more information. - * + * * @return \Piwik\ViewDataTable\Config */ public static function getDefaultConfig() @@ -298,12 +298,12 @@ abstract class ViewDataTable implements ViewInterface /** * Returns the default request config instance. - * + * * Visualizations that define their own request properties should override this method and * return an instance of their new {@link Piwik\ViewDataTable\RequestConfig} descendant. * * See the last example {@link ViewDataTable here} for more information. - * + * * @return \Piwik\ViewDataTable\RequestConfig */ public static function getDefaultRequestConfig() @@ -326,7 +326,7 @@ abstract class ViewDataTable implements ViewInterface /** * Returns the viewDataTable ID for this DataTable visualization. - * + * * Derived classes should not override this method. They should instead declare a const ID field * with the viewDataTable ID. * @@ -348,7 +348,7 @@ abstract class ViewDataTable implements ViewInterface /** * Returns `true` if this instance's or any of its ancestors' viewDataTable IDs equals the supplied ID, * `false` if otherwise. - * + * * Can be used to test whether a ViewDataTable object is an instance of a certain visualization or not, * without having to know where that visualization is. * @@ -479,7 +479,7 @@ abstract class ViewDataTable implements ViewInterface /** * Returns `true` if this visualization can display some type of data or not. - * + * * New visualization classes should override this method if they can only visualize certain * types of data. The evolution graph visualization, for example, can only visualize * sets of DataTables. If the API method used results in a single DataTable, the evolution |