API Reference

Config

Properties
Methods

This documentation is for an outdated Matomo version.
Click here if you want to read this article for the latest version.

Piwik\ViewDataTable\

Config

Contains base display properties for ViewDataTables.

Client Side Properties

Client side properties are properties that should be passed on to the browser so client side JavaScript can use them. Only affects ViewDataTables that output HTML.

Overridable Properties

Overridable properties are properties that can be set via the query string. If a request has a query parameter that matches an overridable property, the property will be set to the query parameter value.

Reusing base properties

Many of the properties in this class only have meaning for the Visualization class, but can be set for other visualizations that extend ViewDataTable directly.

Visualizations that extend ViewDataTable directly and want to re-use these properties must make sure the properties are used in the exact same way they are used in Visualization.

Defining new display properties

If you are creating your own visualization and want to add new display properties for it, extend this class and add your properties as fields.

Properties are marked as client side properties by calling the addPropertiesThatShouldBeAvailableClientSide() method.

Properties are marked as overridable by calling the addPropertiesThatCanBeOverwrittenByQueryParams() method.

Example

Defining new display properties

class MyCustomVizConfig extends Config
{
    /**
     * My custom property. It is overridable.
     *\/
    public $my_custom_property = false;

    /**
     * Another custom property. It is available client side.
     *\/
    public $another_custom_property = true;

    public function __construct()
    {
        parent::__construct();

        $this->addPropertiesThatShouldBeAvailableClientSide(array('another_custom_property'));
        $this->addPropertiesThatCanBeOverwrittenByQueryParams(array('my_custom_property'));
    }
}

Properties

This class defines the following properties:

$clientSideProperties — The list of ViewDataTable properties that are 'Client Side Properties'.
$overridableProperties — The list of ViewDataTable properties that can be overridden by query parameters.
$footer_icons — Controls what footer icons are displayed on the bottom left of the DataTable view.
$show_visualization_only — Controls whether the buttons and UI controls around the visualization or shown or if just the visualization alone is shown.
$show_goals — Controls whether the goals footer icon is shown.
$show_insights — Controls whether the 'insights' footer icon is shown.
$translations — Array property mapping DataTable column names with their internationalized names.
$show_exclude_low_population — Controls whether the 'Exclude Low Population' option (visible in the popup that displays after clicking the 'cog' icon) is shown.
$show_flatten_table — Whether to show the 'Flatten' option (visible in the popup that displays after clicking the 'cog' icon).
$show_pivot_by_subtable — Whether to show the 'Pivot by subtable' option (visible in the popup that displays after clicking the 'cog' icon).
$pivot_by_dimension — The ID of the dimension to pivot by when the 'pivot by subtable' option is clicked.
$pivot_by_column — The column to display in pivot tables.
$pivot_dimension_name — The human readable name of the pivot dimension.
$show_table — Controls whether the footer icon that allows users to switch to the 'normal' DataTable view is shown.
$show_table_all_columns — Controls whether the 'All Columns' footer icon is shown.
$show_table_performance — Controls whether the 'Performance columns' footer icon is shown (if available).
$show_footer — Controls whether the entire view footer is shown.
$show_footer_icons — Controls whether the row that contains all footer icons & the limit selector is shown.
$columns_to_display — Array property that determines which columns will be shown.
$show_all_views_icons — Controls whether graph and non core viewDataTable footer icons are shown or not.
$selectable_columns — Array property that contains the names of columns that can be selected in the Series Picker.
$related_reports — Related reports are listed below a datatable view.
$related_reports_title ash; "Related Reports" is displayed by default before listing the Related reports, The string can be changed.
$title — The report title.
$title_edit_entity_url — If a URL is set, the title of the report will be clickable.
$description — The report description.
$show_related_reports — Controls whether a report's related reports are listed with the view or not.
$documentation — Contains the documentation for a report.
$onlineGuideUrl — URL linking to an online guide for this report (or plugin).
$custom_parameters — Array property containing custom data to be saved in JSON in the data-params HTML attribute of a data table div.
$show_limit_control — Controls whether the limit dropdown (which allows users to change the number of data shown) is always shown or not.
$show_search — Controls whether the search box under the datatable is shown.
$show_periods — Controls whether the period selector under the datatable is shown.
$selectable_periods — Controls which periods can be selected when the period selector is enabled
$show_export — Controls whether the export feature under the datatable is shown.
$enable_sort — Controls whether the user can sort DataTables by clicking on table column headings.
$show_bar_chart — Controls whether the footer icon that allows users to view data as a bar chart is shown.
$show_pie_chart — Controls whether the footer icon that allows users to view data as a pie chart is shown.
$show_tag_cloud — Controls whether the footer icon that allows users to view data as a tag cloud is shown.
$show_as_content_block — If enabled, shows the visualization as a content block.
$show_title — If enabled shows the title of the report.
$show_export_as_rss_feed — Controls whether the user is allowed to export data as an RSS feed or not.
$show_ecommerce — Controls whether the 'Ecoommerce Orders'/'Abandoned Cart' footer icons are shown or not.
$show_header_message — Stores an HTML message (if any) to display above the datatable view.
$show_footer_message — Stores an HTML message (if any) to display under the datatable view.
$metrics_documentation — Array property that stores documentation for individual metrics.
$tooltip_metadata_name — Row metadata name that contains the tooltip for the specific row.
$self_url — The URL to the report the view is displaying.
$datatable_css_class — CSS class to use in the output HTML div.
$datatable_js_type — The JavaScript class to instantiate after the result HTML is obtained.
$search_recursive — If true, searching through the DataTable will search through all subtables.
$y_axis_unit — The unit of the displayed column.
$show_export_as_image_icon — Controls whether to show the 'Export as Image' footer icon.
$filters — Array of DataTable filters that should be run before displaying a DataTable.
$subtable_controller_action — Contains the controller action to call when requesting subtables of the current report.
$show_pagination_control — Controls whether the 'prev'/'next' links are shown in the DataTable footer.
$show_offset_information — Controls whether offset information (ie, '5-10 of 20') is shown under the datatable.
$hide_annotations_view — Controls whether annotations are shown or not.
$disable_all_rows_filter_limit — Controls whether the 'all' row limit option is shown for the limit selector.
$max_export_filter_limit — Sets a limit for the maximum number of rows that can be exported.
$no_data_message — Message to show if not data is available for the report Defaults to CoreHome_ThereIsNoDataForThisReport if not set
$datatable_actions — List of extra actions to display as icons in the datatable footer.
$segmented_visitor_log_segment_suffix
$disable_comparison — Disable comparison support for this specific usage of a ViewDataTable.
$report_id
$controllerName
$controllerAction

`$clientSideProperties`

The list of ViewDataTable properties that are 'Client Side Properties'.

Signature

Its type is not specified.

`$overridableProperties`

The list of ViewDataTable properties that can be overridden by query parameters.

Signature

Its type is not specified.

`$footer_icons`

Controls what footer icons are displayed on the bottom left of the DataTable view.

The value of this property must be an array of footer icon groups. Footer icon groups have set of properties, including an array of arrays describing footer icons. For example:

array(
    array( // footer icon group 1
        'class' => 'footerIconGroup1CssClass',
        'buttons' => array(
            'id' => 'myid',
            'title' => 'My Tooltip',
            'icon' => 'path/to/my/icon.png'
        )
    ),
    array( // footer icon group 2
        'class' => 'footerIconGroup2CssClass',
        'buttons' => array(...)
    )
)

By default, when a user clicks on a footer icon, Matomo (formerly Piwik) will assume the 'id' is a viewDataTable ID and try to reload the DataTable w/ the new viewDataTable. You can provide your own footer icon behavior by adding an appropriate handler via DataTable.registerFooterIconHandler in your JavaScript code.

The default value of this property is not set here and will show the 'Normal Table' icon, the 'All Columns' icon, the 'Goals Columns' icon and all jqPlot graph columns, unless other properties tell the view to exclude them.

Signature

Its type is not specified.

`$show_visualization_only`

Controls whether the buttons and UI controls around the visualization or shown or if just the visualization alone is shown.

Signature

Its type is not specified.

`$show_goals`

Controls whether the goals footer icon is shown.

Signature

Its type is not specified.

`$show_insights`

Controls whether the 'insights' footer icon is shown.

Signature

Its type is not specified.

`$translations`

Array property mapping DataTable column names with their internationalized names.

The default value for this property is set elsewhere. It will contain translations of common metrics.

Signature

Its type is not specified.

`$show_exclude_low_population`

Controls whether the 'Exclude Low Population' option (visible in the popup that displays after clicking the 'cog' icon) is shown.

Signature

Its type is not specified.

`$show_flatten_table`

Whether to show the 'Flatten' option (visible in the popup that displays after clicking the 'cog' icon).

Signature

Its type is not specified.

`$show_pivot_by_subtable`

Whether to show the 'Pivot by subtable' option (visible in the popup that displays after clicking the 'cog' icon).

Signature

Its type is not specified.

`$pivot_by_dimension`

The ID of the dimension to pivot by when the 'pivot by subtable' option is clicked. Defaults to the subtable dimension of the report being displayed.

Signature

Its type is not specified.

`$pivot_by_column`

The column to display in pivot tables. Defaults to the first non-label column if not specified.

Signature

Its type is not specified.

`$pivot_dimension_name`

The human readable name of the pivot dimension.

Signature

Its type is not specified.

`$show_table`

Controls whether the footer icon that allows users to switch to the 'normal' DataTable view is shown.

Signature

Its type is not specified.

`$show_table_all_columns`

Controls whether the 'All Columns' footer icon is shown.

Signature

Its type is not specified.

`$show_table_performance`

Controls whether the 'Performance columns' footer icon is shown (if available).

Signature

Its type is not specified.

`$show_footer`

Controls whether the entire view footer is shown.

Signature

Its type is not specified.

`$show_footer_icons`

Controls whether the row that contains all footer icons & the limit selector is shown.

Signature

Its type is not specified.

`$columns_to_display`

Array property that determines which columns will be shown. Columns not in this array should not appear in ViewDataTable visualizations.

Example: array('label', 'nb_visits', 'nb_uniq_visitors')

If this value is empty it will be defaulted to array('label', 'nb_visits') or array('label', 'nb_uniq_visitors') if the report contains a nb_uniq_visitors column after data is loaded.

Signature

Its type is not specified.

`$show_all_views_icons`

Controls whether graph and non core viewDataTable footer icons are shown or not.

Signature

Its type is not specified.

`$selectable_columns`

Array property that contains the names of columns that can be selected in the Series Picker.

Default value: false

Signature

Its type is not specified.

`$related_reports`

Related reports are listed below a datatable view. When clicked, the original report will change to the clicked report and the list will change so the original report can be navigated back to.

Signature

Its type is not specified.

`$related_reports_title`

"Related Reports" is displayed by default before listing the Related reports, The string can be changed.

Signature

Its type is not specified.

`$title`

The report title. Used with related reports so report headings can be changed when switching reports.

This must be set if related reports are added.

Signature

Its type is not specified.

`$title_edit_entity_url`

If a URL is set, the title of the report will be clickable. Is supposed to be set for entities that can be configured (edited) such as goal. Eg when there is a goal report, and someone is allowed to edit the goal entity, a link is supposed to be with a URL to the edit goal form.

Signature

It is a string value.

`$description`

The report description. eg like a goal description

Signature

Its type is not specified.

`$show_related_reports`

Controls whether a report's related reports are listed with the view or not.

Signature

Its type is not specified.

`$documentation`

Contains the documentation for a report.

Signature

Its type is not specified.

`$onlineGuideUrl`

URL linking to an online guide for this report (or plugin).

Signature

It is a string value.

`$custom_parameters`

Array property containing custom data to be saved in JSON in the data-params HTML attribute of a data table div. This data can be used by JavaScript DataTable classes.

e.g. array('typeReferrer' => ...)

It can then be accessed in the twig templates by clientSideParameters.typeReferrer

Signature

Its type is not specified.

`$show_limit_control`

Controls whether the limit dropdown (which allows users to change the number of data shown) is always shown or not.

Normally shown only if pagination is enabled.

Signature

Its type is not specified.

`$show_search`

Controls whether the search box under the datatable is shown.

Signature

Its type is not specified.

`$show_periods`

Controls whether the period selector under the datatable is shown.

Signature

Its type is not specified.

`$selectable_periods`

Controls which periods can be selected when the period selector is enabled

Signature

Its type is not specified.

`$show_export`

Controls whether the export feature under the datatable is shown.

Signature

Its type is not specified.

`$enable_sort`

Controls whether the user can sort DataTables by clicking on table column headings.

Signature

Its type is not specified.

`$show_bar_chart`

Controls whether the footer icon that allows users to view data as a bar chart is shown.

Signature

Its type is not specified.

`$show_pie_chart`

Controls whether the footer icon that allows users to view data as a pie chart is shown.

Signature

Its type is not specified.

`$show_tag_cloud`

Controls whether the footer icon that allows users to view data as a tag cloud is shown.

Signature

Its type is not specified.

`$show_as_content_block`

If enabled, shows the visualization as a content block. This is similar to wrapping your visualization with a <div piwik-content-block></div>

Signature

It is a bool value.

`$show_title`

If enabled shows the title of the report.

Signature

It is a bool value.

`$show_export_as_rss_feed`

Controls whether the user is allowed to export data as an RSS feed or not.

Signature

Its type is not specified.

`$show_ecommerce`

Controls whether the 'Ecoommerce Orders'/'Abandoned Cart' footer icons are shown or not.

Signature

Its type is not specified.

`$show_header_message`

Stores an HTML message (if any) to display above the datatable view.

Attention: Message will be printed raw. Don't forget to escape where needed!

Signature

Its type is not specified.

`$show_footer_message`

Stores an HTML message (if any) to display under the datatable view.

Attention: Message will be printed raw. Don't forget to escape where needed!

Signature

Its type is not specified.

`$metrics_documentation`

Array property that stores documentation for individual metrics.

E.g. array('nb_visits' => '...', ...)

By default this is set to values retrieved from report metadata (via API.getReportMetadata API method).

Signature

Its type is not specified.

`$tooltip_metadata_name`

Row metadata name that contains the tooltip for the specific row.

Signature

Its type is not specified.

`$self_url`

The URL to the report the view is displaying. Modifying this means clicking back to this report from a Related Report will go to a different URL. Can be used to load an entire page instead of a single report when going back to the original report.

The URL used to request the report without generic filters.

Signature

Its type is not specified.

`$datatable_css_class`

CSS class to use in the output HTML div. This is added in addition to the visualization CSS class.

Signature

Its type is not specified.

`$datatable_js_type`

The JavaScript class to instantiate after the result HTML is obtained. This class handles all interactive behavior for the DataTable view.

Signature

Its type is not specified.

`$search_recursive`

If true, searching through the DataTable will search through all subtables.

Signature

Its type is not specified.

`$y_axis_unit`

The unit of the displayed column. Valid if only one non-label column is displayed.

Signature

Its type is not specified.

`$show_export_as_image_icon`

Controls whether to show the 'Export as Image' footer icon.

Signature

Its type is not specified.

`$filters`

Array of DataTable filters that should be run before displaying a DataTable. Elements of this array can either be a closure or an array with at most three elements, including: - the filter name (or a closure) - an array of filter parameters - a boolean indicating if the filter is a priority filter or not

Priority filters are run before queued filters. These filters should be filters that add/delete rows.

If a closure is used, the view is appended as a parameter.

Signature

Its type is not specified.

`$subtable_controller_action`

Contains the controller action to call when requesting subtables of the current report.

By default, this is set to the controller action used to request the report.

Signature

Its type is not specified.

`$show_pagination_control`

Controls whether the 'prev'/'next' links are shown in the DataTable footer. These links change the 'filter_offset' query parameter, thus allowing pagination.

Signature

Its type is not specified.

`$show_offset_information`

Controls whether offset information (ie, '5-10 of 20') is shown under the datatable.

Signature

Its type is not specified.

`$hide_annotations_view`

Controls whether annotations are shown or not.

Signature

Its type is not specified.

`$disable_all_rows_filter_limit`

Controls whether the 'all' row limit option is shown for the limit selector.

Signature

It is a bool value.

`$max_export_filter_limit`

Sets a limit for the maximum number of rows that can be exported.

Signature

It is a int value.

`$no_data_message`

Message to show if not data is available for the report Defaults to CoreHome_ThereIsNoDataForThisReport if not set

Attention: Message will be printed raw. Don't forget to escape where needed!

Signature

It is a string value.

`$datatable_actions`

List of extra actions to display as icons in the datatable footer.

Not API yet.

Signature

It is a array value.

`$segmented_visitor_log_segment_suffix`

Signature

Its type is not specified.

`$disable_comparison`

Disable comparison support for this specific usage of a ViewDataTable.

Signature

It is a bool value.

`$report_id`

Signature

Its type is not specified.

`$controllerName`

Signature

Its type is not specified.

`$controllerAction`

Signature

Its type is not specified.

Methods

The class defines the following methods:

__construct() — Constructor.
addPropertiesThatShouldBeAvailableClientSide() — Marks display properties as client side properties.
addPropertiesThatCanBeOverwrittenByQueryParams() — Marks display properties as overridable.
getProperties() — Returns array of all property values in this config object.
removeColumnToDisplay()
getPriorityFilters()
getPresentationFilters()
addRelatedReport() ash; Adds a related report to the $related_reports property.
addRelatedReports() ash; Adds several related reports to the $related_reports property.
addTranslation() — Associates internationalized text with a metric.
addTranslations() — Associates multiple translations with metrics.
disablePivotBySubtableIfTableHasNoSubtables()

`__construct()`

Constructor.

Signature

`addPropertiesThatShouldBeAvailableClientSide()`

Marks display properties as client side properties. Read this to learn more.

Signature

It accepts the following parameter(s):
- $propertyNames (array) — List of property names, eg, array('show_limit_control', 'show_goals').
It does not return anything or a mixed result.

`addPropertiesThatCanBeOverwrittenByQueryParams()`

Marks display properties as overridable. Read this to learn more.

Signature

It accepts the following parameter(s):
- $propertyNames (array) — List of property names, eg, array('show_limit_control', 'show_goals').
It does not return anything or a mixed result.

`getProperties()`

Returns array of all property values in this config object. Property values are mapped by name.

Signature

Returns: array — eg, array('show_limit_control' => 0, 'show_goals' => 1, ...)

`removeColumnToDisplay()`

Signature

It accepts the following parameter(s):
- $columnToRemove
It does not return anything or a mixed result.

`getPriorityFilters()`

Signature

It does not return anything or a mixed result.

`getPresentationFilters()`

Signature

It does not return anything or a mixed result.

`addRelatedReport()`

Adds a related report to the $related_reports property. If the report references the one that is currently being displayed, it will not be added to the related report list.

Signature

It accepts the following parameter(s):
- $relatedReport (string) — The plugin and method of the report, eg, 'DevicesDetection.getBrowsers'.
- $title (string) — The report's display name, eg, 'Browsers'.
- $queryParams (array) — Any extra query parameters to set in related report's URL, eg, array('idGoal' => 'ecommerceOrder').
It does not return anything or a mixed result.

`addRelatedReports()`

Adds several related reports to the $related_reports property. If any of the reports references the report that is currently being displayed, it will not be added to the list. All other reports will still be added though.

If you need to make sure the related report URL has some extra query parameters, use addRelatedReport().

Signature

It accepts the following parameter(s):
- $relatedReports (array) — Array mapping report IDs with their internationalized display titles, eg, array( 'DevicesDetection.getBrowsers' => 'Browsers', 'Resolution.getConfiguration' => 'Configurations' )
It does not return anything or a mixed result.

`addTranslation()`

Associates internationalized text with a metric. Overwrites existing mappings.

See $translations.

Signature

It accepts the following parameter(s):
- $columnName (string) — The name of a column in the report data, eg, 'nb_visits' or 'goal_1_nb_conversions'.
- $translation (string) — The internationalized text, eg, 'Visits' or "Conversions for 'My Goal'".
It does not return anything or a mixed result.

`addTranslations()`

Associates multiple translations with metrics.

See $translations and addTranslation().

Signature

It accepts the following parameter(s):
- $translations (array) — An array of column name => text mappings, eg, array( 'nb_visits' => 'Visits', 'goal_1_nb_conversions' => "Conversions for 'My Goal'" )
It does not return anything or a mixed result.

`disablePivotBySubtableIfTableHasNoSubtables()`

Signature

It accepts the following parameter(s):
- $table (DataTable) —
It does not return anything or a mixed result.