Sobre estilos de ícone

Pensando em facilitar a customização do projeto foi desenvolvida a funcionalidade que permite a criação de ícones personalizados de forma mais fácil e sem integração direta com o código do projeto.

Toda a funcionalidade está concentrada no arquivo custom_icons.json localizado em ./resources/icons/.

ATENÇÃO: Nunca use o arquivo icons.json para fazer essas personalizações, uma vez que esse arquivo pode ser sobrescrito em uma eventual atualização.

Veja mais detalhes sobre a estrutura de JSON aqui.

O arquivo contém 3 nós principais, sendo eles names, hostgroups e styles, nesse momento iremos focar no nó chamado styles, é esse nó que contém a definição dos estilos.

Básico

Definição

Para criar um novo estilo é necessário que seja criado um novo nó dentro de 'styles' seguindo esse formato:

"NOME_NOVO_ESTILO": {
    "grey": {
        "iconUrl": "URL_DA_IMAGEM",
        "iconSize": [LARGURA, ALTURA]
    },
    "green": {
        "iconUrl": "URL_DA_IMAGEM",
        "iconSize": [LARGURA, ALTURA]
    },
    "yellow": {
        "iconUrl": "URL_DA_IMAGEM",
        "iconSize": [LARGURA, ALTURA]
    },
    "orange": {
        "iconUrl": "URL_DA_IMAGEM",
        "iconSize": [LARGURA, ALTURA]
    },
    "red": {
        "iconUrl": "URL_DA_IMAGEM",
        "iconSize": [LARGURA, ALTURA]
    }
},

Sempre deve iniciar pelo nome do estilo (é encorajado o uso do padrão snake case) e em seguida a definição de todas as cores, cada cor representa um status:

• Cinza = Desconhecido;
• Verde = Up;
• Amarelo = Aviso;
• Laranja = Critico;
• Vermelho = Down;

Todas as cores devem ser definidas, para que o estilo funcione corretamente.

URL da imagem

Por padrão o projeto assume que as imagens estão contidas em uma pasta dentro de ./resources/icons/styles/, é recomendado que dentro dessa pasta seja criada uma nova pasta com o nome do estilo e que seus ícones sejam agrupados dentro dela, dessa forma a URL a ser informada no JSON deve ser o caminho relativo a partir da pasta ./resources/icons/styles/, sendo assim quando:

"iconURL": "novo_estilo/Grey.png",

Então a URL completa gerada será: ./resources/icons/styles/novo_estilo/Grey.png

Uso

Uma vez essa definição tendo sido concluída com sucesso* basta informar o nome do novo estilo no arquivo de configuração.

'default_icon_style' => "NOME_NOVO_ESTILO",

^{* Nesse site jsonformatter você pode verificar se o arquivo permanece um JSON válido após as modificações!}

Avançado

Parâmetros adicionais

Por padrão tendo a largura e comprimento (iconSize) o projeto automaticamente calculara as informações relativas ao alinhamento do ícone (iconAnchor) e posição do pop-up (popupAnchor) seguindo essas regras:

• Alinhamento do ícone (iconAnchor): [LARGURA/2, (ALTURA-1)], dessa forma o ícone se posiciona acima do ponto definido no mapa;
• Posição do pop-up (popupAnchor): [0, -(ALTURA-1)], esse parâmetro parte do ponto definido no alinhamento do ícone, dessa forma o pop-up se posiciona acima do ícone;

Mas se necessário você pode sobrescrever essas definições, bastando somente adicionar os parâmetros dentro da definição de cada cor.

Enquanto os valores padrões gerados para quando somente definido iconSize:

"NOME_NOVO_ESTILO": {
    "grey": {
        "iconUrl": "new_style/Green.png",
        "iconSize": [29, 43]
    },
    ...

Seriam, para iconAnchor = [14, 44] e popupAnchor = [0, -44];

Para sobrescrever bastaria definir esses parâmetros dentro do no da cor, dessa forma:

"NOME_NOVO_ESTILO": {
    "grey": {
        "iconUrl": "new_style/Green.png",
        "iconSize": [29, 43],
        "iconAnchor": [20, 40],
        "popupAnchor": [0, -5]
    },
    ...

Isso levaria a sobrescrita dos valores padrões pré-calculados e os informados seriam utilizados!

Ícones dinâmicos.

Desde a versão 2.1.0 é possível definir ícones dinâmicos com base no nome ou grupo dos hosts, permitindo assim o uso de mais de um estilo de ícone ao mesmo tempo.

Dentro do mesmo arquivo custom_icons.json você encontrará os nós names e hostgroups, através dos quais as definições dinâmicas podem ser feitas.

Estrutura esperada

Ambos os nós têm a mesma estrutura esperada:

Onde a chave será o nome de um estilo, podendo dar um dos estilos pré-existentes ou customizados, o valor será o nome exato de um host ou grupo (cada um em seu próprio nó).

    "names": {
        "estilo_pre_existente": "Nomde de um host"
    },
    
    "hostgroups": {
        "estilo_customizado": "Nomde de um grupo",
    },

Também é possível mapear vários nomes de host ou grupos de host para cada estilo usando a notação de array ["valor1", "valor2"]:

    "names": {
        "estilo_pre_existente": ["Nome de um host", "Nome de outro host"]
    }

Exemplo de uso na vida real:

Digamos que eu tenha 5 hostgroups nas configurações, a saber: servidores-xyz, routeadores-a, routeadores-b, hotspot-d e outro (de nome irrelevante para o exemplo).

E um dos hosts no grupo servez-xyz tem o nome Servidor-principal.

Com base nisso, digamos que eu queira exibir cada um com seu estilo de ícone específico, conforme abaixo:

Name	Style
servidores-xyz hostgroup	server
Servidor-principal host name	server_border_dark
routeadores-a hostgroup	router
routeadores-a hostgroup	router
hostspot-d hostgroup	wifi

Nesse caso, os nós ficariam assim:

    "names": {
        "server_border_dark": "Servidor-principal"
    },
    
    "hostgroups": {
        "server": "servidores-xyz",
        "router": ["routeadores-a", "routeadores-b"],
        "wifi": "hotspot-d",
    },

Com esta configuração, cada grupo exibiria seu próprio ícone, e o host Servidor-principal seria o único com um ícone diferente dentro do grupo servidores-xyz porque tem uma configuração baseada em nome que substitui o estilo do grupo.

Observe também que existem dois grupos para roteadores e estes foram mapeados usando notação de array passando o nome dos dois grupos.

Todos os grupos e hosts que não tiverem uma configuração definida aqui exibirão o ícone padrão definido no arquivo de configuração, como o quinto grupo sem nome em nosso exemplo.

---

João Carlos.

See here in English.