Configurações gerais

As configurações gerais no sistema permitem o controle de parametrizações simples que se aplicam a todo o sistema ou a um módulo específico. Elas devem ser utilizadas para configurações cujos valores sejam de tipos primitivos, datas ou chaves do sistema, e quando elas não são relacionadas ao sistema de permissões, nem a outros registros, como grupos ou usuários.

É importante observar que o sistema possui diversos outros mecanismos para gerenciar as parametrizações, portanto as configurações gerais devem ser empregadas quando as demais opções existentes não forem adequadas. Abaixo são relacionados alguns cenários de uso e as estratégias recomendadas:

Permissões associadas a uma classe de dados ou arquivo: deve ser utilizado o modelo de permissões.
Permissões específicas de um processo: uso de palavras chaves associadas ao processo, recurso existente no modelo de permissões do sistema.
Permissões gerais que não se aplicam a um processo ou a uma classe de dados: escopos de autorização.
Configurações ou preferências associadas aos registros de uma classe de dados: campos na classe de dados ou vínculos associados à ela.
Regras de sugestão de valores com base nas informações preenchidas pelo usuário: pesquisa combinatória (funcionalidade implementada pelo ERP).
Configurações complexas que requerem lógicas programáveis associadas a uma classe de dados: arquivos x-config ou x-model associados à classe de dados.
Configurações complexas que requerem lógicas programáveis não associadas a uma classe de dados: arquivos x-config ou x-model filhos de “/Configuração”.
Configurações simples que não requerem lógicas programáveis: configurações gerais.

Observando os cenários de uso acima, vê-se que as configurações gerais devem ser utilizadas apenas quando as outras estratégias existentes não forem aderentes, nunca como primeira opção. O motivo disso é que as configurações gerais, por serem uma solução generalista, não permitem a implementação de regras ou controles ricos como os existentes no modelo de permissões, nem têm a flexibilidade dos arquivos “x-config” e “x-model”.

Processo Configurações gerais

Caminho: Desenvolvimento > Configurações gerais > Configurações gerais.

Neste processo é possível criar ou alterar as definições das configurações gerais. O público alvo desse processo são os desenvolvedores do sistema que desejam criar uma nova configuração geral ou modificar uma existente. Ele não deve ser utilizado diretamente pelos administradores do sistema, nem pelos usuários finais, pois a sua interface é técnica e não possui uma boa usabilidade. Por exemplo, no preenchimento de configurações que armazenam chaves, não há apresentação de grades lookup e o usuário do processo deve informar as chaves manualmente.

Criando ou alterando uma configuração geral

A criação ou alteração de uma configuração geral segue o fluxo normal de utilização da grade e os seguintes campos abaixo devem ser obrigatoriamente preenchidos:

Nome: deve ser um nome técnico composto apenas por letras não acentuadas, números e o caractere “_”, podendo ser definida uma hierarquia de seções por meio do separador “.”. É recomendado que se use uma convenção de namespaces, garantindo que um identificador definido por um módulo do sistema não conflite com os demais. O uso de seções também é recomendado, pois a API de configurações gerais permite a leitura e alteração simplificada de múltiplas configurações contidas em uma seção. Exemplo: “wf.login.colors.primary”.
Descrição: indica o propósito e uso da configuração no sistema. O texto informado será apresentado ao usuário como ajuda no preenchimento da configuração.
Tipo: tipo da configuração, podendo ser “string”, “int32”, “int64”, “double”, “date”, “time”, “timestamp”, “boolean”, “dbkey” ou “color”.
Múltiplo: indica se a configuração aceita múltiplos valores do tipo informado.
Valor padrão: determina o valor da configuração caso ela não tenha sido preenchida em uma base de dados.
Sincronizável: indica se a configuração pode ser enviada para uma outra base de dados por meio do processo de sincronização de configurações. Configurações que tenham que ser únicas para uma base de dados devem ter essa opção desativada. Por exemplo, uma configuração que indique o endereço público da base de dados não é sincronizável, pois não faz sentido replicar essa configuração para outras bases de dados, como as de desenvolvimento e homologação. Já as configurações de cores da tela de login são sincronizáveis, pois uma vez que uma base de dados é configurada, há o desejo de replicar essa configuração com facilidade para as demais. ** Rótulo: nome curto a ser apresentado ao usuário no preenchimento da configuração.

Para configurações do tipo dbkey, também devem ser informados os seguintes campos:

Classe: classe de dados das chaves.
Tipo de lookup: define se a chave é de um registro, de uma classe de dados ou de um arquivo da Virtual File System.

Para simplificar a construção de grades para preenchimentos das configurações, é recomendado que também sejam preenchidos os campos “Grupo”, “Coluna”, “Ordem”, “Tamanho” e “Largura”. Esses campos e o “Rótulo” são utilizados pela função newSettingsGrid para criar uma grade de preenchimento da configuração. Essa funcionalidade será explicada com mais detalhes mais à frente.

É importante observar que os registros de configurações gerais devem ser associados aos produtos do sistema (chave negativa) e o campo “Valor” não é relevante no momento da criação da configuração. Esse campo é definido com a propriedade “Usuário altera chave negativa” habilitada, portanto o valor dele não é replicado pelos processos de atualização do sistema, diferentemente do campo “Valor padrão”, que é sincronizado com os demais campos da configuração pelos processos de atualização.

Classe GeneralSettings

Módulo: @nginstack/engine/lib/settings/GeneralSettings.

Após as configurações terem sido criadas, o desenvolvedor pode consultar ou alterar os seus valores por meio dos método get e update da classe GeneralSettings, conforme exemplo abaixo:

const settings = require('@nginstack/engine/lib/settings/GeneralSettings').getInstance();

settings.get('wf.login.colors.primary'); // => '#1565c0'
settings.get('wf.login.colors'); // {primary: '#1565c0', secondary: '#546e7a', background: '#fafafa'}

settings.update('wf.login.colors.primary', '#1565c0');
settings.update('wf.login.colors', {
  primary: '#1565c0',
  secondary: '#546e7a',
  background: '#fafafa'
});

A adoção de nomes seguindo uma estrutura hierárquica bem definida simplificam o uso da API. E que uma vez que um nome é adotado, a sua alteração pode quebrar códigos existentes, exigindo que essa alteração seja evitada ou que seja bem documentada. Alternativamente, a API também aceita identificar as configurações pelas suas chaves, no entanto, essa forma de uso não permite a leitura ou alteração de uma seção de valores.

Criando interfaces para alteração das configurações gerais

Para que o administrador do sistema ou o usuário final alterem as configurações gerais, é recomendado que sejam criados processos específicos, com um escopo de configuração reduzido e que sejam de simples utilização. Devem ser evitados processos muito genéricos, sendo preferível processos menores, restritos a um domínio de negócio ou a uma parte dele.

Para isso, o desenvolvedor deve criar grades com colunas específicas para cada configuração a ser alterada, fazendo uso de estratégias que simplifiquem o preenchimento, como grupos, ajuda de campos e validações de preenchimento na interface.

Para simplificar a criação dessas interfaces existe a função auxiliar newSettingsGrid. Ela constrói uma grade que deve ser utilizada para o preenchimento de uma ou várias configurações a partir dos nomes ou chaves dessas configurações.

A grade retornada por essa função possui uma configuração básica, com um campo para cada configuração simples e uma grade detalhe para cada uma das configurações de múltiplos valores. Outras regras podem ser adicionadas à grade retornada com o objetivo de melhorar a sua usabilidade. Por exemplo, no código abaixo é adicionado um botão para permitir que novos arquivos sejam carregados no sistema, evitando que o usuário tenha que fazer essa operação em uma outra interface separada do sistema:

const newSettingsGrid = require('@nginstack/web-framework/lib/settings/newSettingsGrid');

this.interaction('main', function () {
  const grid = newSettingsGrid('wf.login.backgroundImages', {
    title: 'Imagens de fundo da tela de login'
  });
  grid.on('defineFields', function (evt) {
    const backgroundImages = evt.grid.field('wf.login.backgroundImages');
    backgroundImages.on('defineGrid', function (evt) {
      const grid = evt.field.grid;
      grid.button('Carregar novas imagens', function () {
        process.upload({
          maxFiles: 10,
          accept: 'image/*'
        }).then(function (files) {
          const vfs = dbCache.getTable('iVfs');
          vfs.indexFieldNames = 'iContentSHA256';
          const fileKeys = files.map(function (file) {
            if (vfs.find(file.sha256)) {
              return vfs.num('iKey');
            } else {
              return file.uploadToVfs(-1892602438); // Background images
            }
          });
          const ds = grid.ds;
          const state = ds.backupState();
          try {
            ds.indexFieldNames = 'value';
            fileKeys.forEach(function (fileKey) {
              if (!ds.find(fileKey)) {
                grid.insert();
                grid.field('value').setValue(fileKey);
                grid.post();
              }
            });
          } finally {
            ds.restoreState(state);
          }
        }).catch(function (e) {
          const msg = 'Erro na operação de upload: ' + e.message;
          process.alert(msg);
        });
      });
    });
  });
  grid.write();
});

Processos auxiliares

Tipos de configurações

Caminho: Desenvolvimento > Configurações gerais > Tipos de configurações.

Processo auxiliar onde podem ser visualizados todos os tipos de configurações suportados pela classe GeneralSettings. Como a criação de novos tipos exige a revisão dessa classe, este processo não deve ser utilizado com objetivo de definir novos tipos.

Sincronizar configurações gerais

Caminho: Desenvolvimento > Atualização > Sincronizar configurações gerais.

Processo que permite sincronizar as configurações gerais de uma base de dados a partir de uma outra. Mais detalhes no manual Sincronizar configurações gerais.

Última atualização em 11 Sep 2023