Eventos de Campo
Automatize o comportamento dos formulários
Os Eventos de Campo permitem configurar regras que são executadas automaticamente — e em tempo real — enquanto o usuário preenche um formulário. Com eles, você pode preencher campos automaticamente, limpar valores, bloquear envios e recarregar dados, tudo de forma reativa e customizável.
Os eventos são configurados na aba Eventos de Campo dentro da configuração de cada campo, em Configurações > Estrutura > Categorias > Campos.
Os eventos funcionam em formulários de criação e edição de itens, sendo eles acessados tanto pela tela nativa de itens (botão de ações ou criação pela tabela) quanto pelo botão de editar na tela dedicada do item.
O que você pode fazer com eventos
| Caso de uso | O que faz | Exemplo |
|---|---|---|
| Preenchimento automático | Atualiza campos relacionados assim que um valor é informado. | Ao selecionar um cliente no campo de relacionamento, o CNPJ, o endereço e o e-mail de contato são preenchidos automaticamente com os dados cadastrados daquele cliente. |
| Reset inteligente | Limpa o valor de campos dependentes quando uma seleção principal muda. | Ao trocar a categoria de um chamado de "Financeiro" para "Jurídico", os campos de subcategoria, prioridade e responsável são limpos automaticamente para evitar dados inconsistentes. |
| Lógica condicional | Aplica mudanças dinâmicas apenas quando determinadas condições são atendidas. | Ao preencher a nota de avaliação de um fornecedor com valor abaixo de 5, o campo "Classificação de Risco" é automaticamente preenchido com "Alto Risco". Se a nota for 5 ou mais, nada acontece. |
| Validação em tempo real | Bloqueia o envio do formulário se um campo não atender a critérios específicos. | Se o valor do contrato for maior que R$ 50.000 e o campo "Aprovação da Diretoria" estiver vazio, uma mensagem vermelha é exibida e o formulário não pode ser enviado. |
| Recarregamento de lógica | Reprocessa condicionais e validações de um campo sem alterar seu valor. | O campo "Filial" só aparece quando "Região" está preenchido. Ao se tornar visível, um evento recarrega o campo de origem para que "Filial" receba o valor que não conseguiu receber antes. |
Anatomia de um evento
Todo evento segue o mesmo fluxo:
Quando um campo dispara um evento, o ENSPACE avalia as condicionais configuradas e executa ações nos campos alvo. Essas ações podem atualizar outros campos e disparar novos eventos automaticamente.
1. Gatilho
Define quando o evento dispara.
Pense no gatilho com a pergunta "o que eu quero que dispare a ação no meu formulário?"
| Gatilho | O evento dispara quando o campo for... |
|---|---|
| Editado | Alterado pelo usuário (o evento dispara no momento em que o dado é confirmado no campo). |
| Resetado | Restaurado ao valor inicial. |
| Ao aparecer em tela | Exibido no formulário (útil para campos condicionais que aparecem dinamicamente). |
2. Ação
Define o que o evento faz.
Pense na ação com a pergunta "o que eu quero que aconteça?".
| Ação | Comportamento |
|---|---|
| Editar Campos | Atribui um novo valor aos campos alvo. O valor configurado sobrescreve qualquer valor existente no campo. |
| Resetar Campos | Limpa o valor dos campos alvo, restaurando-os ao estado inicial. |
| Invalidar Campos | Bloqueia o envio do formulário enquanto a condição for atendida. Uma mensagem vermelha é exibida abaixo do campo com o texto configurado, e o formulário não pode ser enviado até que a condição deixe de ser verdadeira. Requer configuração de condicionais. |
| Recarregar Campos | Reprocessa a lógica do campo alvo (condicionais de visibilidade, obrigatoriedade, validações e filtros dinâmicos de listas e relacionamentos) sem alterar o valor que já está preenchido. |
O Recarregar é essencial em cenários de encadeamento de eventos com campos condicionais. Quando um evento preenche dois campos ao mesmo tempo — por exemplo, "Região" e "Filial" — mas "Filial" só aparece no formulário quando "Região" está preenchido, o valor de "Filial" pode não ser aplicado porque o campo ainda não estava visível no momento do disparo. A solução é configurar um evento no campo "Filial" com o gatilho Ao aparecer em tela e a ação Recarregar Campos, apontando para o campo de origem. Assim, quando "Filial" se torna visível, o campo de origem é recarregado e o evento original é redisparado, preenchendo "Filial" corretamente.
3. Campos alvo
Lista dos campos que serão afetados pela ação. O que você precisa informar varia conforme a ação:
| Ação | O que informar |
|---|---|
| Editar Campos | Campo (referência técnica, sem chaves) + Valor (expressão ou valor fixo) |
| Resetar Campos | Campo (referência técnica, sem chaves) |
| Invalidar Campos | Campo (referência técnica, sem chaves) + Mensagem de bloqueio (texto exibido ao usuário) |
| Recarregar Campos | Campo (referência técnica, sem chaves) |
{{}} nem data. no campo "Campo"?Em variáveis (como
{{data.nome_cliente}}), as chaves duplas {{}} indicam que você quer buscar o valor armazenado naquele campo — o dado varia conforme o item, por isso é uma variável. Já no campo "Campo" dos eventos, você está apenas apontando para o campo em si — dizendo ao sistema qual campo deve ser afetado pela ação. Não é um valor dinâmico, é uma referência fixa. Por isso, não precisa de chaves duplas.Quanto ao data.: no ENSPACE, data é o agrupamento interno que contém todos os campos personalizados criados por você. Campos como created_at ou reference são metadados do sistema e ficam fora de data. Por isso, nas variáveis, usamos {{data.nome_cliente}} — para entrar nesse agrupamento e acessar o valor do campo. Nos eventos, porém, o sistema já opera dentro do contexto dos campos da categoria, então o prefixo data. é desnecessário. Basta usar a referência direta: nome_cliente.4. Condicionais (opcional)
Determinam se o evento deve ser executado. Cada condição é formada por três elementos: Referência, Operador e Valor.
As condições podem ser combinadas em dois ramos:
| Ramo | Lógica |
|---|---|
| E | Todas as condições devem ser verdadeiras. |
| OU | Pelo menos uma condição deve ser verdadeira. |
A ação Invalidar Campos requer obrigatoriamente pelo menos uma condicional configurada — é ela que define quando o bloqueio será ativado.
Para entender em profundidade quando usar
data., {{}}, referência direta e % nos diferentes contextos do ENSPACE, consulte Referências e variáveis.Expressões nos valores
Ao definir o valor de um campo alvo na ação Editar Campos, você pode usar expressões com chaves duplas ({{ }}) para acessar dados dinamicamente. Existem três fontes de dados:
| Fonte | Descrição | Quando usar |
|---|---|---|
form_value | Valores que o usuário já preencheu no formulário atual, antes do envio. | Acessar qualquer campo do formulário. |
payload | Valor exato do campo que acabou de disparar o evento. | Copiar o valor do campo gatilho para outro campo. |
item_related | Dados do item vinculado. Disponível apenas quando o campo gatilho é do tipo Relacionamento ou Relacionamento Múltiplo. | Preencher campos com dados do item relacionado. |
Para expressões avançadas que envolvem condicionais (
if), iterações (each) ou manipulação complexa de listas de objetos, habilite a opção Expressão Complexa no evento. Essa opção expande as capacidades das expressões nos campos alvo, permitindo o mesmo nível de flexibilidade disponível em campos virtuais.Expressões complexas podem impactar a performance do formulário. Utilize essa opção apenas quando necessário e prefira expressões simples para cenários básicos.
O prefixo {{~v2}}
Ligar a opção Expressão Complexa é só a metade da configuração. Toda expressão complexa precisa começar com o prefixo {{~v2}}, que informa ao sistema que o conteúdo do campo Valor deve ser interpretado como uma expressão baseada em Handlebars.
Sem o prefixo, o conteúdo é tratado como texto comum e nenhum helper funciona. O campo é preenchido com a expressão literal, em vez do resultado dela.
Com o prefixo, o campo passa a aceitar toda a sintaxe de templates Handlebars, incluindo {{#each}}, {{#if}}, {{#with}} e os demais helpers.
Exemplo — percorrer um Relacionamento Múltiplo e concatenar um campo de cada item relacionado:
{{~v2}}{{#each item_related}}{{data.cidade}};{{/each}}
Ao selecionar três fornecedores no formulário, o campo alvo é preenchido com São Paulo;Rio de Janeiro;Curitiba;.
Esse é o caso que a Expressão Complexa resolve: eventos de campo passam a consumir listas de um Relacionamento Múltiplo, da mesma forma que já consumiam os dados de um Relacionamento Simples.
Como montar uma expressão
Combine a fonte de dados com a referência técnica do campo dentro de chaves duplas:
| Expressão | O que acessa |
|---|---|
{{form_value.nome_cliente}} | O valor do campo nome_cliente preenchido no formulário. |
{{payload}} | O valor completo do campo que disparou o evento. |
{{payload.reference}} | A referência do item selecionado (para campos de Relacionamento). |
{{item_related.data.nome}} | O campo nome do item relacionado ao campo de Relacionamento. |
Expressões matemáticas também são suportadas no campo Valor:
{{form_value.preco}} * {{form_value.quantidade}}
Expressões matemáticas não funcionam com campos do tipo lista (repetidor). Para somar valores de listas, utilize
sumArray(). Consulte Expressões.
Passo a passo: habilitar uma expressão complexa em um evento
A coluna Expressão Complexa muda como o valor é interpretado, e o prefixo no início do campo é obrigatório:
Abra a aba Eventos de Campo
Na configuração do campo, vá até a aba Eventos de Campo.
Crie o evento
Clique em Adicionar evento.
Aponte o campo de destino
Em Campo, informe a referência técnica do campo que vai receber os valores.
Ligue a Expressão Complexa
Ative o botão da coluna Expressão Complexa.
Comece pelo prefixo
Em Valor, abra com {{~v2}}. É esse prefixo que faz o sistema ler o conteúdo como expressão.
Escreva e salve
Com a expressão pronta, aqui um {{#each}} percorrendo os relacionados, clique em Salvar.
Confira no formulário
No item, selecione vários relacionados e veja o campo preenchido sozinho.
Tipos especiais de campo em eventos
A maioria dos campos armazena valores simples (texto ou número). Alguns tipos, porém, armazenam um conjunto de informações (um "objeto"). Ao usá-los em eventos, é importante saber como acessar cada parte.
Relacionamento Simples
Armazena três propriedades: reference (identificador do item), id (código interno) e display (nome de exibição).
| Expressão | O que retorna |
|---|---|
{{payload}} | Objeto completo — use para copiar para outro campo de Relacionamento Simples. |
{{payload.reference}} | Referência do item selecionado. |
{{payload.id}} | ID interno do item. |
{{payload.display}} | Nome de exibição do item. |
Relacionamento Múltiplo
Armazena uma lista de objetos, cada um com reference, id e display.
| Expressão | O que retorna |
|---|---|
{{payload}} | Lista completa — use para copiar para outro campo de Relacionamento Múltiplo. |
{{payload[0].reference}} | Referência do primeiro item da lista. Use [1], [2] etc. para outros itens. |
{{payload[0].display}} | Nome de exibição do primeiro item. |
Iteração em listas de relacionamento
Quando você precisa percorrer todos os itens relacionados e extrair valores de um campo específico, utilize expressões que tratam a lista completa:
| Expressão | O que retorna |
|---|---|
{{payload.map(item => item.data.campo)}} | Lista com os valores do campo campo de todos os itens relacionados. |
{{payload.map(item => item.reference)}} | Lista com as referências de todos os itens relacionados. |
{{payload.map(item => item.display)}} | Lista com os nomes de exibição de todos os itens relacionados. |
Utilize essas expressões para preencher campos de texto ou listas com informações agregadas dos itens relacionados. Por exemplo, ao selecionar vários advogados em um campo de relacionamento múltiplo, é possível extrair as inscrições de todos eles e preencher automaticamente um campo de texto com esses valores.
Repetidor
Armazena uma lista de objetos, cada um correspondendo a uma linha do repetidor.
| Expressão | O que retorna |
|---|---|
{{payload}} | Lista completa — use para copiar para outro Repetidor com a mesma estrutura. |
{{payload[0].campo_interno}} | Valor de um subcampo da primeira linha. |
Valor Monetário
Armazena value (valor numérico), originalValue (valor original) e currency (código da moeda).
| Expressão | O que retorna |
|---|---|
{{payload}} | Objeto completo — use para copiar para outro campo de Valor Monetário. |
{{payload.value}} | Apenas o valor numérico. |
{{payload.currency}} | Código da moeda (ex: BRL, USD). |
Encadeamento de eventos
Os eventos são encadeáveis: se o evento do campo A edita o campo B, e o campo B possui um evento próprio, esse segundo evento será disparado automaticamente. Isso permite criar cadeias de automação complexas — por exemplo, selecionar um cliente que preenche a região, que por sua vez preenche a filial.
Evite criar eventos que formem loops — por exemplo, um evento no campo A que edita o campo A (a si mesmo), ou um evento no campo A que edita o campo B e um evento no campo B que edita o campo A.
Proteção anti-loop
O ENSPACE possui proteção em duas camadas para evitar que eventos entrem em ciclo infinito:
- Na configuração: quando o gatilho "Editado" e a ação "Editar Campos" são selecionados simultaneamente, o editor de eventos emite um aviso informando que, caso o campo que dispara o evento seja também o campo a ser editado, o evento será desconsiderado para evitar loop.
- Na execução: mesmo que uma combinação não seja detectada na configuração (como loops indiretos entre dois ou mais campos), o sistema conta com um limite de execuções por ciclo. Se uma cadeia de eventos ultrapassar esse limite, ela é interrompida automaticamente — evitando travamentos e inconsistências nos dados.
Exemplos práticos
Básico
Cálculo automático
Cenário: Calcular o valor total de um pedido multiplicando preço pela quantidade.
- Campo gatilho:
quantidade(Número) - Gatilho: Editado
- Ação: Editar Campos
- Campo alvo:
| Campo | Valor |
|---|---|
valor_total | {{form_value.preco}} * {{form_value.quantidade}} |
Reset de campos ao mudar seleção
Cenário: Ao alterar a categoria de um chamado, os campos de detalhe devem ser limpos para evitar inconsistências.
- Campo gatilho:
categoria(Lista de Seleção) - Gatilho: Editado
- Ação: Resetar Campos
- Campos alvo:
subcategoria,descricao_detalhe,prioridade
Intermediário
Preenchimento automático com relacionamento
Cenário: Ao selecionar um contratante (campo Relacionamento), o nome e o valor do contrato são preenchidos automaticamente.
- Campo gatilho:
contratante(Relacionamento Simples) - Gatilho: Editado
- Ação: Editar Campos
- Campos alvo:
| Campo | Valor |
|---|---|
nome_contratante | {{item_related.data.nome}} |
valor_contrato | {{item_related.data.valor_do_contrato}} |
Sincronização de endereço com condicional
Cenário: Se o usuário responder "Sim" à pergunta "O endereço de correspondência é o mesmo?", o endereço de correspondência é preenchido automaticamente com o valor do endereço principal.
- Campo gatilho:
endereco_principal(Endereço) - Gatilho: Editado
- Ação: Editar Campos
- Campo alvo:
| Campo | Valor |
|---|---|
correspondencia | {{payload}} |
- Condicional:
| Referência | Operador | Valor |
|---|---|---|
endereco_igual_correspondencia | igual a | Sim |
Avançado
Validação com bloqueio de envio
Cenário: Se o valor do contrato for maior que R$ 50.000, o campo de aprovação da diretoria deve estar preenchido para permitir o envio.
- Campo gatilho:
valor_contrato(Valor Monetário) - Gatilho: Editado
- Ação: Invalidar Campos
- Campo alvo:
| Campo | Mensagem de bloqueio |
|---|---|
aprovacao_diretoria | Contratos acima de R$ 50.000 exigem aprovação da diretoria. |
- Condicional:
| Referência | Operador | Valor |
|---|---|---|
valor_contrato | maior que | 50000 |
Recarregar campo condicional
Cenário: O campo "Filial" só aparece quando "Região" está preenchido. Um evento preenche ambos automaticamente, mas "Filial" fica vazio porque ainda não estava visível no momento do disparo. A solução é recarregar o campo de origem quando "Filial" aparece.
- Campo gatilho:
filial - Gatilho: Ao aparecer em tela
- Ação: Recarregar Campos
- Campo alvo:
negocio_relacionado(o campo de relacionamento que origina os dados) - Condicional:
| Referência | Operador | Valor |
|---|---|---|
item_related | preenchido | — |
Quando "Filial" se torna visível, o campo de relacionamento é recarregado, seus eventos são redisparados e "Filial" recebe o valor correto.
Erros comuns
| Problema | Causa provável | Como resolver |
|---|---|---|
| O evento não dispara | Condicional mal configurada ou campo gatilho incorreto. | Verifique se as condições estão corretas e se o campo gatilho é o que realmente está sendo editado. |
| O campo alvo não é atualizado | O campo alvo é de um tipo restrito. | Consulte a lista de campos que não podem ser alvo abaixo. |
| Erro na expressão | Chaves incorretas ou referência inexistente. | Use chaves duplas no valor ({{referencia}}). No campo "Campo", use a referência pura, sem chaves. |
| Dados do item relacionado não aparecem | Uso de item_related em campo que não é de Relacionamento. | item_related só funciona quando o gatilho é um campo de Relacionamento ou Relacionamento Múltiplo. |
| Dois eventos conflitam no mesmo campo alvo | Ordem de execução imprevisível. | Evite configurar múltiplos eventos que editam o mesmo campo alvo. O último a ser processado prevalece, e a ordem não é garantida. |
Campos que não podem ser alvo de eventos
Os seguintes tipos de campo não podem ser editados, resetados ou recarregados por eventos:
Matriz de Dados, Caixas de Seleção, Lista de Seleção Múltipla, Arquivo, Imagem, Editor de Documentos, PDF, Assinatura Eletrônica, Tags, Chat e Anotações.