Description

The base class for report visualizations that output HTML and use JavaScript.

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 header message (if {@link Piwik\ViewDataTable\Config::$show_header_message} is set),
  • 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; } }

Type hierarchy

Class usage:

This class is used in:
Class Package
Piwik\Plugins\PrivacyManager\PrivacyManager
piwik/piwik 4.0.0-b3