Piwik\ViewDataTable\

Config

Contains base display properties for ViewDataTables.

Manipulating these properties in a ViewDataTable instance will change how its report will be displayed.

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 overriden 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_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.
  • $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.
  • $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.
  • $no_data_message — Message to show if not data is available for the report Defaults to CoreHome_ThereIsNoDataForThisReport if not set
  • $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 overriden by query parameters.

Signature

  • Its type is not specified.

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.

Controls whether the entire view footer is shown.

Signature

  • Its type is not specified.

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.

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" 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.

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.

$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.

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.

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.

$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.

$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.

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.

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.

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.

getPriorityFilters()

Signature

  • It does not return anything.

getPresentationFilters()

Signature

  • It does not return anything.

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 releated report's URL, eg, array('idGoal' => 'ecommerceOrder').
  • It does not return anything.

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.

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.

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.

disablePivotBySubtableIfTableHasNoSubtables()

Signature

  • It accepts the following parameter(s):

  • It does not return anything.