API Reference

WidgetConfig

Piwik\Widget\

WidgetConfig

Configures a widget.

Methods

The class defines the following methods:

setCategoryId()

Set the id of the category the widget belongs to.

Signature

  • It accepts the following parameter(s):
    • $categoryId (string) — Usually a translation key, eg 'General_Visits', 'Goals_Goals', ...
  • It returns a WidgetConfig value.

getCategoryId()

Get the id of the category the widget belongs to.

Signature

  • It returns a string value.

setSubcategoryId()

Set the id of the subcategory the widget belongs to. If a subcategory is specified, the widget will be shown in the Matomo (formerly Piwik) reporting UI. The subcategoryId will be used as a translation key for the submenu item.

Signature

  • It accepts the following parameter(s):
    • $subcategoryId (string) — Usually a translation key, eg 'General_Overview', 'Actions_Pages', ...
  • It returns a WidgetConfig value.

getSubcategoryId()

Get the currently set category ID.

Signature

  • It returns a string value.

setModule()

Set the module (aka plugin name) of the widget. The correct module is usually detected automatically and not needed to be configured manually.

Signature

  • It accepts the following parameter(s):
    • $module (string) — eg 'CoreHome'
  • It returns a WidgetConfig value.

getModule()

Signature

  • It does not return anything or a mixed result.

setAction()

Set the action of the widget that shall be used in the URL to render the widget.

The correct action is usually detected automatically and not needed to be configured manually.

Signature

  • It accepts the following parameter(s):
    • $action (string) — eg 'renderMyWidget'
  • It returns a WidgetConfig value.

getAction()

Get the currently set action.

Signature

  • It returns a string value.

setParameters()

Sets (overwrites) the parameters of the widget. These parameters will be added to the URL when rendering the widget. You can access these parameters via `Piwik\Common::getRequestVar(.

..)`.

This applies to widgets rendered through their controller/action request. Client-rendered widgets do not receive these parameters automatically and should instead derive request state from the browser context or load data via API requests.

Signature

  • It accepts the following parameter(s):
    • $parameters (array) — eg. ('urlparam' => 'urlvalue')
  • It returns a WidgetConfig value.

addParameters()

Add new parameters and only overwrite parameters that have the same name. See setParameters()

Like setParameters(), these parameters are only used for widgets rendered through their controller/action request and are not forwarded automatically to client-rendered widgets.

Signature

  • It accepts the following parameter(s):
    • $parameters (array) — eg. ('urlparam' => 'urlvalue')
  • It returns a WidgetConfig value.

getParameters()

Get all URL parameters needed to render this widget.

Signature

  • Returns: array — Eg ('urlparam' => 'urlvalue').

setName()

Set the name of the widget.

Signature

  • It accepts the following parameter(s):
    • $name (string) — Usually a translation key, eg 'VisitTime_ByServerTimeWidgetName'
  • It returns a WidgetConfig value.

getName()

Get the name of the widget.

Signature

  • It returns a string value.

setOrder()

Set the order of the widget.

Signature

  • It accepts the following parameter(s):
    • $order (int) — eg. 5
  • It returns a WidgetConfig value.

getOrder()

Returns the order of the widget.

Signature

  • It returns a int value.

isEnabled()

Defines whether a widget is enabled or not. For instance some widgets might not be available to every user or might depend on a setting (such as Ecommerce) of a site. In such a case you can perform any checks and then return true or false. If your report is only available to users having super user access you can do the following: return Piwik::hasUserSuperUserAccess();

Signature

  • It returns a bool value.

setIsEnabled()

Enable / disable the widget. See isEnabled()

Signature

  • It accepts the following parameter(s):

    • $isEnabled (bool) —

  • It returns a WidgetConfig value.

enable()

Enables the widget. See isEnabled()

Signature

  • It does not return anything or a mixed result.

disable()

Disables the widget. See isEnabled()

Signature

  • It does not return anything or a mixed result.

checkIsEnabled()

This method checks whether the widget is available, see isEnabled(). If not, it triggers an exception containing a message that will be displayed to the user. You can overwrite this message in case you want to customize the error message. Eg.

if (!$this->isEnabled()) {
    throw new Exception('Setting XYZ is not enabled or the user has not enough permission');
}

Signature

  • It does not return anything or a mixed result.
  • It throws one of the following exceptions:

getUniqueId()

Returns the unique id of an widget based on module, action and the set parameters.

Signature

  • It returns a string value.

setIsNotWidgetizable()

Sets the widget as not widgetizable isWidgetizeable().

Signature

setIsWidgetizable()

Sets the widget as widgetizable isWidgetizeable().

Signature

isWidgetizeable()

Detect whether the widget is widgetizable meaning it won't be able to add it to the dashboard and it won't be possible to export the widget via an iframe if it is not widgetizable. This is usually not needed but useful when you eg want to display a widget within the Matomo UI but not want to have it widgetizable.

Signature

  • It returns a bool value.

setMiddlewareParameters()

If middleware parameters are specified, the corresponding action will be executed before showing the actual widget in the UI. Only if this action (can be a controller method or API method) returns JSON true the widget will be actually shown. It is similar to isEnabled() but the specified action is performed each time the widget is requested in the UI whereas isEnabled is only checked once on the initial page load when we load the initial list of widgets. So if your widget's visibility depends on archived data (aka idSite/period/date) you should specify middle parameters. This has mainly two reasons:

  • This way the initial page load time is faster as we won't have to request archived data on the initial page load for widgets that are potentially never shown.
  • We execute that action every time before showing it. As the initial list of widgets is loaded on page load it is possible that some archives have no data yet, but at a later time there might be actually archived data. As we never reload the initial list of widgets we would still not show the widget even there we should. Example: On page load there are no conversions, a few minutes later there might be conversions. As the middleware is executed before showing it, we detect correctly that there are now conversions whereas isEnabled is only checked once on the initial Matomo page load.

Signature

  • It accepts the following parameter(s):
    • $parameters (array) — URL parameters eg array('module' => 'Goals', 'action' => 'Conversions')
  • It returns a WidgetConfig value.

getMiddlewareParameters()

Get defined middleware parameters (if any).

Signature

  • It returns a array value.

setClientSideComponent()

Since Matomo 5.10.0

Marks this widget as client-rendered by a Vue component exported by the given plugin bundle.

Client-rendered widgets do not execute the widget controller/action in a separate request before rendering. They should derive dynamic state from the current browser request or load data through API requests instead.

Signature

  • It accepts the following parameter(s):
    • $plugin (string) — eg 'Transitions'
    • $component (string) — eg 'TransitionsPage'
  • It returns a WidgetConfig value.

getClientSideComponent()

Since Matomo 5.10.0

Returns the configured client-rendered component definition.

Signature

  • Returns: array — string, name: string}

setClientSideProps()

Since Matomo 5.10.0

Sets static props that should be passed to the client-rendered Vue widget.

Use this for configuration known when the widget is registered. Request-specific widget parameters are not forwarded to client-rendered widgets through this mechanism.

Signature

  • It accepts the following parameter(s):

    • $props (array) —

  • It returns a WidgetConfig value.

getClientSideProps()

Since Matomo 5.10.0

Returns props configured for the client-rendered Vue widget.

Signature

  • It returns a array value.

setIsWide()

Marks this widget as a "wide" widget that requires the full width.

Signature

  • It returns a $this value.

isWide()

Detect whether the widget should be shown wide or not.

Signature

  • It returns a bool value.