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, determinandone l'aspetto e il comportamento quando vengono renderizzati nella vista di configurazione.

La classe CWidgetFormView supporta i seguenti metodi:

• addField() - riceve come parametro un'istanza della classe CWidgetFieldView; ogni classe CWidgetField ha una rispettiva classe CWidgetFieldView 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 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 del modulo (CWidgetFieldCheckBox, CWidgetFieldTextArea, CWidgetFieldRadioButtonList, ecc.). Le classi che estendono CWidgetField sono responsabili della ricezione, del salvataggio e della validazione dei valori di configurazione del widget.

Sono disponibili le seguenti classi CWidgetField.

Le seguenti classi CWidgetField sono state create per widget specifici. Queste classi hanno casi d'uso molto specifici, ma possono anche essere riutilizzate se necessario.