Piwik\ViewDataTable\
Contains base display properties for ViewDataTables.
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 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.
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'));
}
}
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$clientSidePropertiesThe list of ViewDataTable properties that are 'Client Side Properties'.
$overridablePropertiesThe list of ViewDataTable properties that can be overridden by query parameters.
$footer_iconsControls 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.
$show_visualization_onlyControls whether the buttons and UI controls around the visualization or shown or if just the visualization alone is shown.
$show_goalsControls whether the goals footer icon is shown.
$show_insightsControls whether the 'insights' footer icon is shown.
$translationsArray 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.
$show_exclude_low_populationControls whether the 'Exclude Low Population' option (visible in the popup that displays after clicking the 'cog' icon) is shown.
$show_flatten_tableWhether to show the 'Flatten' option (visible in the popup that displays after clicking the 'cog' icon).
$show_pivot_by_subtableWhether to show the 'Pivot by subtable' option (visible in the popup that displays after clicking the 'cog' icon).
$pivot_by_dimensionThe 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.
$pivot_by_columnThe column to display in pivot tables. Defaults to the first non-label column if not specified.
$pivot_dimension_nameThe human readable name of the pivot dimension.
$show_tableControls whether the footer icon that allows users to switch to the 'normal' DataTable view is shown.
$show_table_all_columnsControls whether the 'All Columns' footer icon is shown.
$show_table_performanceControls whether the 'Performance columns' footer icon is shown (if available).
$show_footerControls whether the entire view footer is shown.
$show_footer_iconsControls whether the row that contains all footer icons & the limit selector is shown.
$columns_to_displayArray 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.
$show_all_views_iconsControls whether graph and non core viewDataTable footer icons are shown or not.
$selectable_columnsArray property that contains the names of columns that can be selected in the Series Picker.
Default value: false
$related_reportsRelated 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.
$related_reports_title"Related Reports" is displayed by default before listing the Related reports, The string can be changed.
$titleThe report title. Used with related reports so report headings can be changed when switching reports.
This must be set if related reports are added.
$title_edit_entity_urlIf 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.
string value.$descriptionThe report description. eg like a goal description
$show_related_reportsControls whether a report's related reports are listed with the view or not.
$documentationContains the documentation for a report.
$onlineGuideUrlURL linking to an online guide for this report (or plugin).
string value.$custom_parametersArray 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
$show_limit_controlControls 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.
$show_searchControls whether the search box under the datatable is shown.
$show_periodsControls whether the period selector under the datatable is shown.
$selectable_periodsControls which periods can be selected when the period selector is enabled
$show_exportControls whether the export feature under the datatable is shown.
$enable_sortControls whether the user can sort DataTables by clicking on table column headings.
$show_bar_chartControls whether the footer icon that allows users to view data as a bar chart is shown.
$show_pie_chartControls whether the footer icon that allows users to view data as a pie chart is shown.
$show_tag_cloudControls whether the footer icon that allows users to view data as a tag cloud is shown.
$show_as_content_blockIf enabled, shows the visualization as a content block. This is similar to wrapping your visualization
with a <div piwik-content-block></div>
bool value.$show_titleIf enabled shows the title of the report.
bool value.$show_export_as_rss_feedControls whether the user is allowed to export data as an RSS feed or not.
$show_ecommerceControls whether the 'Ecoommerce Orders'/'Abandoned Cart' footer icons are shown or not.
$show_header_messageStores an HTML message (if any) to display above the datatable view.
Attention: Message will be printed raw. Don't forget to escape where needed!
$show_footer_messageStores an HTML message (if any) to display under the datatable view.
Attention: Message will be printed raw. Don't forget to escape where needed!
$metrics_documentationArray 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).
$tooltip_metadata_nameRow metadata name that contains the tooltip for the specific row.
$self_urlThe 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.
$datatable_css_classCSS class to use in the output HTML div. This is added in addition to the visualization CSS class.
$datatable_js_typeThe JavaScript class to instantiate after the result HTML is obtained. This class handles all interactive behavior for the DataTable view.
$search_recursiveIf true, searching through the DataTable will search through all subtables.
$y_axis_unitThe unit of the displayed column. Valid if only one non-label column is displayed.
$show_export_as_image_iconControls whether to show the 'Export as Image' footer icon.
$filtersArray 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.
$subtable_controller_actionContains 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.
$show_pagination_controlControls whether the 'prev'/'next' links are shown in the DataTable footer. These links change the 'filter_offset' query parameter, thus allowing pagination.
$show_offset_informationControls whether offset information (ie, '5-10 of 20') is shown under the datatable.
$hide_annotations_viewControls whether annotations are shown or not.
$disable_all_rows_filter_limitControls whether the 'all' row limit option is shown for the limit selector.
bool value.$max_export_filter_limitSets a limit for the maximum number of rows that can be exported.
int value.$no_data_messageMessage 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!
string value.$datatable_actionsList of extra actions to display as icons in the datatable footer.
Not API yet.
array value.$segmented_visitor_log_segment_suffix$disable_comparisonDisable comparison support for this specific usage of a ViewDataTable.
bool value.$report_id$controllerName$controllerActionThe 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.
addPropertiesThatShouldBeAvailableClientSide()Marks display properties as client side properties. Read this to learn more.
$propertyNames (array) —
List of property names, eg, array('show_limit_control', 'show_goals').addPropertiesThatCanBeOverwrittenByQueryParams()Marks display properties as overridable. Read this to learn more.
$propertyNames (array) —
List of property names, eg, array('show_limit_control', 'show_goals').getProperties()Returns array of all property values in this config object. Property values are mapped by name.
array —
eg, array('show_limit_control' => 0, 'show_goals' => 1, ...)removeColumnToDisplay()It accepts the following parameter(s):
$columnToRemoveIt does not return anything or a mixed result.
getPriorityFilters()getPresentationFilters()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.
$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').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().
$relatedReports (array) —
Array mapping report IDs with their internationalized display titles, eg, array( 'DevicesDetection.getBrowsers' => 'Browsers', 'Resolution.getConfiguration' => 'Configurations' )addTranslation()Associates internationalized text with a metric. Overwrites existing mappings.
See $translations.
$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'".addTranslations()Associates multiple translations with metrics.
See $translations and addTranslation().
$translations (array) —
An array of column name => text mappings, eg, array( 'nb_visits' => 'Visits', 'goal_1_nb_conversions' => "Conversions for 'My Goal'" )disablePivotBySubtableIfTableHasNoSubtables()It accepts the following parameter(s):
$table (DataTable) —It does not return anything or a mixed result.