Click here if you want to read this article for the latest Piwik version

Piwik\Plugin\Dimension\

ActionDimension

Since Piwik 2.5.0

Defines a new action dimension that records any information during tracking for each action.

You can record any action information by implementing one of the following events: onLookupAction() and getActionId() or onNewAction(). By defining a $columnName and $columnType a new column will be created in the database (table log_link_visit_action) automatically and the values you return in the previous mentioned events will be saved in this column.

You can create a new dimension using the console command ./console generate:dimension.

Properties

This abstract class defines the following properties:

  • $columnName ash; This will be the name of the column in the database table if a $columnType is specified. Inherited from Dimension
  • $columnType ash; If a columnType is defined, we will create a column in the MySQL table having this type. Inherited from Dimension

$columnName

This will be the name of the column in the database table if a $columnType is specified.

Signature

  • It is a string value.

$columnType

If a columnType is defined, we will create a column in the MySQL table having this type.

Please make sure MySQL understands this type. Once you change the column type the Piwik platform will notify the user to perform an update which can sometimes take a long time so be careful when choosing the correct column type.

Signature

  • It is a string value.

Methods

The abstract class defines the following methods:

  • addSegment() — Adds a new segment.
  • getName() ash; Get the translated name of the dimension. Inherited from Dimension
  • getId() ash; Returns a unique string ID for this dimension. Inherited from Dimension
  • getAllDimensions() ash; Gets an instance of all available visit, action and conversion dimension. Inherited from Dimension
  • getDimensions() Inherited from Dimension
  • factory() ash; Creates a Dimension instance from a string ID (see getId()). Inherited from Dimension
  • getModule() ash; Returns the name of the plugin that contains this Dimension. Inherited from Dimension
  • install() — Installs the action dimension in case it is not installed yet.
  • uninstall() ash; Uninstalls the dimension if a $columnName and columnType is set.
  • onLookupAction() — If the value you want to save for your dimension is something like a page title or page url, you usually do not want to save the raw value over and over again to save bytes in the database.
  • getActionId() — An action id.
  • onNewAction() — This event is triggered before a new action is logged to the log_link_visit_action table.

addSegment()

Adds a new segment.

It automatically sets the SQL segment depending on the column name in case none is set already.

See Also

  • \Piwik\Columns\Dimension::addSegment()

Signature

  • It accepts the following parameter(s):

  • It does not return anything.

getName()

Get the translated name of the dimension.

Defaults to an empty string.

Signature

  • It returns a string value.

getId()

Returns a unique string ID for this dimension.

The ID is built using the namespaced class name of the dimension, but is modified to be more human readable.

Signature

  • Returns: string — eg, "Referrers.Keywords"
  • It throws one of the following exceptions:
    • Exception — if the plugin and simple class name of this instance cannot be determined. This would only happen if the dimension is located in the wrong directory.

getAllDimensions()

Gets an instance of all available visit, action and conversion dimension.

Signature

getDimensions()

Signature

  • It accepts the following parameter(s):

  • It does not return anything.

factory()

Creates a Dimension instance from a string ID (see getId()).

Signature

  • It accepts the following parameter(s):

    • $dimensionId (string) — See getId().
  • Returns: Dimension|null — The created instance or null if there is no Dimension for $dimensionId or if the plugin that contains the Dimension is not loaded.

getModule()

Returns the name of the plugin that contains this Dimension.

Signature

  • It returns a string value.
  • It throws one of the following exceptions:
    • Exception — if the Dimension is not located within a Plugin module.

install()

Installs the action dimension in case it is not installed yet.

The installation is already implemented based on the $columnName and $columnType. If you want to perform additional actions beside adding the column to the database - for instance adding an index - you can overwrite this method. We recommend to call this parent method to get the minimum required actions and then add further custom actions since this makes sure the column will be installed correctly. We also recommend to change the default install behavior only if really needed. FYI: We do not directly execute those alter table statements here as we group them together with several other alter table statements do execute those changes in one step which results in a faster installation. The column will be added to the log_link_visit_action MySQL table.

Example: ``` public function install() { $changes = parent::install(); $changes['log_link_visit_action'][] = "ADD INDEX index_idsite_servertime ( idsite, server_time )";

   return $changes;

} ```

Signature

  • Returns: array — An array containing the table name as key and an array of MySQL alter table statements that should be executed on the given table. Example: array( 'log_link_visit_action' => array("ADD COLUMN `$this->columnName` $this->columnType", "ADD INDEX ...") );

uninstall()

Uninstalls the dimension if a $columnName and columnType is set.

In case you perform any custom actions during install() - for instance adding an index - you should make sure to undo those actions by overwriting this method. Make sure to call this parent method to make sure the uninstallation of the column will be done.

Signature

  • It does not return anything.
  • It throws one of the following exceptions:

onLookupAction()

If the value you want to save for your dimension is something like a page title or page url, you usually do not want to save the raw value over and over again to save bytes in the database.

Instead you want to save each value once in the log_action table and refer to this value by its ID in the log_link_visit_action table. You can do this by returning an action id in "getActionId()" and by returning a value here. If a value should be ignored or not persisted just return boolean false. Please note if you return a value here and you implement the event "onNewAction" the value will be probably overwritten by the other event. So make sure to implement only one of those.

Signature

  • It accepts the following parameter(s):

    • $request (Piwik\Tracker\Request) —

    • $action (Piwik\Tracker\Action) —

  • Returns: Piwik\Plugin\Dimension\false|mixed

getActionId()

An action id.

The value returned by the lookup action will be associated with this id in the log_action table.

Signature

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

onNewAction()

This event is triggered before a new action is logged to the log_link_visit_action table.

It overwrites any looked up action so it makes usually no sense to implement both methods but it sometimes does. You can assign any value to the column or return boolan false in case you do not want to save any value.

Signature

  • It accepts the following parameter(s):

    • $request (Piwik\Tracker\Request) —

    • $visitor (Piwik\Tracker\Visitor) —

    • $action (Piwik\Tracker\Action) —

  • Returns: mixed|Piwik\Plugin\Dimension\false