diff options
author | diosmosis <benakamoorthi@fastmail.fm> | 2013-12-06 08:14:56 +0400 |
---|---|---|
committer | diosmosis <benakamoorthi@fastmail.fm> | 2013-12-06 08:14:56 +0400 |
commit | 87d676dbff31adb4c1cf389cd66511434ab925ab (patch) | |
tree | 84401bb94212a06e373d0a668050239d9448b37e /core/Plugin/ViewDataTable.php | |
parent | 777ca60440aa67e436fb15bb0fc1bd445d32ce78 (diff) |
Refs #4200, documented undocumented visualization classes.
Diffstat (limited to 'core/Plugin/ViewDataTable.php')
-rw-r--r-- | core/Plugin/ViewDataTable.php | 92 |
1 files changed, 80 insertions, 12 deletions
diff --git a/core/Plugin/ViewDataTable.php b/core/Plugin/ViewDataTable.php index b3b64ac05a..2cd67bbd9e 100644 --- a/core/Plugin/ViewDataTable.php +++ b/core/Plugin/ViewDataTable.php @@ -23,22 +23,31 @@ use Piwik\ViewDataTable\Request as ViewDataTableRequest; use Piwik\ViewDataTable\RequestConfig as VizRequest; /** - * The base class of all analytics visualizations. + * The base class of all report visualizations. * * ViewDataTable instances load analytics data via Piwik's API and then output some * type of visualization of that data. * - * Visualizations can be in any format. HTML-based visualizations should derive from + * 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 that is 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. + * 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. * @@ -54,22 +63,81 @@ use Piwik\ViewDataTable\RequestConfig as VizRequest; * * **Customizing how reports are displayed** * - * Each individual report should be rendered in its own controller action. There are two - * ways to render reports, you can either: + * 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 visualization instance - * 2. + * 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. * - * **TODO** + * ViewDataTable instances are configured by setting and modifying display properties and request + * parameters. * * ### Creating new visualizations * - * - * **TODO** + * 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 * - * **TODO** + * **Manually configuring a ViewDataTable** + * + * // a controller method that displays a single report + * public function myReport() + * { + * $view = \Piwik\ViewDataTable\Factory::build('table', 'MyPlugin.myReport'); + * $view->config->show_limit_control = true; + * $view->config->translations['myFancyMetric'] = "My Fancy Metric"; + * // ... + * 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) { + * case 'MyPlugin.myReport': + * $view->config->show_limit_control = true; + * $view->config->translations['myFancyMetric'] = "My Fancy Metric"; + * // ... + * 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(); + * } + * } * * @package Piwik * @subpackage ViewDataTable |