Tipo de página

Wizard: um cadastro longo, quebrado em etapas.

Esta admissão roda no app de exemplo, publicado no Teste Online. São quatro etapas: dados gerais, endereço, conta bancária e resumo. Cada uma grava na sua tabela e é validada antes de avançar.

Quatro etapas, com o caminho todo à vista

No topo, cada etapa tem um ícone e mostra se está feita, em andamento ou pendente. Quem preenche vê só os campos daquele momento, em vez de uma tela com 40 campos.

Primeira etapa da admissão de pessoa, com nome, documento e as quatro etapas indicadas no topo — Na etapa 1, dados gerais, as quatro etapas já aparecem no topo da tela.

Cada etapa grava numa tabela

Cada seção do formulário (<mad-form-section>) vira uma etapa. O nome da seção diz em qual tabela aquele bloco grava. Aqui são três: pessoa, endereço e conta bancária.

resources/views/…blade.php

<mad-form submit="onSave"><mad-form-section title="Dados gerais" icon="clipboard-list" name="dados"><mad-form-grid :cols="2"><mad-input-field name="nome" label="Nome" :required="true" /><mad-input-field name="documento" label="Documento" :required="true" /></mad-form-grid></mad-form-section><mad-form-section title="Endereço" icon="map-pin" name="endereco__"><mad-form-grid :cols="2"><mad-input-field name="rua" label="Rua" /><mad-dbcombo-field name="cidade_id" label="Cidade" model="Cidade" display="{nome}" /></mad-form-grid></mad-form-section>...</mad-form>

Segunda etapa da admissão, com rua, número, bairro, CEP e a cidade escolhida numa lista — Na etapa 2, endereço, a lista de cidades vem do banco e a etapa 1 já aparece concluída.

Só avança com a etapa válida

O botão Avançar só passa se a etapa estiver válida. O erro aparece no próprio campo, e as etapas já concluídas seguem marcadas. Voltar não apaga nada do que foi digitado.

Terceira etapa da admissão, com aviso de campo obrigatório embaixo do campo Banco — Na etapa 3, o aviso "O campo conta bancaria banco é obrigatório." segura o avanço, e as etapas 1 e 2 seguem concluídas.

Quando usar o wizard

Use quando um cadastro tem campos demais para uma tela só. Em etapas, quem preenche vê só o que importa agora, sabe quanto falta e corrige o erro na etapa em que ele aconteceu.

Admissão de funcionário (RH). Dados, endereço e conta bancária, como no exemplo acima.
Cadastro de fornecedor (compras). Dados da empresa, contato, conta bancária e os documentos anexados.
Cliente novo (vendas). Dados do cliente, endereço de entrega e condição de pagamento.
Matrícula ou inscrição. Dados do aluno, do responsável e do pagamento, com um resumo para conferir antes de gravar.

Se o cadastro cabe numa tela, ou é uma venda com itens, use o formulário. Se o registro gravado ainda precisa de aprovação, use a fila de aprovação. O agente de IA também gera wizard a partir de uma especificação.

O que você configura

As etapas são as seções do formulário. O indicador de etapas do framework é o <mad-steps>, com um <mad-step> por etapa.

Título, subtítulo e ícone da seção title subtitle icon: O nome do bloco de campos, uma linha de apoio e o ícone.
Formato do indicador variant: O caminho no topo aparece como setas, pontos, números ou uma barra de progresso.
Nome, descrição e ícone da etapa label description icon: O que o indicador mostra em cada etapa, como "Endereço" e uma descrição curta.
Etapa atual current: A etapa em andamento. As anteriores ficam concluídas e as seguintes pendentes, sem você marcar uma por uma.
Método que grava submit: O método chamado ao enviar o formulário, como o onSave do código acima.

O que vai para o projeto Laravel

O wizard é um formulário em etapas: uma classe em app/Control e a view com <mad-form>. No padrão de wizard do framework, o controller cuida das etapas assim:

Avançar confere só a etapa atual. O método onNext valida só as regras daquela etapa, e ninguém vê aviso de um campo que nem apareceu. Voltar (onPrev) só muda de etapa.
Concluir grava numa transação. O método onFinish confere a última etapa e grava numa transação do banco.
A etapa atual fica no controller. Ela é uma propriedade pública ($step), por isso se mantém a cada ida ao servidor.

Como toda tela do MadBuilder, esses arquivos abrem no seu editor, vão para o seu Git e aceitam código à mão em blocos protegidos, que continuam lá quando a tela é gerada de novo. Veja como o código é gerado.

Perguntas sobre o wizard

O wizard grava a cada etapa ou só no final?

Você escolhe entre salvar a cada etapa ou só no final, de uma vez. Nos dois casos, cada etapa pode gravar numa tabela diferente.

O wizard aceita os mesmos campos do formulário?

Aceita. As etapas usam os mesmos tipos de campo do formulário, mais de 40, como lista do banco, data, moeda e upload de arquivo.

Dá pra clicar numa etapa e ir direto para ela?

Dá. O indicador de etapas tem um modo clicável, e um método do controller recebe o clique e decide o que acontece.

E mais

Salvar a cada etapa ou só no finalVoltar sem perder o que já foi digitadoEtapa de resumo antes de gravarÍcone e situação de cada etapa: feita, atual ou pendenteCada etapa pode gravar numa tabela diferenteOs mesmos tipos de campo do formulário, mais de 40

Veja também o Formulário ou os tipos de página.

Crie a conta, monte uma tela, baixe o projeto.

Sem demo agendada e sem call de descoberta. Se o Laravel que sair não passar na revisão do seu time, você perdeu uma tarde.

Testar o app agora Ver o código gerado

Crie a contaBeta aberto, sem cartão.
Monte uma telaNo visual, no código ou pedindo à IA.
Baixe o .zipUm projeto Laravel que roda onde você quiser.