Criar um módulo (tutorial)

Este é um tutorial passo a passo que mostra como criar um módulo simples de frontend do Zabbix. Você pode baixar todos os arquivos deste módulo como um arquivo ZIP: MyAddress.zip.

O que você vai criar

Durante este tutorial, você primeiro criará um módulo de frontend que adiciona uma nova seção de menu My Address e depois o converterá em um módulo de frontend mais avançado que faz uma requisição HTTP para https://api.seeip.org e exibe a resposta — o endereço IP do seu computador — em uma nova página na seção de menu My Address recém-criada. Veja como o módulo final ficará:

Parte I - Nova seção de menu

Adicionar um módulo em branco ao frontend do Zabbix

1. Crie um diretório MyAddress no diretório modules da sua instalação do frontend do Zabbix (por exemplo, zabbix/ui/modules).

2. Crie um arquivo manifest.json com os metadados básicos do módulo (consulte a descrição dos parâmetros suportados).

ui/modules/MyAddress/manifest.json

{
    "manifest_version": 2.0,
    "id": "my-address",
    "name": "My IP Address",
    "version": "1.0",
    "namespace": "MyAddress",
    "description": "My External IP Address."
}

3. No frontend do Zabbix, vá para a seção Administration → General → Modules e clique no botão Scan directory.

4. Localize o novo módulo My IP Address na lista e clique no hiperlink "Disabled" para alterar o status do módulo de "Disabled" para "Enabled" (se o módulo não estiver listado, consulte a seção de troubleshooting).

O módulo agora está registrado no frontend. No entanto, ele ainda não está visível, porque você ainda precisa definir a funcionalidade do módulo. Depois de adicionar conteúdo ao diretório do módulo, você verá imediatamente as alterações no frontend do Zabbix ao atualizar a página.

Criar uma seção de menu

1. Crie um arquivo Module.php no diretório MyAddress.

Esse arquivo implementa uma nova classe Module que estende a classe padrão CModule. A classe Module inserirá uma nova seção de menu My Address no menu principal.

O método setAction() especifica uma ação a ser executada ao clicar na seção de menu. Para começar, você pode usar a ação predefinida userprofile.edit, que abrirá a página User profile. Na parte III deste tutorial, você aprenderá a criar uma ação personalizada.

ui/modules/MyAddress/Module.php

<?php

namespace Modules\MyAddress;

use Zabbix\Core\CModule,
    APP,
    CMenuItem;

class Module extends CModule {

    public function init(): void {
        APP::Component()->get('menu.main')
            ->add((new CMenuItem(_('My Address')))
            ->setAction('userprofile.edit'));
    }
}

3. Atualize o frontend do Zabbix. Agora há uma nova seção My Address na parte inferior do menu principal do Zabbix. Clique em My Address para abrir a página User profile.

Parte II - Alteração da localização da seção do menu

Nesta parte, você moverá a seção de menu Meu endereço para a seção Monitoramento e, em seguida, adicionará um menu aninhado a ela. Como resultado, os usuários poderão acessar duas páginas de submenus a partir da seção de menu Monitoramento → Meu endereço.

1. Abra e edite o arquivo Module.php.

ui/modules/MyAddress/Module.php

<?php

namespace Modules\MyAddress;

use Zabbix\Core\CModule,
    APP,
    CMenuItem;

class Module extends CModule {

    public function init(): void {
        APP::Component()->get('menu.main')
            ->findOrAdd(_('Monitoring'))
            ->getSubmenu()
            ->insertAfter(_('Discovery'),
                (new CMenuItem(_('My Address')))->setAction('userprofile.edit')
            );
    }
}

2. Atualize o frontend do Zabbix. Expanda a seção de menu Monitoramento e observe que a seção Meu endereço agora está localizada abaixo da seção Descoberta.

3. Para adicionar páginas aninhadas à seção de menu Meu endereço, abra e edite novamente o arquivo Module.php.

Esta etapa cria duas subseções:

• IP externo que executa uma nova ação 'my.address' que será definida nas próximas etapas;
• Perfil do usuário que executa a ação predefinida 'userprofile.edit' para abrir a página Perfil do usuário.

Observe que, para o menu aninhado, você precisa usar a classe CMenu além das classes usadas nas etapas anteriores.

ui/modules/MyAddress/Module.php

<?php

namespace Modules\MyAddress;

use Zabbix\Core\CModule,
    APP,
    CMenu,
    CMenuItem;

class Module extends CModule {

    public function init(): void {
        APP::Component()->get('menu.main')
            ->findOrAdd(_('Monitoring'))
            ->getSubmenu()
            ->insertAfter(_('Discovery'),
                (new CMenuItem(_('My Address')))->setSubMenu(
                    new CMenu([
                        (new CMenuItem(_('External IP')))->setAction('my.address'),
                        (new CMenuItem(_('User profile')))->setAction('userprofile.edit')
                    ])
                )
            );
    }
}

4. Atualize o frontend do Zabbix. Observe que a seção de menu Meu endereço agora contém um menu de terceiro nível com duas páginas - IP externo e Perfil do usuário.

Parte III - Ação do módulo

Uma action é implementada em dois arquivos - actions/MyAddress.php e views/my.address.php. O arquivo actions/MyAddress.php cuida da implementação da lógica de negócio, enquanto o arquivo views/my.address.php é responsável pela view.

1. Crie um diretório actions no diretório MyAddress.

2. Crie um arquivo MyAddress.php no diretório actions.

A lógica da action será definida na classe MyAddress. Essa classe de action implementará quatro funções: init(), checkInput(), checkPermissions() e doAction(). O frontend do Zabbix chama a função doAction() quando a action é solicitada. Essa função é responsável pela lógica de negócio do módulo.

ui/modules/MyAddress/actions/MyAddress.php

<?php

namespace Modules\MyAddress\Actions;

use CController,
    CControllerResponseData;

class MyAddress extends CController {

    public function init(): void {
        $this->disableCsrfValidation();
    }

    protected function checkInput(): bool {
        return true;
    }

    protected function checkPermissions(): bool {
        return true;
    }

    protected function doAction(): void {
        $data = ['my-ip' => file_get_contents("https://api.seeip.org")];
        $response = new CControllerResponseData($data);
        $this->setResponse($response);
    }
}

3. Crie um novo diretório views no diretório MyAddress.

4. Crie um arquivo my.address.php no diretório views e defina a view do módulo.

Observe que a variável $data está disponível na view sem precisar ser definida especificamente. O framework passa automaticamente o array associativo para a view.

ui/modules/MyAddress/views/my.address.php

<?php

(new CHtmlPage())
    ->setTitle(_('The HTML Title of My Address Page'))
    ->addItem(new CDiv($data['my-ip']))
    ->show();

5. A action do módulo precisa ser registrada no arquivo manifest.json. Abra manifest.json e adicione um novo objeto actions que contenha:

• a chave da action com o nome da action escrito em minúsculas (a-z) e com as palavras separadas por pontos (por exemplo, my.address);
• o nome da classe da action (MyAddress) como valor da chave class do objeto my.address;
• o nome da view da action (my.address) como valor da chave view do objeto my.address.

ui/modules/MyAddress/manifest.json

{
    "manifest_version": 2.0,
    "id": "my-address",
    "name": "My IP Address",
    "version": "1.0",
    "namespace": "MyAddress",
    "description": "My External IP Address.",
    "actions": {
        "my.address": {
            "class": "MyAddress",
            "view": "my.address"
        }
    }
}

6. Atualize o frontend do Zabbix. Clique em My address → External IP para ver o endereço IP do seu computador.