Formulário
Antes de escolher os campos, você monta o esqueleto: seções que agrupam assuntos, linhas que dividem a largura em colunas, e a barra de ações no rodapé. Você não escreve código nem CSS: arrasta a estrutura e o formulário já nasce alinhado e responsivo.
Quando usar cada peça
Um formulário do MadBuilder é feito de cinco peças de estrutura. Elas não guardam dado nenhum — servem para organizar os campos que guardam.
| Você quer | A peça certa |
|---|---|
| Agrupar campos do mesmo assunto, com título | Seção |
| Colocar dois ou três campos lado a lado | Linha |
| Fazer um campo ocupar o dobro da largura | Coluna |
| Empilhar coisas uma embaixo da outra, com espaço igual | Pilha |
| Separar dois blocos com um traço | Separador |
| A tela ficou longa demais e ninguém acha nada | Abas e cards |
| Mostrar vários registros numa grade, não um por vez | Listagem |
| Uma tabela que só tem um registro (parâmetros, configurações) | Formulário do tipo Registro único |
Montar o esqueleto
- Abra o formulário no Studio.
- Clique com o botão direito dentro da tela, no ponto onde o bloco deve entrar.
- No menu, o grupo Estrutura do Formulário traz Seção, Linha, Coluna, Pilha e Separador.
- Escolha Seção para começar: quase toda tela é uma seção com linhas dentro.
- Clique na seção recém-criada para o painel da direita mostrar as opções dela.
Dar identidade à seção
- Selecione a seção e abra Identificação no painel.
- Título: o texto que aparece acima do bloco. É o que a pessoa lê.
- Subtítulo: uma linha de apoio, opcional — bom para explicar o que preencher ali.
- Ícone: um desenho ao lado do título.
- Mostrar cabeçalho: desligue quando o formulário abre em cortina lateral. A cortina já mostra o título da tela no alto, e a seção repetiria o mesmo título logo abaixo.
- Se a seção guarda dados de outra tabela (o endereço de um cliente, por exemplo), abra Fonte de dados e preencha Tabela vinculada.

Passe o mouse na lista — ou use ↑ ↓ depois de focar um item.
Dividir a largura em colunas
A Linha divide o espaço horizontal em partes iguais, e cada campo solto nela ocupa uma parte. A Coluna é a peça que você acrescenta quando um campo precisa ocupar mais de uma.
- Dentro da seção, adicione uma Linha.
- Selecione a linha e, em Layout, escolha Colunas — 2 é o mais comum, 3 cabe em campos curtos.
- Arraste os campos para dentro da linha. Cada um ocupa uma parte, na ordem em que estão. A tela gerada pelo assistente já vem assim: os campos direto na Linha, sem Coluna.
- Precisa de um campo mais largo? Selecione a linha e clique em Adicionar coluna nesta linha, na barra que aparece sobre ela — ou escolha Coluna no menu do botão direito. Arraste o campo para dentro da Coluna e, no painel dela, aumente Colunas (span).


Fechar a tela: separador e barra de ações
- Entre dois blocos que não têm relação, adicione um Separador — um traço fino que dá respiro.
- No fim do formulário, use a barra de ações para os botões de salvar, cancelar e o que mais a tela precisar.
- Selecione o Formulário (o bloco de fora, na trilha do topo do painel) para configurar Ao salvar.
form › form-section › form-grid)
mostra onde você está. Clicando num nome dela você sobe um nível — é o jeito mais rápido de
selecionar a linha ou a seção sem caçar no canvas.Testar antes de entregar
Salve a tela e publique no Teste online. Confira nesta ordem:
| O que fazer | O que tem que acontecer |
|---|---|
| Abrir a tela no computador | Os campos aparecem lado a lado, na quantidade de colunas escolhida. |
| Estreitar a janela até o tamanho de um celular | Os campos se empilham, um por linha, sem cortar nada. |
| Ler os títulos das seções | Cada bloco diz de que assunto ele trata. |
| Preencher e salvar | Os valores vão para a tabela da tela — e, nas seções vinculadas, para a tabela vinculada. |
| Reabrir o registro salvo | Todos os blocos voltam preenchidos. |
Problemas comuns
Os campos ficam um embaixo do outro, mesmo em tela grande
Eles não estão dentro de uma Linha. Campo solto dentro da seção ocupa a largura toda. Adicione uma Linha e arraste os campos para dentro dela.
Um campo ficou espremido e o vizinho sobrando
Campos soltos na Linha dividem a largura em partes iguais. Ponha o campo que precisa de mais espaço dentro de uma Coluna e aumente Colunas (span) nela. A soma dos spans não deve passar do número de Colunas da linha: o editor não confere, e um span maior desalinha a linha sem aviso.
Salvei e os valores de um bloco não foram para a tabela
A seção está com Tabela vinculada preenchida (ou vazia quando deveria estar preenchida). Confira em Fonte de dados: é esse campo que decide o destino dos campos de dentro.
A tela ficou enorme e ninguém acha o que procura
Passou do ponto em que seções resolvem. Divida em abas — cada aba com as suas seções.
Quem preenche a cortina lateral aperta Esc sem querer e perde o que digitou
Abra as Propriedades da página e, com Tipo de exibição em Cortina lateral ou
Modal (centralizado), ligue Confirmar antes de fechar com alterações. Com algo
digitado e não salvo, Esc e o X passam a perguntar antes de descartar; Salvar,
Cancelar e Voltar continuam fechando direto. No código da tela, o interruptor grava
protected static bool $confirmDiscard = true;. Uma <mad-drawer> ou <mad-modal> montada
dentro da tela faz o mesmo com o atributo confirm-close.
O usuário precisa ver a tela de trás para preencher o modal
Abra as Propriedades da página e, com Tipo de exibição em Modal (centralizado),
ligue Arrastar pelo cabeçalho. O usuário segura o cabeçalho e leva a janela para o lado;
ela não sai da área visível e volta ao centro quando a tela é aberta de novo. Os botões do
cabeçalho continuam funcionando, e no celular a janela fica fixa. No código da tela, o
interruptor grava protected static bool $draggable = true;. Uma <mad-modal> montada
dentro da tela faz o mesmo com o atributo draggable, desde que tenha title.
A tabela de parâmetros não pode ganhar um segundo registro
Crie a tela como Nova página → Formulário → Registro único. Ela vai direto para o menu e abre já com o registro carregado; não há listagem nem botão Novo. Salvar sempre atualiza o mesmo registro — na primeira vez, com a tabela vazia, ele é criado. Em sistemas com várias empresas, cada empresa tem o seu.
Referência: painel × código
Para quem também mexe no Blade, este é o de-para entre o painel e os atributos gerados.
| No painel | No código | Padrão |
|---|---|---|
| Título | title | — |
| Subtítulo | subtitle | — |
| Ícone | icon | — |
| Mostrar cabeçalho | no-header | ligado |
| Tabela vinculada | detail-table | a tabela da tela |
| Nome (id da seção) | name | — |
| Seção pai (cadeia) | parent | — |
| Colunas (da Linha) | :cols | 2 |
| Template colunas | template | colunas iguais |
| Espaço entre linhas (da Linha e do Formulário) | row-gap | o do tema; sem tema, 16px na seção |
| Colunas (span) (da Coluna) | span | 1 |
| Coluna inicial | start | a próxima livre |
| Gap (px) (da Pilha) | gap | — |
| Ao salvar | submit | onSave |
| Espaço do label | label-gap | 5px (do tema) |
| Cor do label (Estilo do label) | label-color | a do tema |
| Tamanho do label | label-size | 11px |
| Peso do label | label-weight | negrito |
| Label em itálico | label-italic | desligado |