API Reference

Visualization

Piwik\Plugin\

Visualization

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 Matomo (formerly Piwik) UI. The following extra UI controls will be displayed around the visualization itself:

Rendering Process

The following process is used to render reports:

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 View is created and rendered.
  • isThereDataToDisplay: Called after a 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;
    }
}

Constants

This class defines the following constants:

  • TEMPLATE_FILE — The Twig template file to use when rendering, eg, "@MyPlugin/_myVisualization.twig". Inherited from Visualization

TEMPLATE_FILE

Must be defined by classes that extend Visualization.

Properties

This class defines the following properties:

$config

Contains display properties for this visualization.

Signature

$requestConfig

Contains request properties for this visualization.

Signature

Methods

The class defines the following methods:

__construct()

Constructor. Initializes display and request properties to their default values.

Posts the ViewDataTable.configure event which plugins can use to configure the way reports are displayed.

Signature

  • It accepts the following parameter(s):

    • $controllerAction

    • $apiMethodToRequestDataTable

    • $overrideParams

getDefaultConfig()

Returns the default config instance.

Visualizations that define their own display properties should override this method and return an instance of their new Config descendant.

See the last example here for more information.

Signature

getDefaultRequestConfig()

Returns the default request config instance.

Visualizations that define their own request properties should override this method and return an instance of their new RequestConfig descendant.

See the last example here for more information.

Signature

getViewDataTableId()

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.

Signature

  • It returns a string value.
  • It throws one of the following exceptions:

isViewDataTableId()

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.

Signature

  • It accepts the following parameter(s):
    • $viewDataTableId (string) — The viewDataTable ID to check for, eg, 'table'.
  • It returns a bool value.

getDataTable()

Returns the DataTable loaded from the API.

Signature

  • It returns a DataTable value.
  • It throws one of the following exceptions:

setDataTable()

To prevent calling an API multiple times, the DataTable can be set directly.

It won't be loaded from the API in this case.

Signature

  • It accepts the following parameter(s):
    • $dataTable (DataTable) — The DataTable to use.
  • It returns a void value.

render()

Requests all needed data and renders the view.

Signature

  • Returns: string — Serialized data, eg, (image, array, html...).

isRequestingSingleDataTable()

Returns true if this instance will request a single DataTable, false if requesting more than one.

Signature

  • It returns a bool value.

canDisplayViewDataTable()

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.

Signature

  • It accepts the following parameter(s):
    • $view (ViewDataTable) — Contains the API request being checked.
  • It returns a bool value.

throwWhenSettingNonOverridableParameter()

Display a meaningful error message when any invalid parameter is being set.

Signature

  • It accepts the following parameter(s):

    • $overrideParams

  • It does not return anything or a mixed result.

  • It throws one of the following exceptions:
    • ``

getNonOverridableParams()

Signature

  • It accepts the following parameter(s):

    • $overrideParams

  • It returns a array value.

isComparing()

Returns true if both this current visualization supports comparison, and if comparison query parameters are present in the URL.

Signature

  • It returns a bool value.

supportsComparison()

Implementations should override this method if they support a special comparison view. By default, it is assumed visualizations do not support comparison.

Signature

  • It returns a bool value.

getRequestArray()

Signature

  • It does not return anything or a mixed result.

assignTemplateVar()

Assigns a template variable making it available in the Twig template specified by TEMPLATE_FILE.

Signature

  • It accepts the following parameter(s):
    • $vars (array|string) — One or more variable names to set.
    • $value (mixed) — The value to set each variable to.
  • It does not return anything or a mixed result.

isThereDataToDisplay()

Returns true if there is data to display, false if otherwise.

Derived classes should override this method if they change the amount of data that is loaded.

Signature

  • It does not return anything or a mixed result.

beforeLoadDataTable()

Hook that is called before loading report data from the API.

Use this method to change the request parameters that is sent to the API when requesting data.

Signature

  • It does not return anything or a mixed result.

beforeGenericFiltersAreAppliedToLoadedDataTable()

Hook that is executed before generic filters are applied.

Use this method if you need access to the entire dataset (since generic filters will limit and truncate reports).

Signature

  • It does not return anything or a mixed result.

afterGenericFiltersAreAppliedToLoadedDataTable()

Hook that is executed after generic filters are applied.

Signature

  • It does not return anything or a mixed result.

afterAllFiltersAreApplied()

Hook that is executed after the report data is loaded and after all filters have been applied.

Use this method to format the report data before the view is rendered.

Signature

  • It does not return anything or a mixed result.

beforeRender()

Hook that is executed directly before rendering. Use this hook to force display properties to be a certain value, despite changes from plugins and query parameters.

Signature

  • It does not return anything or a mixed result.