API Reference

WidgetContainerConfig

Piwik\Widget\

WidgetContainerConfig

Defines a new widget container.

To define a widget container just place a subclass within the Widgets folder of your plugin.

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

..)`.

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()

Signature

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

getParameters()

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()

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.

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.

setId()

Sets (overwrites) the id of the widget container.

The id can be used by any plugins to add more widgets to this container and it will be also used for the unique widget id and in the URL to render this widget.

Signature

  • It accepts the following parameter(s):
    • $id (string) — eg 'Products' or 'Contents'
  • It returns a WidgetContainerConfig value.

getId()

Get the id of the widget.

Signature

  • It returns a string value.

setLayout()

Sets the layout of the container widget.

By default widgets within a container are displayed one after another. In case you want to change this behaviour you can specify a layout that will be recognized by the UI. It is not yet possible to define custom layouts.

Signature

  • It accepts the following parameter(s):
    • $layout (string) — eg 'ByDimension' see Piwik\Plugins\CoreHome\CoreHome::WIDGET_CONTAINER_LAYOUT_BY_DIMENSION
  • It returns a WidgetContainerConfig value.

getLayout()

Gets the currently set layout.

Signature

  • It returns a string value.

addWidgetConfig()

Adds a new widget to the container widget.

Signature

setWidgetConfigs()

Set (overwrite) widget configs.

Signature

  • It accepts the following parameter(s):

  • It does not return anything or a mixed result.

getWidgetConfigs()

Get all added widget configs.

Signature