Enspace Docs

Eventos em Campos

A funcionalidade Eventos em Campos permite configurações automáticas em campos de formulários, executadas quando o valor de um campo é alterado (commit).

Cada campo pode possuir uma ou mais regras de evento, totalmente configuráveis pelo usuário.

Estrutura do Evento

1. Momento do Disparo

Define quando o evento será executado.

  • Opções: Editado, Excluído.

2. Tipo de Ação

Define o que o evento fará.

  • Exemplos: Editar Campos, Resetar Campos.

3. Campos Alvo da Ação

Lista dos campos que serão afetados pela ação.

  • Campo: Referência do campo alvo (usar apenas a referência pura, sem chaves).
    • Exemplo: exemplo_de_campo
  • Valor: Expressão ou valor atribuído ao campo.
    • Exemplo: {{exemplo_com_expressao}}

4. Condicionais (Opcional)

Conjunto de condições que determinam quando o evento deve ser executado.

  • Ramo “and”: Todas as condições devem ser verdadeiras.
  • Ramo “or”: Pelo menos uma condição deve ser verdadeira.

Nota: Cada condição é composta por: { Referência, Operador, Valor }.

Regras e Limitações

Campos Restritos

Alguns tipos de campo não podem ser alterados por eventos:

  • EnMatrix
  • checkbox
  • multiSelect
  • uploadFile
  • uploadImage
  • EnOnlyoffice
  • EnPDF
  • EnESign
  • EnlChips
  • EnRelMulti
  • EnChats
  • EnNotes
  • EnRepeater

Referências de Expressões

As expressões usadas nos eventos podem referenciar:

  1. Dados do formulário: (form_value)
  2. Dados do item relacionado: (item_related)

Casos de Uso

A utilização de eventos permite automatizar o comportamento do formulário, sendo os cenários mais comuns:

  • Preenchimento Automático: Preencher automaticamente outro campo ao editar um campo principal.
  • Reset de Campos: Resetar um grupo de campos ao alterar um seletor (ex: mudar a categoria limpa os detalhes).
  • Lógica Condicional: Aplicar mudanças dinâmicas em campos baseadas em condições específicas.

Dados Disponíveis nas Expressões

Ao construir as expressões para os campos alvo, você pode utilizar os seguintes objetos:

1. Dados do Formulário (form_value)

Acessa qualquer valor presente no formulário atual.

  • Exemplo: {{form_value.nome_do_contratante}}

2. Valor do Disparador (payload)

Acessa o valor exato do campo que acabou de acionar o evento.

  • Exemplo: {{payload}}

3. Itens Relacionados (item_related)

Acessa dados de registros vinculados.

Nota: Disponível apenas quando o campo disparador é do tipo Relacionamento ou Relacionamento Múltiplo.

  • Exemplo: {{item_related.data.valor_do_contrato}}

Exemplo Prático

Cenário: Sincronização de endereço.

No exemplo abaixo, configuramos um evento no campo "Endereço principal":

  1. Gatilho: Disparado quando o campo for Editado.
  2. Ação: Editar Campos.
  3. Configuração do Alvo:
    • Campo: correspondencia
    • Valor: {{payload}} (ou seja, o mesmo valor digitado no endereço principal).
Visualização do campo Endereço Principal

Condicional do Exemplo

Além das configurações anteriores, o evento possui uma regra lógica de execução:

  • Regra: O evento só será executado se o campo endereco_igual_correspondencia for igual a "Sim".

Isso garante que a automação respeite a escolha do usuário antes de sobrescrever os dados no campo de correspondência.

Condicional do Exemplo

Benefícios

A implementação desta funcionalidade traz diversas vantagens estratégicas para o desenvolvimento:

  • Redução de Código: Diminui drasticamente a necessidade de scripts customizados para validações simples.
  • Centralização: Mantém a lógica de interação diretamente no esquema (schema) de campos.
  • Escalabilidade: Facilita a manutenção e permite o reaproveitamento das regras em múltiplos formulários.

Condição Especial de Uso: Valor Monetário

O campo do tipo Valor Monetário permite trabalhar com valores em dinheiro e pode ser utilizado tanto para receber informações quanto para interagir com outros campos por meio de eventos.

Como editar um campo “Valor Monetário”

Para editar um campo do tipo Valor Monetário, o valor enviado precisa ser válido. Isso significa que ele deve ser:

  • Um número: Pode ser proveniente de qualquer outro campo.
  • O valor de outro campo do tipo Valor Monetário.

Usando o “Valor Monetário” para editar outros campos

O campo Valor Monetário também pode ser usado para alterar outros campos através de eventos. Você pode utilizar o valor completo do campo ou acessar informações específicas, como:

  • {{payload}} → Valor completo do campo.
  • {{payload.value}} → Valor numérico (apenas os números).
  • {{payload.currency}} → Moeda utilizada (ex: BRL, USD).

Como o valor é armazenado

O campo Valor Monetário não armazena apenas um número simples. Ele é um objeto composto por um conjunto de informações estruturadas:

  • value: Valor numérico atual processado pelo sistema.
  • originalValue: Valor original que foi informado inicialmente.
  • currency: Moeda do valor (ex: "BRL", "USD").
  • config: Configurações técnicas e metadados do campo.

Exemplo de valor armazenado:

{
  "currency": "BRL",
  "value": 1000,
  "originalValue": 1000
}

Definindo valores iniciais

Também é possível definir um valor inicial para o campo Valor Monetário. Esse valor pode ser configurado das seguintes formas:

  • Número estático: Um valor numérico fixo definido diretamente na configuração.
  • Valor dinâmico: O valor proveniente de outro campo do tipo Valor Monetário.

Observação Importante

Nos exemplos e descrições acima, textos no formato "referencia_campo" representam as referências reais (slugs/IDs) dos campos utilizados na configuração dos eventos.

Campos
Endereço