Botões da barra principal

A barra principal possui à direita alguns botões por padrão, que dão acesso à pesquisa, ao chatbot e ao menu de usuário. É possível adicionar nesta área novos botões com funcionalidades totalmente customizadas.

Registro do botão

O registro do botão deve ser feito em um arquivo x-config (.config) na Virtual File System, na classe “Configuração/Web Framework/Barra principal” (-1892602256). Ele deve ter o seguinte formato:

this.registerButton({
  order: 15,
  icon: 'icon_name',
  label: 'Button name',
  dependencies: null,
  module: -112260235,
  config: '{}'
});
  • order: quanto menor a ordem, mais à esquerda o botão é exibido. Os botões customizados sempre são encaixados entre o botão de pesquisa e o menu de perfil do usuário. O botão do chatbot tem ordem 10 por padrão.
  • icon: nome do ícone do botão. Pode ser escolhido entre os elencados no processo “Administração do sistema > Aparência e personalização > Ícones”.
  • label: nome do botão que será exibido na sua dica flutuante.
  • dependencies: array no formato JSON com os caminhos dos scripts necessários para o funcionamento do botão. Via de regra, será null, pois é recomendado que seja dada preferência à carga desses scripts através de importação dinâmica dentro do módulo.
  • module: chave do módulo controlador do botão. Um arquivo javascript (.js) que deverá ser salvo na Virtual File System.
  • config: um objeto livre no formato JSON com as configurações que serão passadas para o módulo.

Módulo

O código que controla a funcionalidade do botão deve estar em um módulo javascript, que deverá ser salvo como um arquivo .js na Virtual File System. Este módulo deve exportar uma função sem retorno que recebe os seguintes parâmetros:

  1. Um objeto button, cuja interface será explicada adiante.
  2. A configuração já desserializada que foi inserida em config no registro do botão. Este parâmetro é opcional, sendo utilizando apenas se uma configuração for declarada no registro.
  3. A função “showMessage” que pode ser utilizada para apresentar mensagens para o usuário, como em situações de erro que impeçam a ação do botão.

O módulo fica com o seguinte formato:

export default function (button, configuration, showMessage) {
    // Código do funcionamento do botão
}

Objeto button

O objeto button possui as seguintes propriedades:

  • button: auto-referência.
  • active: permite controlar o estado de ativação do botão.
  • enabled: permite controlar se o botão está habilitado ou não.

O botão possui eventos que podem ter listeners registrados no seguinte formato:

button.on('nome_do_evento', () => {
  // Código a ser executado no momento do evento
});

Os eventos são:

  • initialize: emitido quando é necessário inicializar o componente controlado pelo botão.
  • click: emitido quando o usuário clica sobre o botão. No caso dos botões que exibem componentes na interface, é importante que esse botão verifique se o componente está ativo ou não e, juntamente com a propriedade “active”, controle a visibilidade do componente quando o botão é acionado.
  • minimize: emitido quando é necessário minimizar o componente controlado pelo botão, pois outros elementos serão apresentados na tela.
  • screenLock: emitido quando a tela do sistema é bloqueada. Ao receber este evento, o componente controlado pelo botão deve ser ocultado ou encerrado, garantindo que a interface não possa ser utilizada durante o bloqueio de sessão.
  • screenUnlock: emitido quando a sessão do usuário é desbloqueada, permitindo que o componente controlado por este botão possa ser restaurado, caso ele não tenha sido finalizado no evento “screenLock”.

Exemplo

A seguir, daremos o exemplo de uma calculadora nutricional sendo aberta ao clicar no botão.

Primeiro, registraremos o botão no x-config da classe “Barra principal” (-1892602256).

this.registerButton({
  order: 1000,
  icon: 'calculator',
  label: 'Calculadora nutricional',
  dependencies: null,
  module: 90000000000000,
  config: '{}'
});

Depois vamos inserir o seguinte código no módulo:

const id = 'macro-nutrient-calculator';

export default function (button) {
  const iframe = document.createElement('iframe');
  iframe.src = 'https://wellnessed.com/macro-tmp.html';
  iframe.async = 1;
  iframe.id = id;
  iframe.style.position = 'fixed';
  iframe.style.top = '60px';
  iframe.style.right = '12px';
  iframe.style.height = '600px';
  iframe.style.width = '360px'
  iframe.style.background = 'rgba( 255, 255, 255, 0.45 )';
  iframe.style.boxShadow = '0 8px 32px 0 rgba( 31, 38, 135, 0.37 )';
  iframe.style.backdropFilter = 'blur( 13.5px )';
  iframe.style.borderRadius = '10px';
  iframe.style.border = '1px solid rgba( 255, 255, 255, 0.18 )';
  iframe.style.display = 'none';

  document.body.append(iframe);

  button.on('initialize', () => {
    button.enabled = true;
  });

  button.on('click', (event) => {
    if (button.active) {
      iframe.style.display = 'none';
    } else {
      iframe.style.display = '';
    }

    button.active = !button.active;
  });

  button.on('minimize', () => {
    iframe.style.display = 'none';
    button.active = false;
  });

  button.on('screenLock', () => {
    iframe.remove();
  });

  button.on('screenUnlock', () => {
    document.body.append(iframe);
    if (button.active) {
      iframe.style.display = ''
    } else {
      iframe.style.display = 'none'
    }
  });
}

Perceba que um iframe é montado e customizado a partir de um componente de terceiro, e um listener é registrado para cada um dos eventos, controlando o comportamento do botão e do iframe.

Última atualização em 23 Apr 2025