Piwik\Settings\

FieldConfig

Lets you configure a form field.

Constants

This class defines the following constants:

• UI_CONTROL_MULTI_SELECT — Shows a select field where a user can select multiple values. Inherited from FieldConfig- UI_CONTROL_SINGLE_EXPANDABLE_SELECT — Shows an expandable select field which is useful when each selectable value belongs to a group. Inherited from FieldConfig

UI_CONTROL_MULTI_SELECT

The type "Array" is required for this ui control. To use this field assign it to the $uiControl property.

UI_CONTROL_SINGLE_EXPANDABLE_SELECT

To use this field assign it to the $uiControl property.

Properties

This class defines the following properties:

• $uiControl — Describes what HTML element should be used to manipulate the setting through Matomo (formerly Piwik)'s UI.
• $customUiControlTemplateFile — Defines a custom template file for a UI control.
• $customFieldComponent — Defines a custom Vue component to use for the internal field UI control.
• $uiControlAttributes — Name-value mapping of HTML attributes that will be added HTML form control, eg, array('size' => 3).
• $fullWidth — Makes field full width.
• $availableValues — The list of all available values for this setting.
• $introduction — Text that will appear above this setting's section in the Plugin Settings admin page.
• $description — Text that will appear directly underneath the setting title in the Plugin Settings admin page.
• $inlineHelp — Text that will appear next to the setting's section in the Plugin Settings admin page.
• $prepare — A closure that prepares the setting value.
• $validate — A closure that does some custom validation on the setting before the setting is persisted.
• $transform — A closure that transforms the setting value.
• $title — This setting's display name, for example, 'Refresh Interval'.
• $condition — Here you can define conditions so that certain form fields will be only shown when a certain condition is true.
• $validators ash; Here you can add one or multiple instances of Piwik\Validators\BaseValidator to avoid having to write the same validators over and over again in $validate.

$uiControl

Describes what HTML element should be used to manipulate the setting through Matomo's UI.

See Piwik\Plugin\Settings for a list of supported control types.

Signature

• It is a string value.

$customUiControlTemplateFile

Defines a custom template file for a UI control. This file should render a UI control and expose the value in a "formField.value" angular model. For an example see "plugins/CorePluginsAdmin/angularjs/form-field/field-text.html"

Signature

• It is a string value.

$customFieldComponent

Defines a custom Vue component to use for the internal field UI control. This should be an array with two keys:

• plugin: the name of the plugin that the UI control exists in.
• name: the name of the export for the component in the plugin's Vue UMD module.

Signature

• It is a string[] value.

$uiControlAttributes

Name-value mapping of HTML attributes that will be added HTML form control, eg, array('size' => 3). Attributes will be escaped before outputting.

Signature

• It is a array value.

$fullWidth

Makes field full width.

Useful for $field->uiControl = FieldConfig::UI_CONTROL_MULTI_TUPLE;

Signature

• It is a bool value.

$availableValues

The list of all available values for this setting. If null, the setting can have any value.

If supplied, this field should be an array mapping available values with their prettified display value. Eg, if set to array('nb_visits' => 'Visits', 'nb_actions' => 'Actions'), the UI will display Visits and Actions, and when the user selects one, Matomo will set the setting to nb_visits or nb_actions respectively.

The setting value will be validated if this field is set. If the value is not one of the available values, an error will be triggered.

Note: If a custom validator is supplied (see $validate), the setting value will not be validated.

Signature

• It can be one of the following types:
  • null
  • array

$introduction

Text that will appear above this setting's section in the Plugin Settings admin page.

Signature

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

$description

Text that will appear directly underneath the setting title in the Plugin Settings admin page. If set, should be a short description of the setting.

Signature

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

$inlineHelp

Text that will appear next to the setting's section in the Plugin Settings admin page. If set, it should contain information about the setting that is more specific than a general description, such as the format of the setting value if it has a special format.

Be sure to escape any user input as HTML can be used here.

Signature

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

$prepare

A closure that prepares the setting value. If supplied, this closure will be executed before the setting has been validated.

Example

$setting->prepare = function ($value, Setting $setting) {
    return mb_strtolower($value);
}

Signature

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

$validate

A closure that does some custom validation on the setting before the setting is persisted.

The closure should take two arguments: the setting value and the Setting instance being validated. If the value is found to be invalid, the closure should throw an exception with a message that describes the error.

Example

$setting->validate = function ($value, Setting $setting) {
    if ($value > 60) {
        throw new \Exception('The time limit is not allowed to be greater than 60 minutes.');
    }
}

Signature

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

$transform

A closure that transforms the setting value. If supplied, this closure will be executed after the setting has been validated.

Note: If a transform is supplied, the setting's $type has no effect. This means the transformation function will be responsible for casting the setting value to the appropriate data type.

Example

$setting->transform = function ($value, Setting $setting) {
    if ($value > 30) {
        $value = 30;
    }

    return (int) $value;
}

Signature

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

$title

This setting's display name, for example, 'Refresh Interval'.

Be sure to escape any user input as HTML can be used here.

Signature

• It is a string value.

$condition

Here you can define conditions so that certain form fields will be only shown when a certain condition is true. This condition is supposed to be evaluated on the client side dynamically. This way you can hide for example some fields depending on another field. For example if SiteSearch is disabled, fields to enter site search keywords is not needed anymore and can be disabled.

For example 'sitesearch', or 'sitesearch && !use_sitesearch_default' where 'sitesearch' and 'use_sitesearch_default' are both values of fields.

Signature

• It is a string value.

$validators

Here you can add one or multiple instances of Piwik\Validators\BaseValidator to avoid having to write the same validators over and over again in $validate.

Examples Want to require a value to be set? $fieldConfig->validators[] = new Piwik\Validators\NotEmpty();

Want to require an email? $fieldConfig->validators[] = new Piwik\Validators\NotEmpty(); $fieldConfig->validators[] = new Piwik\Validators\Email();

The core comes with a set of various validators that can be used.

Signature

• It is a Piwik\Validators\BaseValidator value.