Configuração

Esta página descreve as classes que podem ser usadas para criar uma visualização de configuração do widget com campos de configuração personalizados. A exibição de configuração do widget é a parte do widget que permite ao usuário configurar os parâmetros do widget para presentation.

Widget

Classe primária de widget, estende a classe base de todos os widgets do painel - CWidget. Necessário para substituir o comportamento padrão do widget.

A classe Widget deve estar localizada no diretório raiz do widget (por exemplo, ui/modules/my_custom_widget).

Exemplo de Widget.php

<?php
       
       namespace Modules\MyCustomWidget;
       
       use Zabbix\Core\CWidget;
       
       class Widget extends CWidget {
       
           public const MY_CONSTANT = 0;
       
           função pública getTranslationStrings(): array {
               retorna [
                   'class.widget.js' => [
                       'Sem dados' => _('Sem dados')
                   ]
               ];
           }
       }

WidgetForm

A classe WidgetForm estende a classe padrão CWidgetForm e contém um conjunto de campos CWidgetField que são necessários para definir a estrutura de armazenamento da configuração do widget no banco de dados e manipular a validação de entrada.

A classe WidgetForm deve estar localizada no diretório includes. Se a classe tiver um nome diferente, o nome deverá ser especificado no parâmetro widget/form_class no arquivo manifest.json.

Exemplo de 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 {
       
           função pública addFields(): self {
               return $this
                   ->addField(
                       (novo CWidgetFieldMultiSelectItem('itemid', _('Item')))
                           ->setFlags(CWidgetField::FLAG_NOT_EMPTY | CWidgetField::FLAG_LABEL_ASTERISK)
                           ->setMultiple(false)
                           ->setFilterParameter('numeric', true)
                   )
                   ->addField(
                       new CWidgetFieldTextBox('description', _('Description'))
                   )
                   ->addField(
                       (new CWidgetFieldColor('chart_color', _('Color')))->setDefault('FF0000')
                   );
           }
       }

CWidgetFormView

A classe CWidgetFormView é necessária para especificar a lógica de apresentação dos campos definidos na classe WidgetForm, determinando sua aparência e comportamento quando renderizados na exibição de configuração.

A classe CWidgetFormView é compatível com os seguintes métodos:

  • addField() - recebe uma instância da classe CWidgetFieldView como parâmetro; Cada classe CWidgetField tem uma respectiva classe CWidgetFieldView para uso na exibição de configuração do widget.
  • includeJsFile() - permite adicionar um arquivo JavaScript à visualização de configuração do widget.
  • addJavaScript() - permite adicionar JavaScript em linha que será executado assim que a visualização de configuração do widget for carregada.

A classe CWidgetFormView deve estar localizada no diretório views.

Exemplo de views/widget.edit.php

<?php
           
       /**
        * Minha visualização de formulário de widget personalizado.
        *
        * @var CView $this
        * @var array $data
        */
       
       use Zabbix\Widgets\Fields\CWidgetFieldGraphDataSet;
       
       (novo CWidgetFormView($data))
           ->addField(
               new CWidgetFieldMultiSelectItemView($data['fields']['itemid'], $data['captions']['items']['itemid'])
           )
           ->addField(
               new CWidgetFieldTextBoxView($data['fields']['description']),
               'js-advanced-configuration'
           )
           ->addField(
               new CWidgetFieldColorView($data['fields']['chart_color']),
               'js-advanced-configuration'
           )
           ->includeJsFile('widget.edit.js.php')
           ->addJavaScript('my_widget_form.init('.json_encode([
               'color_palette' => CWidgetFieldGraphDataSet::DEFAULT_COLOR_PALETTE
           ], JSON_THROW_ON_ERROR).');')
           ->show();

JavaScript

Uma classe JavaScript pode ser usada para adicionar comportamento dinâmico e interatividade à exibição de configuração do widget. Por exemplo, você pode inicializar um seletor de cores, definido na classe CWidgetFormView.

A classe JavaScript deve ser carregada com o formulário, portanto, deve ser referenciada na classe CWidgetFormView usando os métodos includeJsFile() e addJavaScript().

No exemplo abaixo, uma instância de classe singleton é imediatamente criada e armazenada com o nome window.my_custom_widget_form. Assim, ao abrir o formulário pela segunda vez, a instância será recriada.

A classe JavaScript deve estar localizada no diretório views.

Exemplo de views/widget.edit.js.php

<?php
       
       use Modules\LessonGaugeChart\Widget;
       
       ?>
       
       window.widget_lesson_gauge_chart_form = new class {
       
           init({paleta_de_cor}) {
               this._advanced_configuration = document.getElementById('adv_conf');
       
               this._advanced_configuration.addEventListener('change', () => this.updateForm());
       
               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'); });
               }
       
               this.updateForm();
           }
       
           updateForm() {
               const show_advanced_configuration = this._advanced_configuration.checked;
       
               for (const element of this._form.querySelectorAll('.js-advanced-configuration')) {
                   element.style.display = show_advanced_configuration ? '' : 'none';
               }
           }
       };

CWidgetField

A classe CWidgetField é uma classe base da qual todas as classes de campo de formulário (CWidgetFieldCheckBox, CWidgetFieldTextArea, CWidgetFieldRadioButtonList etc.) são herdadas. As classes que estendem CWidgetField são responsáveis por receber, salvar e validar os valores de configuração do widget.

As seguintes classes CWidgetField estão disponíveis.

CWidgetField class Database field type Description
CWidgetFieldCheckBox int32 Caixa de seleção única
CWidgetFieldCheckBoxList array of int32 Múltiplas caixas de seleção em um único campo de configuração
CWidgetFieldColor string Campo de seleção de cores
CWidgetFieldDatePicker string Campo de seleção de data
*Campo de seleção múltipla que permite selecionar um ou vários hosts. Suporta a definição de padrões de nome de host (todos os hosts correspondentes serão selecionados).
CWidgetFieldIntegerBox int32 Campo para inserir um número inteiro. Pode ser usado para configurar valores mínimos e máximos.
CWidgetFieldLatLng string Caixa de texto que permite inserir latitude, longitude e nível de zoom do mapa separados por vírgula.
CWidgetFieldMultiSelectAction ID Campo de seleção múltipla para selecionar ações (da lista de ações definidas em Alerts → Actions).
CWidgetFieldMultiSelectGraph ID Campo de seleção múltipla para selecionar gráficos personalizados.
CWidgetFieldMultiSelectGraphPrototype ID Campo de seleção múltipla para selecionar protótipos de gráficos personalizados.
CWidgetFieldMultiSelectGroup ID Campo de seleção múltipla para selecionar grupos de hosts.
CWidgetFieldMultiSelectHost ID Campo de seleção múltipla para selecionar hosts.
CWidgetFieldMultiSelectItem ID Campo de seleção múltipla para selecionar itens
CWidgetFieldMultiSelectItemPrototype ID Campo de seleção múltipla para selecionar protótipos de itens
CWidgetFieldMultiSelectMediaType ID Campo de seleção múltipla para selecionar tipos de mídia.
CWidgetFieldMultiSelectService ID Campo de seleção múltipla para selecionar serviços.
CWidgetFieldMultiSelectSla ID Campo de seleção múltipla para selecionar SLAs
CWidgetFieldMultiSelectUser ID Campo de seleção múltipla para selecionar usuários
CWidgetFieldNumericBox string Campo para inserir um número flutuante.
CWidgetFieldRadioButtonList int32 Grupo de caixas de rádio que consiste em uma ou mais caixas de rádio
CWidgetFieldRangeControl int32 Controle deslizante para selecionar um valor do tipo inteiro.
CWidgetFieldSelect int32 Caixa de seleção suspensa
CWidgetFieldSeverities Array de int32 CWidgetFieldCheckBoxList predefinido com severidades de acionamento.
CWidgetFieldTags array of (string, int32, string) Permite configurar uma ou mais linhas de filtro de tags.
CWidgetFieldTextArea string Área de texto para inserir texto de várias linhas.
CWidgetFieldTextBox string Caixa de texto para inserir texto de uma única linha
CWidgetFieldTimeZone string Dropdown com fusos horários
CWidgetFieldUrl string Caixa de texto que permite inserir URLs

As seguintes classes CWidgetField foram criadas para widgets específicos. Essas classes têm casos de uso muito específicos, mas também podem ser reutilizadas, se necessário.

Classe CWidgetField Tipo de campo de banco de dados Descrição
CWidgetFieldColumnsList array of (multiple mixed) Para o widget Top hosts. Crie uma tabela com colunas personalizadas de tipos permitidos.
CWidgetFieldGraphDataSet array of (multiple mixed) Para o widget Graph. Defina a configuração do conjunto de dados e todas as opções relacionadas.
CWidgetFieldGraphOverride array of (multiple mixed) Para o widget Graph. Configurar substituições para hosts/itens específicos. Qualquer configuração de conjunto de dados pode ser substituída.
CWidgetFieldNavTree string Para o widget Map navigation tree. Substitui a visualização do widget no modo de edição pela árvore de seleção de mapas.
CWidgetFieldReference string Para o widget Árvore de navegação do mapa. Cria um identificador exclusivo para esse widget no painel. Ele é usado para fazer referência a esse widget em outros widgets.
CWidgetFieldSelectResource ID Para o widget Map. Permite selecionar o mapa da rede Zabbix.
CWidgetFieldThresholds array of (string, string) Para o widget Top hosts. Permite configurar pares de cores e números.
CWidgetFieldWidgetSelect string Para o widget Map. Permite selecionar uma árvore de navegação de mapa no painel atual. Deve ser usado em combinação com CWidgetFieldReference no widget Map navigation tree.