Report visualizations that extend from this class will be displayed like all others in
the Piwik UI. The following extra UI controls will be displayed around the visualization
itself:
- report documentation,
- a footer message (if {@link Piwik\ViewDataTable\Config::$show_footer_message} is set),
- a list of links to related reports (if {@link Piwik\ViewDataTable\Config::$related_reports} is set),
- a button that allows users to switch visualizations,
- a control that allows users to export report data in different formats,
- a limit control that allows users to change the amount of rows displayed (if
{@link Piwik\ViewDataTable\Config::$show_limit_control} is true),
- and more depending on the visualization.
### Rendering Process
The following process is used to render reports:
- The report is loaded through Piwik's Reporting API.
- The display and request properties that require report data in order to determine a default
value are defaulted. These properties are:
- {@link Piwik\ViewDataTable\Config::$columns_to_display}
- {@link Piwik\ViewDataTable\RequestConfig::$filter_sort_column}
- {@link Piwik\ViewDataTable\RequestConfig::$filter_sort_order}
- Priority filters are applied to the report (see {@link Piwik\ViewDataTable\Config::$filters}).
- The filters that are applied to every report in the Reporting API (called **generic filters**)
are applied. (see {@link Piwik\API\Request})
- The report's queued filters are applied.
- A {@link Piwik\View} instance is created and rendered.
### Rendering Hooks
The Visualization class defines several overridable methods that are called at specific
points during the rendering process. Derived classes can override these methods change
the data that is displayed or set custom properties.
The overridable methods (called **rendering hooks**) are as follows:
- **beforeLoadDataTable**: Called at the start of the rendering process before any data
is loaded.
- **beforeGenericFiltersAreAppliedToLoadedDataTable**: Called after data is loaded and after priority
filters are called, but before other filters. This
method should be used if you need the report's
entire dataset.
- **afterGenericFiltersAreAppliedToLoadedDataTable**: Called after generic filters are applied, but before
queued filters are applied.
- **afterAllFiltersAreApplied**: Called after data is loaded and all filters are applied.
- **beforeRender**: Called immediately before a {@link Piwik\View} is created and rendered.
- **isThereDataToDisplay**: Called after a {@link Piwik\View} is created to determine if the report has
data or not. If not, a message is displayed to the user.
### The DataTable JavaScript class
In the UI, visualization behavior is provided by logic in the **DataTable** JavaScript class.
When creating new visualizations, the **DataTable** JavaScript class (or one of its existing
descendants) should be extended.
To learn more read the Visualizing Report Data
guide.
### Examples
**Changing the data that is loaded**
class MyVisualization extends Visualization
{
load the previous period's data as well as the requested data. this will change
$this->dataTable from a DataTable instance to a DataTable\Map instance.
public function beforeLoadDataTable()
{
$date = Common::getRequestVar('date');
list($previousDate, $ignore) = Range::getLastDate($date, $period);
$this->requestConfig->request_parameters_to_modify['date'] = $previousDate . ',' . $date;
}
since we load the previous period's data too, we need to override the logic to
check if there is data or not.
public function isThereDataToDisplay()
{
$tables = $this->dataTable->getDataTables()
$requestedDataTable = end($tables);
return $requestedDataTable->getRowsCount() != 0;
}
}
**Force properties to be set to certain values**
class MyVisualization extends Visualization
{
ensure that some properties are set to certain values before rendering.
this will overwrite any changes made by plugins that use this visualization.
public function beforeRender()
{
$this->config->max_graph_elements = false;
$this->config->datatable_js_type = 'MyVisualization';
$this->config->show_flatten_table = false;
$this->config->show_pagination_control = false;
$this->config->show_offset_information = false;
}
}
public function beforeGenericFiltersAreAppliedToLoadedDataTable()
{
if ($this->isPivoted()) {
$this->config->columns_to_display = $this->dataTable->getColumns();
$this->dataTable->applyQueuedFilters();
}
parent::beforeGenericFiltersAreAppliedToLoadedDataTable();
}
public static function canDisplayViewDataTable(ViewDataTable $view)
{
// You usually do not need to implement this method. 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. Example:
// return $view->isRequestingSingleDataTable();
return parent::canDisplayViewDataTable($view);
}
public static function getDefaultRequestConfig()
{
$config = parent::getDefaultRequestConfig();
$config->addPropertiesThatShouldBeAvailableClientSide(array('columns'));
return $config;
}
public static function canDisplayViewDataTable(ViewDataTable $view)
{
$period = Common::getRequestVar('period', null, 'string');
$date = Common::getRequestVar('date', null, 'string');
$canGenerateInsights = API::getInstance()->canGenerateInsights($date, $period);
if (!$canGenerateInsights) {
return false;
}
if ($view->requestConfig->apiMethodToRequestDataTable && 0 === strpos($view->requestConfig->apiMethodToRequestDataTable, 'DBStats')) {
return false;
}
return parent::canDisplayViewDataTable($view);
}
