[comment]: # aside:1

[comment]: # ({0a11f1a9-f7477fb0})
# Configuration

This page describes classes that can be used to create a widget configuration view with custom configuration fields.
The widget configuration view is the part of the widget that allows the user to configure widget parameters for [presentation](/presentation).

[comment]: # ({/0a11f1a9-f7477fb0})

[comment]: # ({68bbd84a-adf59b13})
### Widget

Primary widget class, extends the base class of all dashboard widgets - *CWidget*.
Required for overriding the default widget behavior.

The *Widget* class should be located in the root directory of the widget (for example, *zabbix/ui/modules/my_custom_widget*).

**Widget.php example**

```php
<?php

namespace Modules\MyCustomWidget;

use Zabbix\Core\CWidget;

class Widget extends CWidget {

    public const MY_CONSTANT = 0;

    public function getTranslationStrings(): array {
        return [
            'class.widget.js' => [
                'No data' => _('No data')
            ]
        ];
    }
}
```

[comment]: # ({/68bbd84a-adf59b13})

[comment]: # ({e5aad37e-1ff26877})
### WidgetForm

The *WidgetForm* class extends the default class *CWidgetForm* and contains a set of [*CWidgetField*](#cwidgetfield) fields
that are required for defining widget configuration storage structure in the database and handling input validation.

The *WidgetForm* class should be located in the *includes* directory.
If the class has a different name, the name should be specified in the [*widget/form_class*](/devel/modules/file_structure/manifest#widget) parameter in the *manifest.json* file.

**includes/WidgetForm.php example**

```php
<?php

namespace Modules\MyCustomWidget\Includes;

use Modules\MyCustomWidget\Widget;

use Zabbix\Widgets\{
    CWidgetField,
    CWidgetForm
};

use Zabbix\Widgets\Fields\{
    CWidgetFieldMultiSelectItem,
    CWidgetFieldTextBox,
    CWidgetFieldColor
};


class WidgetForm extends CWidgetForm {

    public const DEFAULT_COLOR_PALETTE = [
        'FF465C', 'B0AF07', '0EC9AC', '524BBC', 'ED1248', 'D1E754', '2AB5FF', '385CC7', 'EC1594', 'BAE37D',
        '6AC8FF', 'EE2B29', '3CA20D', '6F4BBC', '00A1FF', 'F3601B', '1CAE59', '45CFDB', '894BBC', '6D6D6D'
    ];

    public function addFields(): self {
        return $this
            ->addField(
                (new CWidgetFieldMultiSelectItem('itemid', _('Item')))
                    ->setFlags(CWidgetField::FLAG_NOT_EMPTY | CWidgetField::FLAG_LABEL_ASTERISK)
                    ->setMultiple(false)
            )
            ->addField(
                new CWidgetFieldTextBox('description', _('Description'))
            )
            ->addField(
                (new CWidgetFieldColor('chart_color', _('Color')))->setDefault('FF0000')
            );
    }
}
```

[comment]: # ({/e5aad37e-1ff26877})

[comment]: # ({3ca7a0e4-61f06fc3})
### CWidgetFormView

The *CWidgetFormView* class is required for specifying the presentation logic of the fields defined in the *WidgetForm* class,
determining their appearance and behavior when rendered in the configuration view.

The *CWidgetFormView* class supports the following methods:

-   *addField()* - receives an instance of the *CWidgetFieldView* class as a parameter;
    each [*CWidgetField*](#cwidgetfield) class, has a respective *CWidgetFieldView* class for using in the widget configuration view.
-   *addFieldset()* - receives an instance of the *CWidgetFieldsGroupView* class that combines fields into a collapsible container.
-   *addFieldsGroup()* - receives an instance of *CWidgetFormFieldsetCollapsibleView* that visually (with a border) combines fields into a group.
-   *includeJsFile()* - allows to add a JavaScript file to the widget configuration view.
-   *addJavaScript()* - allows to add inline JavaScript that will be executed as soon as the widget configuration view is loaded.

The *CWidgetFormView* class should be located in the *views* directory.

**views/widget.edit.php example**

```php
<?php

/**
 * My custom widget form view.
 *
 * @var CView $this
 * @var array $data
 */

use Modules\MyCustomWidget\Includes\WidgetForm;

(new CWidgetFormView($data))
    ->addField(
        (new CWidgetFieldMultiSelectItemView($data['fields']['itemid']))->setPopupParameter('numeric', true)
    )
    ->addFieldset(
        (new CWidgetFormFieldsetCollapsibleView(_('Advanced configuration')))
            ->addField(
                new CWidgetFieldTextBoxView($data['fields']['description'])
            )
            ->addField(
                new CWidgetFieldColorView($data['fields']['chart_color'])
            )
    )
    ->includeJsFile('widget.edit.js.php')
    ->addJavaScript('my_custom_widget_form.init('.json_encode([
        'color_palette' => WidgetForm::DEFAULT_COLOR_PALETTE
    ]).');')
    ->show();
```

[comment]: # ({/3ca7a0e4-61f06fc3})

[comment]: # ({d7c94075-d1c62429})
### JavaScript

A JavaScript class can be used to add dynamic behavior and interactivity to the widget configuration view.
For example, you can initialize a color picker, defined in the [*CWidgetFormView*](#cwidgetformview) class.

The JavaScript class should be loaded with the form, therefore it should be referenced in the [*CWidgetFormView*](#cwidgetformview) class by using the methods *includeJsFile()* and *addJavaScript()*.

In the example below, a singleton class instance is immediately created and stored under the *window.my_custom_widget_form* name.
Thus, opening the form for the second time will re-create the instance.

The JavaScript class should be located in the *views* directory.

**views/widget.edit.js.php example**

```php
<?php

use Modules\MyCustomWidget\Widget;

?>

window.my_custom_widget_form = new class {

    init({color_palette}) {
        colorPalette.setThemeColors(color_palette);

        for (const colorpicker of jQuery('.<?= ZBX_STYLE_COLOR_PICKER ?> input')) {
            jQuery(colorpicker).colorpicker();
        }

        const overlay = overlays_stack.getById('widget_properties');

        for (const event of ['overlay.reload', 'overlay.close']) {
            overlay.$dialogue[0].addEventListener(event, () => { jQuery.colorpicker('hide'); });
        }
    }
};
```

[comment]: # ({/d7c94075-d1c62429})

[comment]: # ({2afcae2e-708ecb6b})
### CWidgetField

The *CWidgetField* class is a base class from which all form field classes (*CWidgetFieldCheckBox*, *CWidgetFieldTextArea*, *CWidgetFieldRadioButtonList*, etc.) are inherited.
Classes extending *CWidgetField* are responsible for receiving, saving, and validating widget configuration values.

The following *CWidgetField* classes are available.

|CWidgetField class|Database field type|Description|
|----|----|----------|
|*CWidgetFieldCheckBox*|int32|Single checkbox.|
|*CWidgetFieldCheckBoxList*|array of int32|Multiple checkboxes under a single configuration field.|
|*CWidgetFieldColor*|string|Color selection field.|
|*CWidgetFieldDatePicker*|string|Date selection field.|
|*CWidgetFieldIntegerBox*|int32|Field to enter an integer. Can be used to configure minimum and maximum values.|
|*CWidgetFieldLatLng*|string|Text box that allows to enter comma-separated latitude, longitude, and map zoom level.|
|*CWidgetFieldMultiSelect*|-|Base class for multiselect fields, extended by all *CWidgetFieldMultiSelect\** classes.|
|*CWidgetFieldMultiSelectAction*|ID|Multiselect field for selecting actions from the list of actions defined in *Alerts → Actions*.|
|*CWidgetFieldMultiSelectGraph*|ID|Multiselect field for selecting custom graphs.|
|*CWidgetFieldMultiSelectGraphPrototype*|ID|Multiselect field for selecting custom graph prototypes.|
|*CWidgetFieldMultiSelectGroup*|ID|Multiselect field for selecting host groups.|
|*CWidgetFieldMultiSelectHost*|ID|Multiselect field for selecting hosts.|
|*CWidgetFieldMultiSelectHostInventory*|array of int32|Multiselect field for selecting host inventory fields.|
|*CWidgetFieldMultiSelectItem*|ID|Multiselect field for selecting items.|
|*CWidgetFieldMultiSelectItemPrototype*|ID|Multiselect field for selecting item prototypes.|
|*CWidgetFieldMultiSelectMap*|ID|Multiselect field for selecting maps.|
|*CWidgetFieldMultiSelectMediaType*|ID|Multiselect field for selecting media types.|
|*CWidgetFieldMultiSelectOverrideHost*|ID|Multiselect field for selecting a data source for hosts from a dashboard or another widget.|
|*CWidgetFieldMultiSelectService*|ID|Multiselect field for selecting services.|
|*CWidgetFieldMultiSelectSla*|ID|Multiselect field for selecting SLAs.|
|*CWidgetFieldMultiSelectUser*|ID|Multiselect field for selecting users.|
|*CWidgetFieldNavTree*|string|Stores a navigation tree structure of maps for use in the *Map navigation tree* widget.|
|*CWidgetFieldNumericBox*|string|Field to enter a float number.|
|*CWidgetFieldPatternSelect*|-|Base class for pattern select fields, extended by all *CWidgetPatternSelect\** classes.|
|*CWidgetFieldPatternSelectHost*|string|Multiselect field for selecting hosts. Supports host name patterns.|
|*CWidgetFieldPatternSelectItem*|string|Multiselect field for selecting items. Supports item name patterns.|
|*CWidgetFieldRadioButtonList*|int32|Radio box group that consists of one or more radio boxes.|
|*CWidgetFieldRangeControl*|int32|Slider to select an integer type value.|
|*CWidgetFieldReference*|string|Stores a unique identifier for this widget on the dashboard; used for widget communication.|
|*CWidgetFieldSelect*|int32|Dropdown select box.|
|*CWidgetFieldSeverities*|array of int32|*CWidgetFieldCheckBoxList* preset with trigger severities.|
|*CWidgetFieldSparkline*|array of (multiple mixed)|Allows configuring a sparkline chart.|
|*CWidgetFieldTags*|array of (string, int32, string)|Allows to configure one or more tag filter rows.|
|*CWidgetFieldTextArea*|string|Text area for entering multi-line text.|
|*CWidgetFieldTextBox*|string|Text box for entering single-line text.|
|*CWidgetFieldThresholds*|array of (string, string)|Allows configuring color and number pairs.|
|*CWidgetFieldTimePeriod*|array of string|Time period selecting field.|
|*CWidgetFieldTimeZone*|string|Dropdown with timezones.|
|*CWidgetFieldUrl*|string|Text box that allows to enter URLs.|

::: noteclassic
The maximum length for `int32` fields is 10 characters, `ID` fields 20 characters, and `string` fields 2048 characters.
For composite types (e.g., `array of (string, int32, string)`), the limit applies to each element individually.
Field-specific length restrictions can be set using methods such as `setMaxLength()`.
:::

[comment]: # ({/2afcae2e-708ecb6b})