Esta página describe las clases que se pueden utilizar para crear una vista de configuración de widget con campos de configuración personalizados. La vista de configuración del widget es la parte del widget que permite al usuario configurar los parámetros del widget para la presentación.
Clase principal del widget, extiende la clase base de todos los widgets del panel - CWidget. Requerido para sobrescribir el comportamiento predeterminado del widget.
La clase Widget debe ubicarse en el directorio raíz del widget (por ejemplo, zabbix/ui/modules/my_custom_widget).
Ejemplo de 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')
]
];
}
}
La clase WidgetForm extiende la clase por defecto CWidgetForm y contiene un conjunto de campos CWidgetField que son necesarios para definir la estructura de almacenamiento de la configuración del widget en la base de datos y gestionar la validación de entrada.
La clase WidgetForm debe ubicarse en el directorio includes. Si la clase tiene un nombre diferente, el nombre debe especificarse en el parámetro widget/form_class en el archivo manifest.json.
Ejemplo 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 {
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', _('Métrica')))
->setFlags(CWidgetField::FLAG_NOT_EMPTY | CWidgetField::FLAG_LABEL_ASTERISK)
->setMultiple(false)
)
->addField(
new CWidgetFieldTextBox('description', _('Descripción'))
)
->addField(
(new CWidgetFieldColor('chart_color', _('Color')))->setDefault('FF0000')
);
}
}
La clase CWidgetFormView es necesaria para especificar la lógica de presentación de los campos definidos en la clase WidgetForm, determinando su apariencia y comportamiento cuando se representan en la vista de configuración.
La clase CWidgetFormView admite los siguientes métodos:
La clase CWidgetFormView debe ubicarse en el directorio views.
Ejemplo de views/widget.edit.php
<?php
/**
* Mi vista de formulario de widget personalizada.
*
* @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(_('Configuración avanzada')))
->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();
Se puede utilizar una clase JavaScript para añadir comportamiento dinámico e interactividad a la vista de configuración del widget. Por ejemplo, puede inicializar un selector de color, definido en la clase CWidgetFormView.
La clase JavaScript debe cargarse con el formulario, por lo tanto, debe ser referenciada en la clase CWidgetFormView utilizando los métodos includeJsFile() y addJavaScript().
En el siguiente ejemplo, se crea inmediatamente una instancia de clase singleton y se almacena bajo el nombre window.my_custom_widget_form. Así, al abrir el formulario por segunda vez, se volverá a crear la instancia.
La clase JavaScript debe ubicarse en el directorio views.
Ejemplo de 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'); });
}
}
};
La clase CWidgetField es una clase base de la que se heredan todas las clases de campos de formulario (CWidgetFieldCheckBox, CWidgetFieldTextArea, CWidgetFieldRadioButtonList, etc.). Las clases que extienden CWidgetField son responsables de recibir, guardar y validar los valores de configuración del widget.
Las siguientes clases CWidgetField están disponibles.
Clase CWidgetField | Tipo de campo en base de datos | Descripción |
---|---|---|
CWidgetFieldCheckBox | int32 | Casilla de verificación única. |
CWidgetFieldCheckBoxList | array de int32 | Varias casillas de verificación bajo un solo campo de configuración. |
CWidgetFieldColor | string | Campo de selección de color. |
CWidgetFieldDatePicker | string | Campo de selección de fecha. |
CWidgetFieldHostPatternSelect | string | Campo de selección múltiple que permite seleccionar uno o varios equipos. Permite definir patrones de nombre de equipo (todos los equipos coincidentes serán seleccionados). |
CWidgetFieldIntegerBox | int32 | Campo para ingresar un número entero. Puede usarse para configurar valores mínimos y máximos. |
CWidgetFieldLatLng | string | Caja de texto que permite ingresar latitud, longitud y nivel de zoom del mapa separados por comas. |
CWidgetFieldMultiSelectAction | ID | Campo de selección múltiple para seleccionar acciones (de la lista de acciones definidas en Alertas → Acciones). |
CWidgetFieldMultiSelectGraph | ID | Campo de selección múltiple para seleccionar gráficos personalizados. |
CWidgetFieldMultiSelectGraphPrototype | ID | Campo de selección múltiple para seleccionar prototipos de gráficos personalizados. |
CWidgetFieldMultiSelectGroup | ID | Campo de selección múltiple para seleccionar grupos de equipos. |
CWidgetFieldMultiSelectHost | ID | Campo de selección múltiple para seleccionar equipos. |
CWidgetFieldMultiSelectItem | ID | Campo de selección múltiple para seleccionar métricas. |
CWidgetFieldMultiSelectItemPattern | ID | Campo de selección múltiple para seleccionar patrones de métricas. |
CWidgetFieldMultiSelectItemPrototype | ID | Campo de selección múltiple para seleccionar prototipos de métricas. |
CWidgetFieldMultiSelectMap | ID | Campo de selección múltiple para seleccionar mapas. |
CWidgetFieldMultiSelectMediaType | ID | Campo de selección múltiple para seleccionar tipos de medios. |
CWidgetFieldMultiSelectOverrideHost | ID | Campo de selección múltiple para seleccionar una fuente de datos (panel o widget) que contenga un equipo para el que el widget pueda mostrar datos. |
CWidgetFieldMultiSelectService | ID | Campo de selección múltiple para seleccionar servicios. |
CWidgetFieldMultiSelectSla | ID | Campo de selección múltiple para seleccionar SLAs. |
CWidgetFieldMultiSelectUser | ID | Campo de selección múltiple para seleccionar usuarios. |
CWidgetFieldNumericBox | string | Campo para ingresar un número flotante. |
CWidgetFieldRadioButtonList | int32 | Grupo de botones de opción que consiste en uno o más botones de opción. |
CWidgetFieldRangeControl | int32 | Control deslizante para seleccionar un valor de tipo entero. |
CWidgetFieldReference | string | Crea un identificador único para este widget en el panel. Se utiliza para referenciar este widget desde otros widgets. |
CWidgetFieldSelect | int32 | Caja de selección desplegable. |
CWidgetFieldSeverities | array de int32 | CWidgetFieldCheckBoxList preconfigurado con severidades de disparadores. |
CWidgetFieldTags | array de (string, int32, string) | Permite configurar una o más filas de filtro de etiquetas. |
CWidgetFieldTextArea | string | Área de texto para ingresar texto de varias líneas. |
CWidgetFieldTextBox | string | Caja de texto para ingresar texto de una sola línea. |
CWidgetFieldTimePeriod | array de string | Campo de selección de periodo de tiempo. |
CWidgetFieldTimeZone | string | Desplegable con zonas horarias. |
CWidgetFieldThresholds | array de (string, string) | Permite configurar pares de color y número. |
CWidgetFieldUrl | string | Caja de texto que permite ingresar URLs. |
Las siguientes clases CWidgetField han sido creadas para widgets particulares. Estas clases tienen casos de uso muy específicos, pero también pueden reutilizarse si es necesario.
Clase CWidgetField | Tipo de campo en base de datos | Descripción |
---|---|---|
CWidgetFieldColumnsList | array de (múltiples mixtos) | Para el widget Top equipos. Crea una tabla con columnas personalizadas de tipos permitidos. |
CWidgetFieldNavTree | string | Para el widget Árbol de navegación de mapas. Reemplaza la vista del widget en modo edición por el árbol de selección de mapas. |