diff options
author | diosmosis <benakamoorthi@fastmail.fm> | 2013-12-08 06:36:27 +0400 |
---|---|---|
committer | diosmosis <benakamoorthi@fastmail.fm> | 2013-12-08 06:36:27 +0400 |
commit | 4cafa9e3c79051476c54ad81a3e73e7242e7775a (patch) | |
tree | 431054418bf63b5094e5c4be961ab420278d289e /core/Plugin/ViewDataTable.php | |
parent | 87d676dbff31adb4c1cf389cd66511434ab925ab (diff) |
Refs #4200 revised some of class/method docs.
Diffstat (limited to 'core/Plugin/ViewDataTable.php')
-rw-r--r-- | core/Plugin/ViewDataTable.php | 74 |
1 files changed, 48 insertions, 26 deletions
diff --git a/core/Plugin/ViewDataTable.php b/core/Plugin/ViewDataTable.php index 2cd67bbd9e..65c5ab86fc 100644 --- a/core/Plugin/ViewDataTable.php +++ b/core/Plugin/ViewDataTable.php @@ -25,7 +25,7 @@ use Piwik\ViewDataTable\RequestConfig as VizRequest; /** * The base class of all report visualizations. * - * ViewDataTable instances load analytics data via Piwik's API and then output some + * 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 @@ -38,7 +38,7 @@ use Piwik\ViewDataTable\RequestConfig as VizRequest; * 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 + * If this parameter is not set, then the default visualization type for the report being * displayed is used. * * ### Configuring ViewDataTables @@ -51,13 +51,13 @@ use Piwik\ViewDataTable\RequestConfig as VizRequest; * * Display properties can be set at any time before rendering. * - * **Request parameters** + * **Request properties** * - * Request parameters are similar to display properties in the way they are set. They are, + * 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 parameters are set by setting the fields of a {@link Piwik\ViewDataTable\RequestConfig} object stored in + * 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. * @@ -71,7 +71,7 @@ use Piwik\ViewDataTable\RequestConfig as VizRequest; * in the {@hook ViewDataTable.configure} event. * * ViewDataTable instances are configured by setting and modifying display properties and request - * parameters. + * properties. * * ### Creating new visualizations * @@ -156,11 +156,15 @@ abstract class ViewDataTable implements ViewInterface protected $dataTable = null; /** + * Contains display properties for this visualization. + * * @var \Piwik\ViewDataTable\Config */ public $config; /** + * Contains request properties for this visualization. + * * @var \Piwik\ViewDataTable\RequestConfig */ public $requestConfig; @@ -171,8 +175,9 @@ abstract class ViewDataTable implements ViewInterface protected $request; /** - * 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'. + * Constructor. Initializes display and request properties to their default values. + * Posts the {@hook ViewDataTable.configure} event which plugins can use to configure the + * way reports are displayed. */ public function __construct($controllerAction, $apiMethodToRequestDataTable) { @@ -230,9 +235,13 @@ abstract class ViewDataTable implements ViewInterface } /** - * 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. + * 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() @@ -241,9 +250,13 @@ abstract class ViewDataTable implements ViewInterface } /** - * 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. + * 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() @@ -265,7 +278,9 @@ abstract class ViewDataTable implements ViewInterface } /** - * Returns the viewDataTable ID for this DataTable visualization. Derived classes should declare a const ID field + * 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. * * @throws \Exception @@ -284,10 +299,13 @@ abstract class ViewDataTable implements ViewInterface } /** - * Detects whether the viewDataTable or one of its ancestors has the given id. - * - * @param string $viewDataTableId + * 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. * + * @param string $viewDataTableId The viewDataTable ID to check for, eg, `'table'`. * @return bool */ public function isViewDataTableId($viewDataTableId) @@ -298,10 +316,10 @@ abstract class ViewDataTable implements ViewInterface } /** - * Returns the DataTable loaded from the API + * Returns the DataTable loaded from the API. * * @return DataTable - * @throws \Exception if not yet defined + * @throws \Exception if not yet loaded. */ public function getDataTable() { @@ -314,10 +332,10 @@ abstract class ViewDataTable implements ViewInterface /** * To prevent calling an API multiple times, the DataTable can be set directly. - * It won't be loaded again from the API in this case + * It won't be loaded from the API in this case. * - * @param $dataTable - * @return void $dataTable DataTable + * @param DataTable $dataTable The DataTable to use. + * @return void */ public function setDataTable($dataTable) { @@ -390,7 +408,8 @@ abstract class ViewDataTable implements ViewInterface } /** - * Determine if the view data table requests a single data table or not. + * Returns `true` if this instance will request a single DataTable, `false` if requesting + * more than one. * * @return bool */ @@ -412,11 +431,14 @@ abstract class ViewDataTable implements ViewInterface } /** - * 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. + * 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 + * graph footer icon should not be displayed. * - * @param ViewDataTable $view + * @param ViewDataTable $view Contains the API request being checked. * @return bool */ public static function canDisplayViewDataTable(ViewDataTable $view) |