[comment]: # aside:1

[comment]: # ({b311df1e-8fe7205c})
# Criar um módulo (tutorial)

[comment]: # ({/b311df1e-8fe7205c})

[comment]: # ({98067368-5fb5b83a})
Este é um tutorial passo a passo que mostra como criar um módulo simples de front-end do Zabbix. Você pode fazer o download de todos os arquivos desse módulo como um arquivo ZIP: [MyAddress.zip](../../../../../assets/en/devel/modules/examples/MyAddress.zip).

[comment]: # ({/98067368-5fb5b83a})

[comment]: # ({5fe8674d-5ce71b9d})
### O que você criará

Durante este tutorial, você primeiro criará um módulo de frontend que adiciona uma nova seção de menu *My Address* e, em seguida, convertê-lo em um módulo de frontend  [more advanced](#part-iii---module-action) que faz uma solicitação HTTP para *https://api.seeip.org* e exibe a resposta - o endereço IP do seu computador - em uma nova página na recém-criada seção de menu *My Address*.
Veja a seguir a aparência do módulo finalizado:

![](../../../../../assets/en/devel/modules/tutorials/module/my_address_finished.png){width="600"}

[comment]: # ({/5fe8674d-5ce71b9d})

[comment]: # ({a5c86d2c-8c2bcd9e})
### Parte I - Nova seção do menu

[comment]: # ({/a5c86d2c-8c2bcd9e})

[comment]: # ({9c416cbb-1d4de634})
##### Adicionar um módulo em branco ao front-end do Zabbix

1. Crie um diretório *MyAddress* em *zabbix/ui/modules*.

2. Crie um arquivo *manifest.json* com os metadados básicos do módulo (consulte a descrição dos [parameters] suportados(../file_structure/manifest)).

**ui/modules/MyAddress/manifest.json**

```json
{
    "manifest_version": 2.0,
    "id": "my-address",
    "name": "Meu endereço IP",
    "version" (versão): "1.0",
    "namespace": "MyAddress",
    "description" (descrição): "My External IP Address" (Meu endereço IP externo)
}
```

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

![](../../../../../assets/en/devel/modules/tutorials/widget/scan_dir.png)

4. Localize o novo módulo *My IP Address* na lista e clique no hiperlink "Disabled" (Desativado) para alterar o status do módulo de "Disabled" (Desativado) para "Enabled" (Ativado).

![](../../../../../assets/en/devel/modules/tutorials/module/module_register.png){width="600"}

O módulo agora está registrado no frontend. Entretanto, ele ainda não está visível, pois 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.

[comment]: # ({/9c416cbb-1d4de634})

[comment]: # ({64c4a481-d88b8114})
##### 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 do menu.
Para começar, você pode usar a ação predefinida *userprofile.edit*, que abrirá a página *User profile*.
Na [part III](#parte-iii---module-action) deste tutorial, você aprenderá a criar uma ação personalizada.

**ui/modules/MyAddress/Module.php**

```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'));
    }
}
```

:::noteclassic
Você pode substituir `'userprofile.edit'` por outras ações, por exemplo, `'charts.view'` (opens custom graphs), `'problems.view'` (opens *Monitoring → Problems*) ou `'report.status'` (opens *System information* report).
:::

3. Atualize o front-end 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*.

![](../../../../../assets/en/devel/modules/tutorials/module/my_address_top_menu.png){width="600"}

[comment]: # ({/64c4a481-d88b8114})

[comment]: # ({89dbfda8-5c3fc480})
### Parte II - Alteração do local da seção do menu

Nesta parte, você moverá a seção de menu *Meu Endereço* para a seção *Monitoramento* e adicionar um submenu a ela.
Como resultado, os usuários poderão acessar duas páginas de submenu na seção de menu *Monitoramento → Meu Endereço*.

1. Abra e edite o arquivo *Module.php*.

**ui/modules/MyAddress/Module.php**

```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(_('Monitoramento'))
                ->getSubmenu()
                    ->insertAfter(_('Descoberta'),
                        (new CMenuItem(_('Meu Endereço')))->setAction('userprofile.edit')
                    );
    }
}
```

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

![](../../../../assets/en/devel/modules/tutorials/module/my_address_monitoring.png){width="600"}

3. Para adicionar paginas abaixo da seção do menu *Meu Endereço*, abra e edite o arquivo *Module.php* novamente.

Esse passo cria duas subseções:

-*IP Externo* que executa uma nova ação 'my.address', que será definida nos próximos passos;
-*Perfil de Usuário* que executa a ação prédefinida 'userprofile.edit' para abrir a pagina *Perfil de usuário*.

Note que para submenus, voce precisa usar a classe *CMenu* além das classes utilizadas em passos anteriores.

**ui/modules/MyAddress/Module.php**

```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(_('Monitoramento'))
->getSubmenu()
->insertAfter(_('Descoberta'),
(new CMenuItem(_('Meu Endereço')))->setSubMenu(
new CMenu([
(new CMenuItem(_('IP Externo')))->setAction('my.address'),
(new CMenuItem(_('Perfil de Usuário')))->setAction('userprofile.edit')
])
)
);
}
}
```

4. Atualize o frontend do Zabbix. Observe que a seção do menu *Meu Endereço* agora contem um menu de terceiro nível, com duas páginas - *IP Externo* and *Perfil de Usuário*.

![](../../../../assets/en/devel/modules/tutorials/module/my_address_nested.png){width="600"}

[comment]: # ({/89dbfda8-5c3fc480})

[comment]: # ({6061bdad-8798eff6})
### Parte III - Módulo de ação

Uma ação é 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 visualização.

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

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

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

::: noteimportant
Os dados devem ser organizados como um sequência associativa.
A sequência pode ser multidimensional e pode conter quaisquer dados esperados pela exibição.
:::

**ui/modules/MyAddress/actions/MyAddress.php**

```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 visualização do módulo.

Observe que a variável `$data` está disponível na visualização sem que ela seja especificamente definida.
A estrutura passa automaticamente a sequência associativa para a visualização.

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

```php
<?php

(new CHtmlPage())
    ->setTitle(_('O título HTML da minha Página de Endereço'))
    ->addItem(new CDiv($data['my-ip']))
    ->show();
```

5. A ação do módulo deve ser registrada no arquivo *manifest.json*. Abra o arquivo *manifest.json* e adicione um novo objeto `actions` que contenha:

-   a chave da ação com o nome da ação escrito em letras minúsculas (a-z) e com palavras separadas por pontos (por exemplo, `my.address`);
-   o nome da classe da ação (`MyAddress`) como um valor para a chave `class` do objeto `my.address`;
-   o nome da visualização da ação (`my.address`) como um valor para a chave `view` do objeto `my.address`.

**ui/modules/MyAddress/manifest.json**

```json
{
    "manifest_version": 2.0,
    "id": "my-address",
    "name": "Meu endereço IP",
    "version" (versão): "1.0",
    "namespace": "MyAddress",
    "description" (descrição): "Meu endereço IP externo",
    "actions": {
    "my.address": {
    "class": "MyAddress",
    "view": "my.address"
    }
    }
}
```

7. Atualize a interface web do Zabbix. Clique na seção do menu *My address → External IP* para ver o endereço IP do seu computador.

![](../../../../../assets/pt/devel/modules/tutorials/module/my_address_finished.png){width="600"}

[comment]: # ({/6061bdad-8798eff6})