20. Modules

Overview

Note that the module code will run with the same privileges as Zabbix source code. This means:

• 3rd party modules can be harmful. You must trust the modules you are installing;
• Errors in a 3rd party module code may crash the frontend. If this happens, just remove the module code from the frontend. As soon as you reload Zabbix frontend, you’ll see a note saying that some modules are absent. Go to (in Administration → General → Modules) and click Scan directory again to remove non-existent modules from the database.

Installation

Please always read the installation manual for a particular module. It is recommended to install new modules one by one to catch failures easily.

Just before you install a module:

• Make sure you have downloaded the module from a trusted source. Installation of harmful code may lead to consequences, such as data loss
• Different versions of the same module (same ID) can be installed in parallel, but only a single version can be enabled at once

Steps to install a module:

• Unpack your module within its own folder in the folder of the Zabbix frontend
• Ensure that your module folder contains at least the manifest.json file
• Navigate to and click the Scan directory button
• New module will appear in the list along with its version, author, description and status
• Enable module by clicking on its status

Troubleshooting:

Developing modules

Modules are written in PHP language. Model-view-controller (MVC) software pattern design is preferred, as it is also used in Zabbix frontend and will ease the development. PHP strict typing is also welcome but not mandatory.

Please note that with modules you can easily add new menu items and respective views and actions to Zabbix frontend. Currently it is not possible to register new API or create new database tables through modules.

Module structure

Each module is a directory (placed within the modules directory) with sub-directories containing controllers, views and any other code:

Naming convention

Before you create a module, it is important to agree on the naming convention for different module items such as directories and files so that we could keep things well organized. You can also find examples above, in the section.

Note that the ‘module’ prefix and name inclusion is mandatory for view and partial file names, unless you need to override Zabbix core views or partials. This rule, however, does not apply to action file names.

Manifest preparation

Each module is expected to have a manifest.json file with the following fields in JSON format:

For reference, please see an example of manifest.json in the section.

Actions

The module will have control over frontend actions defined within the actions object in the manifest.json file. This way new actions are defined. In the same way you may redefine existing actions. Each key of actions should represent the action name and the corresponding value should contain class and optionally layout and view keys.

One action is defined by four counterparts: name, controller, view and layout. Data validation and preparation is typically done in the controller, output formatting is done in the view or partials, and the layout is responsible for decorating the page with elements such as menu, header, footer and others.

Module actions must be defined in the manifest.json file as actions object:

There are several predefined layouts, like layout.json or layout.xml. These are intended for actions which produce different result than an HTML. You may explore predefined layouts in the app/views/ directory or even create your own.

For reference, please see an example action controller file in the section. Please do not hesitate to explore current actions of Zabbix source code, located in the app/ directory.

Module.php

This optional PHP file is responsible for module initialization as well as event handling. Class ‘Module’ is expected to be defined in this file, extending base class \Core\CModule. The Module class must be defined within the namespace specified in the manifest.json file.

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

For reference, please see an example of Module.php in the Reference section.

Reference

This section contains basic versions of different module elements introduced in the previous sections.

manifest.json

Module.php

<?php declare(strict_types = 1);
       use APP;
       /**
        * 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);
       /**
        * @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']
           ])