This is a translation of the original English documentation page. Help us make it better.

20 Modules

Overzicht

Het is mogelijk om de functionaliteit van de Zabbix frontend uit te breiden door externe modules toe te voegen of door je eigen modules te ontwikkelen, zonder dat je de broncode van Zabbix hoeft te wijzigen.

Houd er rekening mee dat de modulecode wordt uitgevoerd met dezelfde rechten als de broncode van Zabbix. Dit betekent het volgende:

  • Externe modules kunnen schadelijk zijn. Je moet de modules vertrouwen die je installeert.
  • Fouten in de code van een externe module kunnen de frontend laten crashen. Als dit gebeurt, verwijder dan gewoon de modulecode uit de frontend. Zodra je de Zabbix frontend opnieuw laadt, zie je een melding dat sommige modules ontbreken. Ga naar Modulebeheer (in BeheerAlgemeenModules) en klik opnieuw op Scan directory om niet-bestaande modules uit de database te verwijderen.

Installatie

Lees altijd de installatiehandleiding voor een specifieke module. Het wordt aanbevolen om nieuwe modules één voor één te installeren om fouten gemakkelijk op te sporen.

Net voordat je een module installeert:

  • Zorg ervoor dat je de module hebt gedownload van een betrouwbare bron. De installatie van schadelijke code kan tot gevolgen leiden, zoals gegevensverlies.
  • Verschillende versies van dezelfde module (dezelfde ID) kunnen parallel worden geïnstalleerd, maar slechts één versie kan tegelijkertijd worden ingeschakeld.

Stappen om een module te installeren:

  • Pak je module uit in zijn eigen map in de modules-map van de Zabbix frontend.
  • Zorg ervoor dat de map van je module ten minste het manifest.json-bestand bevat.
  • Ga naar Modulebeheer en klik op de knop Scan directory.
  • De nieuwe module verschijnt in de lijst, samen met de versie, auteur, beschrijving en status.
  • Schakel de module in door op de status te klikken.

Probleemoplossing:

Probleem Oplossing
Module verscheen niet in de lijst Zorg ervoor dat het bestand manifest.json aanwezig is in de map modules/je-module/ van de Zabbix frontend. Als het bestand aanwezig is, betekent dit dat de module niet geschikt is voor de huidige Zabbix-versie. Als het manifest.json-bestand niet bestaat, heb je waarschijnlijk uitgepakt in de verkeerde map.
Frontend crashte De modulecode is niet compatibel met de huidige Zabbix-versie of serverconfiguratie. Verwijder de modulebestanden en laad de frontend opnieuw. Je ziet een melding dat sommige modules ontbreken. Ga naar Modulebeheer en klik opnieuw op Scan directory om niet-bestaande modules uit de database te verwijderen.
Foutmelding over identieke namespace, ID of acties verschijnt De nieuwe module probeerde een namespace, ID of acties te registreren die al zijn geregistreerd door andere ingeschakelde modules. Schakel de conflicterende module (genoemd in de foutmelding) uit voordat je de nieuwe inschakelt.
Technische foutmeldingen verschijnen Rapporteer fouten aan de ontwikkelaar van de module.

Modules ontwikkelen

Modules worden geschreven in de programmeertaal PHP. Het ontwerp van het model-view-controller (MVC) softwarepatroon wordt aanbevolen, aangezien dit patroon ook wordt gebruikt in de Zabbix frontend en de ontwikkeling zal vergemakkelijken. Strikte typecontrole in PHP is ook welkom, maar niet verplicht.

Houd er rekening mee dat je met modules eenvoudig nieuwe menu-items en bijbehorende weergaven en acties aan de Zabbix frontend kunt toevoegen. Momenteel is het echter niet mogelijk om via modules nieuwe API's te registreren of nieuwe database-tabellen te maken.

Module-structuur

Elke module is een map (geplaatst binnen de modules-map) met submappen die controllers, weergaven en andere code bevatten:

example_module_directory/           (vereist)
           manifest.json                   (vereist)  Metadata en actiedefinitie.
           Module.php                                  Module-initialisatie en gebeurtenisverwerking.
           actions/                                    Actiecontrollerbestanden.
               SomethingView.php
               SomethingCreate.php
               SomethingDelete.php
               data_export/                                 
                   ExportAsXml.php
                   ExportAsExcel.php
           views/                                      Weergavebestanden.
               example.something.view.php
               example.something.delete.php
               js/                                     JavaScript-bestanden die in weergaven worden gebruikt.
                   example.something.view.js.php
           partials/                                   Gedeeltelijke weergavebestanden.
               example.something.reusable.php
               js/                                     JavaScript-bestanden die in gedeeltelijke weergaven worden gebruikt.
                   example.something.reusable.js.php

Zoals je kunt zien, is het enige verplichte bestand in de aangepaste modulemap manifest.json. De module wordt niet geregistreerd zonder dit bestand. Module.php is verantwoordelijk voor het registreren van menu-items en het verwerken van gebeurtenissen zoals 'onBeforeAction' en 'onTerminate'. De mappen actions, views en partials bevatten PHP- en JavaScript-code die nodig is voor moduleacties.

Naamconventie

Voordat je een module maakt, is het belangrijk om het eens te worden over de naamconventie voor verschillende module-items, zoals mappen en bestanden, zodat alles goed georganiseerd blijft. Je kunt ook voorbeelden vinden in het gedeelte Modulestructuur hierboven.

Item Naamgevingsregels Voorbeeld
Modulemap Kleine letters [a-z], underscore en decimale cijfers example_v2
Actiesubmappen Kleine letters [a-z] en underscore-teken data_export
Actiebestanden CamelCase, eindigend met actietype SomethingView.php
Weergave- en gedeeltelijke bestanden Kleine letters [a-z]
Woorden gescheiden door een punt
Voorafgegaan door module. gevolgd door de modulenaam
Eindigt op actietype en .php-bestandsextensie
module.example.something.view.php
Javascript-bestanden Dezelfde regels zijn van toepassing als voor weergave- en gedeeltelijke bestanden, behalve de .js.php bestandsextensie. module.example.something.view.js.php

Merk op dat het voorvoegsel 'module' en de naam verplicht zijn voor de namen van weergave- en gedeeltelijke bestanden, tenzij je Zabbix-kernweergaven of -gedeeltelijke weergaven wilt overschrijven. Deze regel is echter niet van toepassing op actiebestandsnamen.

Voorbereiding van het manifest

Elke module wordt verwacht een manifest.json-bestand te hebben met de volgende velden in JSON-indeling:

Parameter Vereist Type Standaard Beschrijving
manifest_version Ja Double - Versie van het manifest van de module. Momenteel ondersteunde versie is 1.
id Ja String - Module-ID. Slechts één module met een gegeven ID kan tegelijkertijd worden ingeschakeld.
name Ja String - Module-naam zoals weergegeven in de sectie Administratie.
version Ja String - Module-versie zoals weergegeven in de sectie Administratie.
namespace Ja String - PHP-namespace voor Module.php en actieklassen.
author Nee String "" Module-auteur zoals weergegeven in de sectie Administratie.
url Nee String "" Module-URL zoals weergegeven in de sectie Administratie.
description Nee String "" Module-beschrijving zoals weergegeven in de sectie Administratie.
actions Nee Object {} Acties die met deze module moeten worden geregistreerd. Zie Acties.
config Nee Object {} Moduleconfiguratie.

Ter referentie, zie een voorbeeld van manifest.json in de Referentie sectie.

Acties

De module heeft controle over frontend-acties die worden gedefinieerd in het actions object in het manifest.json-bestand. Op deze manier worden nieuwe acties gedefinieerd. Op dezelfde manier kunt u bestaande acties opnieuw definiëren. Elke sleutel van acties moet de naam van de actie vertegenwoordigen en de overeenkomstige waarde moet de sleutels class en optioneel layout en view bevatten.

Eén actie wordt gedefinieerd door vier onderdelen: naam, controller, weergave en lay-out. Gegevensvalidatie en voorbereiding worden meestal gedaan in de controller, opmaak wordt gedaan in de weergave of gedeelten, en de lay-out is verantwoordelijk voor het decoreren van de pagina met elementen zoals het menu, de koptekst, de voettekst en andere.

Moduleacties moeten worden gedefinieerd in het manifest.json-bestand als een actions object:

Parameter Vereist Type Standaard Beschrijving
*sleutel* Ja String - Actienaam, in kleine letters [a-z], waarbij woorden worden gescheiden door een punt.
class Ja String - Naam van de actieklasse, inclusief het subdirectory-pad (indien gebruikt) binnen de actions map.
layout Nee String "layout.htmlpage" Actielay-out.
view Nee String null Actieweergave.

Er zijn verschillende vooraf gedefinieerde lay-outs, zoals layout.json of layout.xml. Deze zijn bedoeld voor acties die een ander resultaat opleveren dan een HTML-pagina. U kunt de vooraf gedefinieerde lay-outs verkennen in de app/views/ map of zelfs uw eigen lay-outs maken.

Soms is het nodig om alleen het weergavedeel van een bepaalde actie opnieuw te definiëren, terwijl de controller intact blijft. In dat geval plaatst u gewoon de benodigde weergave- en/of partiële bestanden in de views map van de module.

Module.php

Dit optionele PHP-bestand is verantwoordelijk voor de initialisatie van de module en het afhandelen van gebeurtenissen. In dit bestand wordt verwacht dat de klasse 'Module' wordt gedefinieerd, die de basis klasse \Core\CModule uitbreidt. De Module-klasse moet worden gedefinieerd binnen de namespace die is gespecificeerd in het manifest.json-bestand.

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

Ter referentie, zie een voorbeeld van Module.php in de Referentie sectie. Aarzel niet om de huidige acties van de Zabbix-broncode te verkennen, die zich bevinden in de app/ map.

Referentie

Deze sectie bevat basisversies van verschillende module-elementen die in de vorige secties zijn geïntroduceerd.

manifest.json

{
           "manifest_version": 1.0,
           "id": "example_module",
           "name": "Voorbeeldmodule",
           "version": "1.0",
           "namespace": "Voorbeeld",
           "author": "John Smith",
           "url": "http://module.example.com",
           "description": "Korte beschrijving van de 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;
       
       /**
        * Raadpleeg de Core\CModule-klasse voor aanvullende referentie.
        */
       class Module extends \Core\CModule {
       
           /**
            * Module initialiseren.
            */
           public function init(): void {
               // Hoofdmenu initialiseren (CMenu class instance).
               APP::Component()->get('menu.main')
                   ->findOrAdd(_('Rapporten'))
                       ->getSubmenu()
                           ->add((new \CMenuItem(_('Voorbeeld breed rapport')))
                               ->setAction('example.report.wide.php')
                           )
                           ->add((new \CMenuItem(_('Voorbeeld smal rapport')))
                               ->setAction('example.report.narrow.php')
                           );
           }
       
           /**
            * Event handler, getriggerd vóór het uitvoeren van de actie.
            *
            * @param CAction $action  Actie-instantie verantwoordelijk voor huidig verzoek.
            */
           public function onBeforeAction(CAction $action): void {
           }
       
           /**
            * Event handler, getriggerd bij afsluiten van de applicatie.
            *
            * @param CAction $action  Actie-instantie verantwoordelijk voor huidig verzoek.
            */
           public function onTerminate(CAction $action): void {
           }
       }

Actiecontroller

<?php declare(strict_types = 1);
       
       namespace Modules\Example\Actions;
       
       use CControllerResponseData;
       use CControllerResponseFatal;
       use CController as CAction;
       
       /**
        * Voorbeeldmoduleactie.
        */
       class SomethingView extends CAction {
       
           /**
            * Actie initialiseren. Methode opgeroepen door Zabbix core.
            *
            * @return void
            */
           public function init(): void {
               /**
                * SID (Sessoin ID) validatie uitschakelen. Sessie-ID-validatie moet alleen worden gebruikt voor acties die
                * datamodificatie omvatten, zoals update- of verwijderacties. In dergelijke gevallen moet het sessie-ID
                * aanwezig zijn in de URL, zodat de URL vervalt zodra de sessie is verlopen.
                */
               $this->disableSIDvalidation();
           }
       
           /**
            * Gebruikersinvoerparameters controleren en saneren. Methode opgeroepen door Zabbix core. Uitvoering stopt als false wordt geretourneerd.
            *
            * @return bool true bij succes, false bij fout.
            */
           protected function checkInput(): bool {
               $fields = [
                   'name'  => 'required|string',
                   'email' => 'required|string',
                   'phone' => 'string'
               ];
       
               // Alleen gevalideerde gegevens zijn verder beschikbaar via $this->hasInput() en $this->getInput().
               $ret = $this->validateInput($fields);
       
               if (!$ret) {
                   $this->setResponse(new CControllerResponseFatal());
               }
       
               return $ret;
           }
       
           /**
            * Controleren of de gebruiker toestemming heeft om deze actie uit te voeren. Methode opgeroepen door Zabbix core.
            * Uitvoering stopt als false wordt geretourneerd.
            *
            * @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);
           }
       
           /**
            * Voorbereiden van het responsobject voor de weergave. Methode opgeroepen door Zabbix 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);
           }
       }

Actieweergave

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