Áú»¢¶Ä²©

20 ²Ñ¨®»å³Ü±ô´Ç²õ

¶Ù±ð²õ³¦°ù¾±±è³¦¾±¨®²Ô general

Es posible mejorar la funcionalidad de la interfaz de Áú»¢¶Ä²© agregando m¨®dulos de terceros o desarrollando sus propios m¨®dulos sin necesidad de cambiar el c¨®digo fuente de Áú»¢¶Ä²©.

Tenga en cuenta que el c¨®digo del m¨®dulo se ejecutar¨¢ con los mismos privilegios que el c¨®digo fuente de Áú»¢¶Ä²©. Esto significa:

  • Los m¨®dulos de terceros pueden ser perjudiciales. Debe confiar en los m¨®dulos que instala;
  • Los errores en el c¨®digo de un m¨®dulo de terceros pueden bloquear la interfaz. Si esto sucede, simplemente elimine el c¨®digo del m¨®dulo de la interfaz. Tan pronto como recargue la interfaz de Áú»¢¶Ä²©, ver¨¢ una nota que dice que algunos de los m¨®dulos est¨¢n ausentes. Ir a administraci¨®n del m¨®dulo (en ´¡»å³¾¾±²Ô¾±²õ³Ù°ù²¹³¦¾±¨®²Ô ¡ú General ¡ú ²Ñ¨®»å³Ü±ô´Ç²õ) y haga clic en Escanear directorio nuevamente para eliminar m¨®dulos inexistentes de la base de datos.

±õ²Ô²õ³Ù²¹±ô²¹³¦¾±¨®²Ô

Lea siempre el manual de instalaci¨®n de un m¨®dulo en particular. Se recomienda instalar nuevos m¨®dulos uno por uno para detectar fallos f¨¢cilmente.

Justo antes de instalar un m¨®dulo:

  • Aseg¨²rese de haber descargado el m¨®dulo de una fuente confiable. La instalaci¨®n de c¨®digo da?ino puede tener consecuencias, como la p¨¦rdida de datos. p¨¦rdida
  • Se pueden instalar diferentes versiones del mismo m¨®dulo (mismo ID) en paralelo, pero solo se puede habilitar una versi¨®n a la vez

Pasos para instalar un m¨®dulo:

  • Desempaquete su m¨®dulo dentro de su propia carpeta en la carpeta modules de la interfaz de Áú»¢¶Ä²©
  • Aseg¨²rese de que la carpeta de su m¨®dulo contenga al menos el archivo manifest.json
  • Vaya a administraci¨®n del m¨®dulo y haga clic en el bot¨®n Escanear directorio
  • El nuevo m¨®dulo aparecer¨¢ en la lista junto con su versi¨®n, autor, descripci¨®n y estado
  • Habilite el m¨®dulo haciendo clic en su estado

Soluci¨®n de problemas:

|Problema|Soluci¨®n| |---------|------------------------------------------------ -| |El m¨®dulo no apareci¨® en la lista|Aseg¨²rese de que el archivo manifest.json exista en la carpeta modules/your-module/ de la interfaz de Áú»¢¶Ä²©. Si es as¨ª, significa que el m¨®dulo no se adapta a la versi¨®n actual de Áú»¢¶Ä²©. Si el archivo manifest.json no existe, probablemente lo hayas descomprimido en el directorio equivocado.| |La interfaz fall¨®|El c¨®digo del m¨®dulo no es compatible con la versi¨®n actual de Áú»¢¶Ä²© o la configuraci¨®n del servidor. Elimine los archivos del m¨®dulo y vuelva a cargar la interfaz. Ver¨¢ un aviso de que algunos m¨®dulos est¨¢n ausentes. Vaya a ´¡»å³¾¾±²Ô¾±²õ³Ù°ù²¹³¦¾±¨®²Ô de m¨®dulos y haga clic en Escanear directorio nuevamente para eliminar m¨®dulos inexistentes de la base de datos.| |Aparece un mensaje de error sobre un espacio de nombres, ID o acciones id¨¦nticos|Un nuevo m¨®dulo intent¨® registrar un espacio de nombres, ID o acciones que ya est¨¢n registrados por otros m¨®dulos habilitados. Deshabilite el m¨®dulo en conflicto (mencionado en el mensaje de error) antes de habilitar el nuevo.| |Aparecen mensajes de error t¨¦cnico|Reportar errores al desarrollador del ³¾¨®»å³Ü±ô´Ç.|

Desarrollo de m¨®dulos

Los m¨®dulos est¨¢n escritos en lenguaje PHP. Modelo-vista-controlador (MVC) Se prefiere el dise?o de patrones de software, ya que tambi¨¦n se utiliza en la interfaz Áú»¢¶Ä²© y facilitar¨¢ el desarrollo. La tipificaci¨®n estricta de PHP tambi¨¦n es recomendada pero no obligatoria.

Tenga en cuenta que con los m¨®dulos puede agregar f¨¢cilmente nuevos elementos de men¨² y vistas y acciones respectivas a la interfaz de Áú»¢¶Ä²©. Actualmente no es posible registrar una nueva API o crear nuevas tablas de bases de datos a trav¨¦s de m¨®dulos.

Estructura del m¨®dulo

Cada m¨®dulo es un directorio (ubicado dentro del directorio modules) con subdirectorios que contienen controladores, vistas y cualquier otro c¨®digo:

example_module_directory/           (obligatorio)
           manifest.json                   (obligatorio)  Metadatos y definici¨®n de acci¨®n.
           Module.php                                  Inicializaci¨®n del m¨®dulo y manejo de eventos.
           actions/                                    Archivos del controlador de acciones.
               SomethingView.php
               SomethingCreate.php
               SomethingDelete.php
               data_export/                                 
                   ExportAsXml.php
                   ExportAsExcel.php
           views/                                      Archivos de vista.
               example.something.view.php
               example.something.delete.php
               js/                                     Archivos JavaScript usados en vistas.
                   example.something.view.js.php
           partials/                                   Archivos parciales de vistas.
               example.something.reusable.php
               js/                                     Archivos JavaScript usados en los parciales.
                   example.something.reusable.js.php

Como puede ver, el ¨²nico archivo obligatorio dentro del m¨®dulo personalizado El directorio es manifest.json. El m¨®dulo no se registrar¨¢ sin esto. archivo. Module.php es responsable de registrar los elementos del men¨² y procesar eventos como 'onBeforeAction' y 'onTerminate'. El Los directorios actions, views y partials contienen PHP y JavaScript c¨®digo necesario para las acciones del ³¾¨®»å³Ü±ô´Ç.

Convenio de denominaci¨®n

Antes de crear un m¨®dulo, es importante acordar la convenci¨®n de los nombres para diferentes elementos del m¨®dulo, como directorios y archivos, de forma que podamos mantener las cosas bien organizadas. Tambi¨¦n puede encontrar ejemplos arriba, en la secci¨®n Estructura del m¨®dulo.

Elemento Reglas de nomenclatura Ejemplo
Directorio del m¨®dulo min¨²sculas [a-z], gui¨®n bajo y d¨ªgitos decimales ejemplo_v2
Subdirectorios de acciones Min¨²sculas [a-z] y car¨¢cter de subrayado datos_export
Archivos de acci¨®n CamelCase, que termina con el tipo de acci¨®n SomethingView.php
Vista y archivos parciales [a-z] en min¨²scula
Palabras separadas por un punto
Con el prefijo ³¾¨®»å³Ü±ô´Ç. seguido del nombre del m¨®dulo
Terminando con el tipo de acci¨®n y la extensi¨®n de archivo .php
³¾¨®»å³Ü±ô´Ç.ejemplo .algo.vista.php
Archivos Javascript Se aplican las mismas reglas que para los archivos de vista y parciales, excepto la extensi¨®n de archivo .js.php. module.example.something.view.js.php

Tenga en cuenta que el prefijo 'module' y la inclusi¨®n del nombre son obligatorios para las vistas y los nombres de archivos parciales, a menos que necesite anular las vistas principales de Áú»¢¶Ä²© o los parciales. Sin embargo, esta regla no se aplica a los nombres de archivos de acciones.

Preparaci¨®n del manifiesto

Se espera que cada m¨®dulo tenga un archivo manifest.json con los siguientes campos en formato JSON:

±Ê²¹°ù¨¢³¾±ð³Ù°ù´Ç Obligatorio Tipo Predeterminado ¶Ù±ð²õ³¦°ù¾±±è³¦¾±¨®²Ô
manifest_version ³§¨ª Doble - Versi¨®n del manifiesto del ³¾¨®»å³Ü±ô´Ç. La versi¨®n actualmente admitida es 1.
id ³§¨ª Cadena - ID del ³¾¨®»å³Ü±ô´Ç. S¨®lo se puede habilitar un m¨®dulo con ID determinado al mismo tiempo.
name ³§¨ª Cadena - Nombre del m¨®dulo como se muestra en la secci¨®n ´¡»å³¾¾±²Ô¾±²õ³Ù°ù²¹³¦¾±¨®²Ô.
version ³§¨ª Cadena - Versi¨®n del m¨®dulo como se muestra en la secci¨®n ´¡»å³¾¾±²Ô¾±²õ³Ù°ù²¹³¦¾±¨®²Ô.
namespace ³§¨ª Cadena - Espacio de nombres PHP para Module.php y clases de acci¨®n.
author No Cadena "" Autor del m¨®dulo como se muestra en la secci¨®n ´¡»å³¾¾±²Ô¾±²õ³Ù°ù²¹³¦¾±¨®²Ô.
url No Cadena "" URL del m¨®dulo como se muestra en la secci¨®n ´¡»å³¾¾±²Ô¾±²õ³Ù°ù²¹³¦¾±¨®²Ô.
description No Cadena "" ¶Ù±ð²õ³¦°ù¾±±è³¦¾±¨®²Ô del m¨®dulo como se muestra en la secci¨®n ´¡»å³¾¾±²Ô¾±²õ³Ù°ù²¹³¦¾±¨®²Ô.
actions No Objeto {} Acciones para registrarse en este ³¾¨®»å³Ü±ô´Ç. Ver Acciones.
config No Objeto {} °ä´Ç²Ô´Ú¾±²µ³Ü°ù²¹³¦¾±¨®²Ô del ³¾¨®»å³Ü±ô´Ç.

Como referencia, consulte un ejemplo de manifest.json en la secci¨®n Referencia.

Acciones

El m¨®dulo tendr¨¢ control sobre las acciones de la interfaz definidas dentro del objeto actions en el archivo manifest.json. De esta manera se definen nuevas acciones. De la misma manera puede redefinir acciones existentes. Cada clave de las acciones debe representar el nombre de la acci¨®n y el valor correspondiente debe contener las claves class y, opcionalmente, layout y view.

Una acci¨®n est¨¢ definida por cuatro contrapartes: nombre, controlador, vista y disposici¨®n. La validaci¨®n y preparaci¨®n de datos generalmente se realiza en el controlador, el formateo de salida se realiza en la vista o parciales, y el dise?o se encarga de decorar la p¨¢gina con elementos como men¨², encabezado, pie de p¨¢gina y otros.

Las acciones del m¨®dulo deben definirse en el archivo manifest.json como un objeto actions:

±Ê²¹°ù¨¢³¾±ð³Ù°ù´Ç Obligatorio Tipo Predeterminado ¶Ù±ð²õ³¦°ù¾±±è³¦¾±¨®²Ô
key ³§¨ª Cadena - Nombre de la acci¨®n, en min¨²sculas [a-z], separando las palabras con punto.
class ³§¨ª Cadena - Nombre de la clase de acci¨®n, incluida la ruta del subdirectorio (si se usa) dentro del directorio acciones.
layout No Cadena "layout.htmlpage" Dise?o de acci¨®n.
view No Cadena nulo Vista de acci¨®n.

Hay varios dise?os predefinidos, como layout.json o dise?o.xml. Est¨¢n destinados a acciones que producen diferentes resultados que un HTML. Puede explorar dise?os predefinidos en el directorio app/views/ o incluso crea el suyo propio.

A veces es necesario redefinir solo la parte de vista de alguna acci¨®n dejando el controlador intacto. En tal caso simplemente coloque la vista necesaria y/o los archivos parciales dentro del directorio views del ³¾¨®»å³Ü±ô´Ç.

Como referencia, consulte un archivo de controlador de acciones de ejemplo en la secci¨®n Referencia. Por favor no dudes en explorar Acciones actuales del c¨®digo fuente de Áú»¢¶Ä²©, ubicadas en el directorio app/.

Module.php

Este archivo PHP opcional tambi¨¦n es responsable de la inicializaci¨®n del ³¾¨®»å³Ü±ô´Ç. como manejo de eventos. Se espera que la clase 'M¨®dulo' est¨¦ definida en este archivo, extendiendo la clase base \Core\CModule. La clase M¨®dulo debe ser definido dentro del espacio de nombres especificado en el archivo manifest.json.

<?php
       
       namespace Modules\Example;
       use Core\CModule as BaseModule;
       
       class Module extends BaseModule {
           ...
       }

Como referencia, consulte un ejemplo de Module.php en la secci¨®n Referencia.

Referencia

Esta secci¨®n contiene versiones b¨¢sicas de diferentes elementos del ³¾¨®»å³Ü±ô´Ç.introducido en las secciones anteriores.

manifest.json

{
           "manifest_version": 1.0,
           "id": "example_module",
           "name": "Example module",
           "version": "1.0",
           "namespace": "Example",
           "author": "John Smith",
           "url": "http://module.example.com",
           "description": "Short description of the module.",
           "actions": {
               "example.something.view": {
                   "class": "SomethingView",
                   "view": "module.example.something.view"
               },
               "example.something.create": {
                   "class": "SomethingCreate",
                   "layout": null
               },
               "example.something.delete": {
                   "class": "SomethingDelete",
                   "layout": null
               },
               "example.something.export.xml": {
                   "class": "data_export/ExportAsXml",
                   "layout": null
               },
               "example.something.export.excel": {
                   "class": "data_export/ExportAsExcel",
                   "layout": null
               }
           },
           "config": {
               "username": "john_smith"
           }
       }

Module.php

<?php declare(strict_types = 1);
       
       namespace Modules\Example;
       
       use APP;
       use CController as CAction;
       
       /**
        * Please see Core\CModule class for additional reference.
        */
       class Module extends \Core\CModule {
       
           /**
            * Initialize module.
            */
           public function init(): void {
               // Initialize main menu (CMenu class instance).
               APP::Component()->get('menu.main')
                   ->findOrAdd(_('Reports'))
                       ->getSubmenu()
                           ->add((new \CMenuItem(_('Example wide report')))
                               ->setAction('example.report.wide.php')
                           )
                           ->add((new \CMenuItem(_('Example narrow report')))
                               ->setAction('example.report.narrow.php')
                           );
           }
       
           /**
            * Event handler, triggered before executing the action.
            *
            * @param CAction $action  Action instance responsible for current request.
            */
           public function onBeforeAction(CAction $action): void {
           }
       
           /**
            * Event handler, triggered on application exit.
            *
            * @param CAction $action  Action instance responsible for current request.
            */
           public function onTerminate(CAction $action): void {
           }
       }

Action controller

<?php declare(strict_types = 1);
       
       namespace Modules\Example\Actions;
       
       use CControllerResponseData;
       use CControllerResponseFatal;
       use CController as CAction;
       
       /**
        * Example module action.
        */
       class SomethingView extends CAction {
       
           /**
            * Initialize action. Method called by Áú»¢¶Ä²© core.
            *
            * @return void
            */
           public function init(): void {
               /**
                * Disable SID (Session ID) validation. Session ID validation should only be used for actions which involve data
                * modification, such as update or delete actions. In such case Session ID must be presented in the URL, so that
                * the URL would expire as soon as the session expired.
                */
               $this->disableSIDvalidation();
           }
       
           /**
            * Check and sanitize user input parameters. Method called by Áú»¢¶Ä²© core. Execution stops if false is returned.
            *
            * @return bool true on success, false on error.
            */
           protected function checkInput(): bool {
               $fields = [
                   'name'  => 'required|string',
                   'email' => 'required|string',
                   'phone' => 'string'
               ];
       
               // Only validated data will further be available using $this->hasInput() and $this->getInput().
               $ret = $this->validateInput($fields);
       
               if (!$ret) {
                   $this->setResponse(new CControllerResponseFatal());
               }
       
               return $ret;
           }
       
           /**
            * Check if the user has permission to execute this action. Method called by Áú»¢¶Ä²© core.
            * Execution stops if false is returned.
            *
            * @return bool
            */
           protected function checkPermissions(): bool {
               $permit_user_types = [USER_TYPE_ZABBIX_ADMIN, USER_TYPE_SUPER_ADMIN];
       
               return in_array($this->getUserType(), $permit_user_types);
           }
       
           /**
            * Prepare the response object for the view. Method called by Áú»¢¶Ä²© core.
            *
            * @return void
            */
           protected function doAction(): void {
               $contacts = $this->getInput('email');
       
               if ($this->hasInput('phone')) {
                   $contacts .= ', '.$this->getInput('phone');
               }
       
               $data = [
                   'name' => $this->getInput('name'),
                   'contacts' => $contacts
               ];
       
               $response = new CControllerResponseData($data);
       
               $this->setResponse($response);
           }
       }

Action view

<?php declare(strict_types = 1);
       
       /**
        * @var CView $this
        */
       
       $this->includeJsFile('example.something.view.js.php');
       
       (new CWidget())
           ->setTitle(_('Something view'))
           ->addItem(new CDiv($data['name']))
           ->addItem(new CPartial('module.example.something.reusable', [
               'contacts' => $data['contacts']
           ])
           ->show();