Configurações - Formulários

O que é

Esta página é o painel central de configuração dos formulários do sistema. Para cada entidade (Excursões, Clientes, Dependentes, Guias, Transportes, Veículos, Usuários e Solicitações de cotação) você decide quais campos padrão ficam visíveis e obrigatórios, pode trocar o rótulo mostrado ao usuário, aplicar máscara (CPF, CNPJ, telefone, CEP, etc.) e ainda criar campos personalizados com validação própria.

O usuário normalmente chega aqui para padronizar quais informações são coletadas em cada cadastro, esconder campos que a agência não usa, tornar campos extras obrigatórios em uma jornada específica (por exemplo, exigir RG no cadastro do admin mas não no portal) e adaptar a modal de Cadastro Rápido de Cliente usada em reservas, inscrição de passageiros e vendas de passeio.

Como usar

1. Vá em Configurações > Formulários no sidebar.
2. Selecione a entidade no topo:
   • No desktop, clique em uma das abas (Excursões, Clientes, Dependentes, Guias, Transportes, Veículos, Usuários, Solicitações de cotação).
   • No celular, use o seletor único no topo da página.
3. Em Clientes e Dependentes aparece a pílula Configurar para: Admin / Portal do Cliente / Cadastro Rápido (no caso de Clientes; Dependentes têm apenas Admin e Portal). Escolha o contexto antes de mexer nos campos - as colunas exibidas mudam conforme o contexto:
   • Admin: Visível, Obrigatório, Na Listagem, No Criar, No Editar, Máscara e Label Custom.
   • Portal do Cliente: Visível, Obrigatório, No Criar e No Editar (sem Listagem, Máscara nem Label Custom).
   • Cadastro Rápido: apenas Visível e Obrigatório (a modal não tem lista nem edição).
4. Em Campos Padrão, para cada linha:
   • Marque/desmarque Visível, Obrigatório, Na Listagem, No Criar e No Editar conforme o contexto.
   • Em Admin, escolha a Máscara no select (lista populada pelas máscaras ativas) ou deixe em Nenhuma.
   • Em Admin, preencha Label Custom para sobrescrever o rótulo do campo (o placeholder mostra o rótulo original).
   • Campos marcados com a tag Sistema (laranja) ficam travados como visíveis e obrigatórios - não podem ser desligados.
5. Clique em Salvar Alterações (botão azul no topo ou no rodapé do bloco) para gravar a configuração do contexto atual.
6. Em Campos Personalizados, clique em Novo Campo (botão verde-esmeralda) para abrir a modal:
   • Nome do Campo - obrigatório, até 255 caracteres. A chave interna (field_key) é gerada automaticamente como slug.
   • Tipo de Campo - obrigatório. Tipos disponíveis: Texto, Texto longo, Número, Valor monetário, Data, Data e hora, Seleção única, Seleção múltipla, Sim/Não, E-mail, Telefone, URL/Link, CPF/CNPJ (lista vem de CustomFieldDefinition::getFieldTypes).
   • Seção - agrupa o campo (Dados Pessoais, Endereço, Contato, Observações, Outros etc.).
   • Máscara - opcional, usa as máscaras cadastradas.
   • Placeholder, Valor Padrão e Texto de Ajuda - auxiliam o preenchimento.
   • Opções - aparece quando o tipo é Seleção única ou Seleção múltipla; adicione Valor e Label por linha.
   • Validação: Tamanho Mínimo, Tamanho Máximo e Formato (preset). Selecione Personalizado (avançado) para informar uma regex.
   • Blocos de visibilidade: Admin (Obrigatório, Na listagem, No criar, No editar), Portal do Cliente (Obrigatório, Visível, No criar, No editar - só nas entidades com portal) e Site Público (apenas em Excursões: exibir no card "Informações" da página pública).
   • Na edição, há ainda o toggle Campo ativo para desligar o campo sem excluir.
7. Clique em Criar Campo (ou Atualizar na edição) para gravar.
8. Para reordenar campos personalizados, arraste pelo ícone de três barras (handle) à esquerda da linha. A nova ordem é salva automaticamente e aparece o toast Ordem atualizada..
9. Para excluir um campo personalizado, clique no ícone de lixeira e confirme o modal Tem certeza que deseja remover o campo "X"? Todos os valores salvos serão perdidos. - a remoção é em cascata e definitiva.

Casos especiais

Contexto Portal do Cliente (Minha Conta)

Aparece apenas para Clientes e Dependentes (definido em EntityFieldConfig::getPortalEntities). Permite configurar separadamente o que o cliente final vê no portal sem mexer na visualização do admin. As colunas Na Listagem, Máscara e Label Custom ficam ocultas neste contexto.

Contexto Cadastro Rápido

Aparece apenas para Clientes (definido em EntityFieldConfig::getQuickCreateEntities). Controla a modal de cadastro rápido usada em reservas, inscrição de passageiros e vendas de passeio. Por padrão, só o campo Nome vem visível e obrigatório - os demais entram conforme você marcar. O campo Nome é fixo como obrigatório (marcado pela UI).

Campos do Sistema (fixed_required)

Campos com a tag laranja Sistema (por exemplo, Nome do cliente) ficam com os checkboxes Visível e Obrigatório desabilitados e marcados. O controller envia um hidden=1 para preservar o estado mesmo se o usuário tentar alterar via DevTools.

Contato de Emergência obrigatório

Quando a entidade é Clientes, abaixo dos blocos de campos aparece o card Contato de Emergência. O toggle Tornar obrigatório chama imediatamente o endpoint toggle-setting e exibe o toast Contato de emergência agora é obrigatório (ou opcional). A regra força o preenchimento de nome, telefone e parentesco do contato de emergência no cadastro de clientes e dependentes.

Card público da excursão

Na modal de criação/edição de campo personalizado, quando a entidade é Excursões, aparece a seção Site Público com a opção Exibir no card "Informações" da página da excursão. Quando ativada, o valor preenchido aparece junto com data, saída e duração no card do site.

Validação com regex personalizada

No bloco Validação da modal, escolher Personalizado (avançado) no select Formato revela o campo Expressão Regular (regex). Aceita padrões no estilo /^[A-Z0-9]+$/. Use os presets (E-mail, CPF, CNPJ, URL etc.) sempre que possível - eles já trazem mensagem amigável.

Reordenação por drag-and-drop

A ordem dos campos personalizados é definida arrastando pelo handle (ícone de três barras) na primeira coluna. A persistência usa o endpoint custom.reorder, que recebe o array de IDs e atualiza a coluna ordem. Não há botão de "salvar ordem" - é automático.

Gerenciar Máscaras

O botão Gerenciar Máscaras no cabeçalho leva para /admin/configuracoes/formularios/mascaras, onde você pode criar máscaras personalizadas (nome, padrão, exemplo e categoria). Máscaras do tipo sistema não podem ser editadas nem removidas - só as custom criadas por você.

Erros comuns e como resolver

• "O campo nome do campo é obrigatório." - Causa: tentou salvar campo personalizado sem preencher o Nome do Campo. Solução: preencher antes de submeter.
• "O campo tipo de campo é inválido." - Causa: alteração via DevTools enviou tipo fora da lista válida. Solução: usar o select padrão da modal.
• "required_with" em options - Causa: marcou tipo Seleção única/múltipla e deixou linhas de opção com Valor ou Label vazios. Solução: preencher os dois ou remover a linha clicando no X.
• "Máscaras do sistema não podem ser editadas." - Causa: tentou editar uma máscara nativa em /admin/configuracoes/formularios/mascaras. Solução: criar uma máscara custom com o ajuste desejado.
• "Máscaras do sistema não podem ser removidas." - Causa: tentou deletar máscara nativa. Solução: somente máscaras custom podem ser removidas.
• Toast "Erro ao salvar configuração" - Causa: falha no toggle do contato de emergência (sem conexão ou sessão expirada). Solução: recarregar a página e tentar novamente.
• Toast "Erro ao salvar a ordem." - Causa: falha na reordenação drag-and-drop. Solução: recarregar e refazer a movimentação.

Onde encontrar

• URL: /admin/configuracoes/formularios
• Caminho no menu: Configurações > Formulários
• Permissão necessária: ver as configurações (acessar) e editar as configurações (salvar)
• Módulo necessário: nenhum

Veja também

• Configurações - Formulário de Inscrição
• Cadastros - Configurar Cadastros Personalizados