Configurazione

Questa pagina descrive le classi che possono essere utilizzate per creare una vista di configurazione del widget con campi di configurazione personalizzati. La vista di configurazione del widget è la parte del widget che consente all'utente di configurare i parametri del widget per la presentazione.

Widget

La classe widget primaria, estende la classe base di tutti i widget della dashboard - CWidget. Necessaria per sovrascrivere il comportamento predefinito del widget.

La classe Widget deve trovarsi nella directory principale del widget (ad esempio, zabbix/ui/modules/my_custom_widget).

Esempio di Widget.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')
]
];
}
}

WidgetForm

La classe WidgetForm estende la classe predefinita CWidgetForm e contiene un insieme di campi CWidgetField necessari per definire la struttura di archiviazione della configurazione del widget nel database e gestire la validazione dell'input.

La classe WidgetForm deve trovarsi nella directory includes. Se la classe ha un nome diverso, il nome deve essere specificato nel parametro widget/form_class nel file manifest.json.

Esempio di includes/WidgetForm.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')
            );
    }
}

CWidgetFormView

La classe CWidgetFormView è necessaria per specificare la logica di presentazione dei campi definiti nella classe WidgetForm, determinando il loro aspetto e comportamento durante il rendering nella vista di configurazione.

La classe CWidgetFormView supporta i seguenti metodi:

• addField() - riceve come parametro un'istanza della classe CWidgetField; ogni classe CWidgetField dispone di una classe CWidgetFieldView corrispondente da utilizzare nella vista di configurazione del widget.
• addFieldset() - riceve un'istanza della classe CWidgetFieldsGroupView, che combina i campi in un contenitore comprimibile.
• addFieldsGroup() - riceve un'istanza di CWidgetFormFieldsetCollapsibleView, che combina visivamente (con un bordo) i campi in un gruppo.
• includeJsFile() - consente di aggiungere un file JavaScript alla vista di configurazione del widget.
• addJavaScript() - consente di aggiungere codice JavaScript inline che verrà eseguito non appena la vista di configurazione del widget viene caricata.

La classe CWidgetFormView deve trovarsi nella directory views.

Esempio di views/widget.edit.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();

JavaScript

Una classe JavaScript può essere utilizzata per aggiungere comportamento dinamico e interattività alla vista di configurazione del widget. Ad esempio, è possibile inizializzare un selettore di colori, definito nella classe CWidgetFormView.

La classe JavaScript deve essere caricata insieme al modulo, pertanto deve essere referenziata nella classe CWidgetFormView utilizzando i metodi includeJsFile() e addJavaScript().

Nell'esempio seguente, un'istanza singleton della classe viene creata immediatamente e memorizzata con il nome window.my_custom_widget_form. Pertanto, aprendo il modulo una seconda volta, l'istanza verrà ricreata.

La classe JavaScript deve trovarsi nella directory views.

Esempio di views/widget.edit.js.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'); });
        }
    }
};

CWidgetField

La classe CWidgetField è una classe di base da cui ereditano tutte le classi dei campi dei moduli (CWidgetFieldCheckBox, CWidgetFieldTextArea, CWidgetFieldRadioButtonList, ecc.). Le classi che estendono CWidgetField sono responsabili della ricezione, del salvataggio e della convalida dei valori di configurazione del widget.

Sono disponibili le seguenti classi CWidgetField.