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:
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:
Pasos para instalar un m¨®dulo:
modules
de la interfaz de Áú»¢¶Ä²©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 ³¾¨®»å³Ü±ô´Ç.|
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.
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 ³¾¨®»å³Ü±ô´Ç.
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¨®duloTerminando 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.
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.
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.
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();