Docs›Componentes (Admin)›mad-db-steps
Componentes (Admin)

mad-db-steps

Indicador de etapas auto-query via model Eloquent (versão DB do mad-steps).

Indicador de progresso em etapas alimentado automaticamente do banco via model Eloquent. E a versao auto-query do <mad-steps>: voce informa o model e os steps sao carregados, ordenados e marcados conforme o value atual — sem precisar declarar <mad-step> filhos.

Para steps declarativos (estaticos no Blade), use <mad-steps> (ver steps-rules.md).

Diferenca para <mad-steps>

<mad-steps> <mad-db-steps>
Origem dos steps Filhos <mad-step> declarados no Blade Auto-query via model Eloquent
Step ativo Prop current (1-based, indice) Prop value (ID do registro)
Cor por step Prop estatica no <mad-step> Campo do model via color-field
Quando usar Wizard de form, fluxo fixo Etapas vindas de tabela (kanban, pipeline)

Internamente, o <mad-db-steps> carrega os registros e delega o render para components.steps — ou seja, todas as variantes visuais do <mad-steps> valem aqui (arrows, dots, numbers, progress).

Props

Prop Tipo Default Descricao
model string '' Classe do model Eloquent (ex: EtapaNegociacao) — obrigatorio
database string MAIN_DATABASE Conexao do banco
key string 'id' Campo da PK
display string 'nome' Campo do label de cada step
color-field string '' Campo do model com a cor (aplica cor customizada por step)
order-by string 'id asc' Ordenacao SQL
filters array [] Filtros: [['campo','op','val'], ...] (suporta subselect com ?)
value string '' ID do step ativo (registro selecionado)
variant string 'arrows' arrows, dots, numbers, progress
clickable bool false Steps completos sao clicaveis
size string '' sm, '' (normal), lg
class string '' Classes CSS extras
mad:click string '' Metodo PHP chamado ao clicar (recebe a key do step)

Comportamento de status (auto)

A partir do value (ID), o componente calcula a posicao do step ativo e marca:

  • Steps anteriores → completed
  • Step do value → active
  • Steps posteriores → pending

Se o value nao bater com nenhum registro, current = 0 (nenhum ativo).

Uso basico

<mad-db-steps model="EtapaNegociacao" database="minierp"
    display="nome" order-by="ordem asc"
    :value="$negociacao->etapa_id" />

Variant arrows com cor por etapa

<mad-db-steps variant="arrows" model="EtapaNegociacao" database="minierp"
    display="nome" color-field="cor" order-by="ordem asc"
    :filters="[['kanban', '=', 'T']]"
    :value="$etapaNegociacaoId" />

Filtros

{{-- Apenas etapas ativas --}}
<mad-db-steps model="EtapaPedido"
    display="nome" order-by="ordem"
    :filters="[['ativo', '=', '1']]"
    :value="$pedido->etapa_id" />

{{-- Multiplos filtros --}}
<mad-db-steps model="EtapaNegociacao"
    display="nome" order-by="ordem"
    :filters="[
        ['ativo', '=', '1'],
        ['tipo', '=', 'venda'],
    ]"
    :value="$negociacao->etapa_id" />

Clicavel — avancar de etapa pelo proprio steps

<mad-db-steps variant="arrows" model="EtapaNegociacao"
    display="nome" color-field="cor" order-by="ordem"
    :value="$negociacao->etapa_id"
    clickable mad:click="onMudarEtapa" />

public function onMudarEtapa(string $etapaId): MadResponse
{
    $neg = Negociacao::findOrFail($this->registroId);
    $neg->etapa_id = $etapaId;
    $neg->save();

    return MadToast::success('Etapa atualizada');
}

A key recebida pelo metodo PHP e o ID do registro (campo key do model).

Variantes

Mesmas do <mad-steps>. Trocar via variant:

<mad-db-steps variant="arrows"   model="EtapaPedido" :value="$id" />
<mad-db-steps variant="dots"     model="EtapaPedido" :value="$id" />
<mad-db-steps variant="numbers"  model="EtapaPedido" :value="$id" />
<mad-db-steps variant="progress" model="EtapaPedido" :value="$id" />

NUNCA fazer

{{-- ERRADO: carregar etapas no controller e montar <mad-steps> com @foreach --}}
@php
    $etapas = EtapaNegociacao::where('ativo', '=', '1')->orderBy('ordem')->get();
@endphp
<mad-steps variant="arrows" :current="$idx">
    @foreach($etapas as $i => $e)
        <mad-step :label="$e->nome" />
    @endforeach
</mad-steps>

{{-- CERTO: deixar o db-steps cuidar da query --}}
<mad-db-steps variant="arrows" model="EtapaNegociacao"
    display="nome" order-by="ordem"
    :filters="[['ativo','=','1']]"
    :value="$negociacao->etapa_id" />

{{-- ERRADO: passar `current` (indice) em vez de `value` (ID) --}}
<mad-db-steps model="EtapaPedido" :current="2" />

{{-- CERTO: db-steps usa value (ID do registro) --}}
<mad-db-steps model="EtapaPedido" :value="$pedido->etapa_id" />

{{-- ERRADO: usar db-steps para fluxo estatico (wizard de form) --}}
<mad-db-steps model="EtapaCadastro" :value="$step" />

{{-- CERTO: para fluxo fixo, usar mad-steps com filhos --}}
<mad-steps variant="dots" :current="$step">
    <mad-step label="Dados" />
    <mad-step label="Pagamento" />
    <mad-step label="Confirmacao" />
</mad-steps>