DB Combo

Esta é a única parte obrigatória. Sem ela o campo aparece vazio.

1. No painel, abra a seção Fonte de dados.
2. Database: o banco. Deixe como está, a não ser que a tabela esteja em outro.
3. Tabela (Model): a tabela de onde saem as opções — no exemplo dos prints, estado.
4. Chave: a coluna que será gravada. Quase sempre id.
5. Display: a coluna que a pessoa lê na tela — aqui {nome}.
6. Ordenar por: por qual coluna a lista aparece, e se é crescente (ASC) ou decrescente (DESC).

O painel, campo a campo

Escolha um item da lista abaixo: ele acende no print.

Passe o mouse na lista — ou use ↑ ↓ depois de focar um item.

O que o painel escreve no código

Por padrão o combo lista tudo que existe na tabela. As Regras de carregamento cortam essa lista — só os ativos, só os do tipo escolhido, só os do ano corrente.

1. No painel, clique na aba Regras de carregamento (fica acima de Propriedades).
2. Clique em Configurar filtros. Abre a janela de regras.
3. Clique em + Regra.
4. Coluna: escolha a coluna da tabela que vai ser comparada — ex.: pais_id.
5. Operador: como comparar — igual, diferente, maior, contém, está na lista…
6. Valor: com o que comparar. O tipo mais comum é Valor literal (você digita, ex.: 1).
7. Confira o Preview do PHP gerado à direita e clique em Aplicar.

A janela de regras, parte por parte

Clique no print para ampliar.

Exemplo montado: pais_id = 1.

Os seis tipos de valor

O campo Valor tem um seletor de tipo. Ele decide de onde sai o valor da comparação:

Várias regras juntas

• AND no Grupo raiz: todas as regras precisam ser verdadeiras (ativo e do meu estado).
• OR: basta uma ser verdadeira (matriz ou filial).
• + Grupo cria um bloco com regra própria dentro do bloco maior — é como usar parênteses numa conta.
• Subconsulta, na aba ao lado de Comparação direta, filtra por algo que está em outra tabela (ex.: só produtos que já foram vendidos).

É o caso clássico: escolho o país e o combo de estado passa a mostrar só os estados daquele país. Quem faz isso é a seção Combo dependente, no campo filho — no exemplo, no campo estado.

1. Clique no combo filho (o que precisa ser filtrado). Não é no pai.
2. Abra a seção Combo dependente.
3. Depende de: escolha o campo pai, aquele que a pessoa preenche antes.
4. Coluna FK: escolha a coluna do filho que aponta para o pai — em estado, é pais_id.

Três níveis

País → estado → cidade funciona do mesmo jeito: configure a cascata em cada filho apontando para o seu pai imediato. Ao trocar o país, o estado recarrega e a cidade limpa junto, em efeito dominó.

Editando um registro que já existe

Quando a tela abre para editar, o pai já vem preenchido e o filho já vem com a lista certa — sem piscar nem exigir clique. Se o campo pai não for uma coluna da tabela (é o caso do país numa tela de cidade, que só existe via relação), quem monta a tela precisa preencher esse valor ao editar; sem isso, a cascata abre vazia no registro salvo.

A pessoa digita "Uruguai", não existe na tabela, e o combo fica vazio. A seção Sem resultados transforma esse beco sem saída em um botão de cadastro dentro do próprio dropdown. São dois modos, que podem ser ligados juntos ou separados.

Modo 1 — abrir o formulário completo

1. Na seção Sem resultados, clique na engrenagem do card Abrir formulário completo.
2. Formulário: escolha a tela de cadastro que deve abrir (ex.: EstadoForm).
3. Método: já vem show, que é o método que abre a tela. Só mude se a sua tela usa outro.
4. Em Aparência do botão, ajuste o texto (Label), o Ícone e a Classe CSS, se quiser.
5. Clique em Salvar. O card passa a mostrar ATIVO.

Clique no print para ampliar.

Modo 2 — cadastro rápido, sem sair da tela

1. Clique na engrenagem do card Cadastro rápido inline.
2. Formulário de cadastro: escolha a tela dona da tabela (ex.: EstadoForm). O método de salvamento é gerado automaticamente nela — o campo Método já mostra o nome, tipo onQuickSaveEstado.
3. Ajuste o botão em Aparência do botão, se quiser.
4. Em Campos, decida o formato do cadastro: sem nenhum campo, o sistema salva só o texto digitado; clicando em Adicionar primeiro campo você monta um mini-formulário.
5. Clique em Salvar.

Clique no print para ampliar.