Piwik\ViewDataTable\

RequestConfig

Contains base request properties for ViewDataTable instances.

Client Side Parameters

Client side parameters are request properties that should be passed on to the browser so client side JavaScript can use them. These properties will also be passed to the server with every AJAX request made.

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 request properties

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

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

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

Example

Defining new request properties

class MyCustomVizRequestConfig extends RequestConfig
{
    /**
     * 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:

• $clientSideParameters — The list of request parameters that are 'Client Side Parameters'.
• $overridableProperties — The list of ViewDataTable properties that can be overridden by query parameters.
• $filter_sort_column — Controls which column to sort the DataTable by before truncating and displaying.
• $filter_sort_order — Controls the sort order.
• $filter_limit — The number of items to truncate the data set to before rendering the DataTable view.
• $flat — If set to true, the returned data will contain the flattened view of the table data set.
• $totals ash; If set to true or "1", the report may calculate totals information and show percentage values for each row in relative to the total value.
• $expanded — If set to true, the returned data will contain the first level results, as well as all sub-tables.
• $filter_offset — The number of items from the start of the data set that should be ignored.
• $filter_pattern — A regex pattern to use to filter the DataTable before it is shown.
• $filter_column — The column to apply a filter pattern to.
• $filter_excludelowpop — Stores the column name to filter when filtering out rows with low values.
• $filter_excludelowpop_value — Stores the value considered 'low' when filtering out rows w/ low values.
• $request_parameters_to_modify — An array property that contains query parameter name/value overrides for API requests made by ViewDataTable.
• $disable_generic_filters — Whether to run generic filters on the DataTable before rendering or not.
• $disable_queued_filters — Whether to run ViewDataTable's list of queued filters or not.
• $apiMethodToRequestDataTable — returns 'Plugin.apiMethodName' used for this ViewDataTable, eg.
• $idSubtable — If the current dataTable refers to a subDataTable (eg.
• $pivotBy — Dimension ID to pivot by.
• $pivotByColumn — The column to display in a pivot table, eg, 'nb_visits'.
• $pivotByColumnLimit — The maximum number of columns to display in a pivot table.
• $compareSegments — List of segments to compare with.
• $comparePeriods — List of period labels to compare with.
• $compareDates — List of period dates to compare with.

$clientSideParameters

The list of request parameters that are 'Client Side Parameters'.

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.

$filter_sort_column

Controls which column to sort the DataTable by before truncating and displaying.

Default value: If the report contains nb_uniq_visitors and nb_uniq_visitors is a displayed column, then the default value is 'nb_uniq_visitors'. Otherwise, it is 'nb_visits'.

Signature

• Its type is not specified.

$filter_sort_order

Controls the sort order. Either 'asc' or 'desc'.

Default value: 'desc'

Signature

• Its type is not specified.

$filter_limit

The number of items to truncate the data set to before rendering the DataTable view.

Default value: false

Signature

• Its type is not specified.

$flat

If set to true, the returned data will contain the flattened view of the table data set.

The children of all first level rows will be aggregated under one row.

Default value: false

Signature

• Its type is not specified.

$totals

If set to true or "1", the report may calculate totals information and show percentage values for each row in relative to the total value.

Default value: 0

Signature

• Its type is not specified.

$expanded

If set to true, the returned data will contain the first level results, as well as all sub-tables.

Default value: false

Signature

• Its type is not specified.

$filter_offset

The number of items from the start of the data set that should be ignored.

Default value: 0

Signature

• Its type is not specified.

$filter_pattern

A regex pattern to use to filter the DataTable before it is shown.

Signature

• Its type is not specified.

$filter_column

The column to apply a filter pattern to.

Signature

• Its type is not specified.

$filter_excludelowpop

Stores the column name to filter when filtering out rows with low values.

Default value: false

Signature

• Its type is not specified.

$filter_excludelowpop_value

Stores the value considered 'low' when filtering out rows w/ low values.

Default value: false

Signature

• It can be one of the following types:
  • Closure
  • string

$request_parameters_to_modify

An array property that contains query parameter name/value overrides for API requests made by ViewDataTable.

E.g. array('idSite' => ..., 'period' => 'month')

Default value: array()

Signature

• Its type is not specified.

$disable_generic_filters

Whether to run generic filters on the DataTable before rendering or not.

Signature

• Its type is not specified.

$disable_queued_filters

Whether to run ViewDataTable's list of queued filters or not.

NOTE: Priority queued filters are always run.

Default value: false

Signature

• Its type is not specified.

$apiMethodToRequestDataTable

returns 'Plugin.apiMethodName' used for this ViewDataTable, eg. 'Actions.getPageUrls'

Signature

• It is a string value.

$idSubtable

If the current dataTable refers to a subDataTable (eg. keywordsBySearchEngineId for id=X) this variable is set to the Id

Signature

• It can be one of the following types:
  • bool
  • int

$pivotBy

Dimension ID to pivot by. See Piwik\DataTable\Filter\PivotByDimension for more info.

Signature

• It is a string value.

$pivotByColumn

The column to display in a pivot table, eg, 'nb_visits'. See Piwik\DataTable\Filter\PivotByDimension for more info.

Signature

• It is a string value.

$pivotByColumnLimit

The maximum number of columns to display in a pivot table. See Piwik\DataTable\Filter\PivotByDimension for more info.

Signature

• It is a int value.

$compareSegments

List of segments to compare with. Defaults to segments used in compareSegments[] query parameter.

Signature

• It is a array value.

$comparePeriods

List of period labels to compare with. Defaults to values used in comparePeriods[] query parameter.

Signature

• It is a array value.

$compareDates

List of period dates to compare with. Defaults to values used in compareDates[] query parameter.

Signature

• It is a array value.

Methods

The class defines the following methods:

• getProperties()
• addPropertiesThatShouldBeAvailableClientSide() — Marks request properties as client side properties.
• addPropertiesThatCanBeOverwrittenByQueryParams() — Marks display properties as overridable.
• setDefaultSort()
• getApiModuleToRequest()
• getApiMethodToRequest()
• getRequestParam()
• getExtraParametersToSet() — Override this method if you want to add custom request parameters to the API request based on ViewDataTable parameters.

getProperties()

Signature

• It does not return anything or a mixed result.

addPropertiesThatShouldBeAvailableClientSide()

Marks request 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('disable_queued_filters', 'filter_column').
• 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('disable_queued_filters', 'filter_column').
• It does not return anything or a mixed result.

setDefaultSort()

Signature

• It accepts the following parameter(s):

  • $columnsToDisplay

  • $hasNbUniqVisitors

  • $actualColumns

• It does not return anything or a mixed result.

getApiModuleToRequest()

Signature

• It does not return anything or a mixed result.

getApiMethodToRequest()

Signature

• It does not return anything or a mixed result.

getRequestParam()

Signature

• It accepts the following parameter(s):

  • $paramName

• It does not return anything or a mixed result.

getExtraParametersToSet()

Override this method if you want to add custom request parameters to the API request based on ViewDataTable parameters. Return in the result the list of extra parameters.

Signature

• Returns: array — eg, ['mycustomparam']