Filtro avançado: o usuário monta o próprio filtro
Com o Filtro avançado, quem usa o sistema monta a busca que precisa, sem pedir uma tela nova: escolhe a coluna, o operador e o valor, combina quantas condições quiser e salva o filtro para usar de novo. Você decide no MadBuilder quais colunas ficam disponíveis.
O que você vai obter
Listagem de clientes no app gerado, com três condições montadas pelo usuário. Exemplo com dados fictícios.
O caminho completo tem quatro passos:
Ligar na listagem
Editor da página de listagem → clique na grade → painel de propriedades → seção Filtro avançado
Abra a listagem no editor e clique na grade. No painel de propriedades aparece a seção Filtro avançado, logo abaixo de Regras de carregamento e Filtros, desligada.
O link Como funciona abre este guia numa aba do editor.
Ligue Permitir que o usuário final filtre. As colunas da grade entram na lista de uma vez, cada uma com o tipo certo (texto, número, data, Sim/Não, tabela relacionada), e o canvas passa a mostrar o botão Filtros na barra da grade, com o número de colunas liberadas.
Escolher as colunas
Seção Filtro avançado → Colunas liberadas
Só as colunas desta lista aparecem para o usuário. Você pode:
- Usar colunas da grade: acrescenta as colunas da listagem que ainda não estão no filtro. Útil depois de adicionar uma coluna nova à grade.
- Adicionar coluna: libera qualquer coluna da tabela, mesmo que ela não apareça na grade, inclusive de tabelas relacionadas, em até três níveis. No exemplo, Estado vem de
cidade → estado → nome. O rótulo já nasce com o nome da tabela (Estado, não Nome); você pode trocá-lo no painel da coluna. - Reordenar com as setas (a ordem é a da lista de colunas que o usuário vê) e remover com a lixeira.
Configurar cada coluna
Clique numa coluna da lista → abre o painel da coluna (← volta para o Filtro avançado)
O painel da coluna tem o rótulo que o usuário vê, o tipo e os operadores permitidos. O tipo decide o campo de valor que aparece no app e quais operadores fazem sentido:
| Tipo | Campo de valor no app | Quando usar |
|---|---|---|
| Texto | Caixa de texto | Nome, e-mail, descrição, código. |
| Número | Caixa numérica (ou duas, no entre) | Quantidade, valor, limite. |
| Data / Data e hora | Calendário, intervalo ou período pronto | Cadastro, vencimento, emissão. |
| Sim/Não | Botões Sim e Não | Ativo, pago, bloqueado. Informe o que o banco grava (por exemplo S/N). |
| Opções fixas | Lista com as opções que você digitar | Situação com poucos valores fixos. |
| Combo de tabela | Lista com os registros de outra tabela, com busca | Categoria, tipo, responsável. |
| Busca no banco | Busca enquanto digita | Tabelas grandes (clientes, produtos). |
Em Operadores permitidos, desmarque o que não faz sentido para aquela coluna. Com todos marcados, o usuário vê todos os operadores do tipo. Pelo menos um precisa ficar marcado.
Opções do filtro
Seção Filtro avançado → Opções
Abaixo das colunas liberadas fica o bloco Opções: filtros salvos, quem pode compartilhar, a lógica inicial, o máximo de condições e o texto do botão. A tabela a seguir explica cada uma.
| Opção | O que faz | Padrão |
|---|---|---|
| Filtros salvos | Pessoais e compartilhados: cada usuário salva os seus e pode compartilhar. Só pessoais: sem compartilhamento. Desligado: sem o menu Meus filtros. | Pessoais e compartilhados |
| Quem pode compartilhar | Administradores ou Todos os usuários. Quem não pode compartilhar salva o filtro como pessoal. | Administradores |
| Lógica inicial | Como as condições começam combinadas: Todas ou Qualquer uma. O usuário pode trocar ao filtrar. | Todas |
| Máximo de condições | Quantas condições cabem num filtro, de 1 a 20. | 15 |
| Texto do botão | O texto do botão na listagem. | Filtros |
O código gerado
Aba Blade da página — para quem prefere editar o código ou pedir ao agente de IA
O painel grava um bloco <mad-custom-filters> dentro da <mad-grid>, com uma tag <mad-custom-filter> por coluna liberada. Você pode editar direto no código: o painel lê o que estiver ali.
<mad-grid self per-page="15">
<mad-columns> … </mad-columns>
<mad-custom-filters save="shared" match="all">
<mad-custom-filter field="{nome}" label="Nome" />
<mad-custom-filter field="{cidade->nome}" label="Cidade" />
<mad-custom-filter field="{cidade->estado->nome}" label="Estado" />
<mad-custom-filter field="{categoria_cliente_id}" label="Categoria" type="dbcombo"
model="CategoriaCliente" display="{nome}" />
<mad-custom-filter field="{data_cadastro}" label="Cadastro" type="date" />
<mad-custom-filter field="{limite_credito}" label="Limite de crédito" type="number" />
<mad-custom-filter field="{ativo}" label="Ativo" type="bool" true="S" false="N" />
<mad-custom-filter field="{situacao}" label="Situação" type="select"
opts="A:Ativo|B:Bloqueado" ops="=,in" />
</mad-custom-filters>
</mad-grid>| Atributo | Onde | O que faz |
|---|---|---|
save | container | shared (padrão), user ou off — os filtros salvos. |
share | container | admin (padrão) ou everyone — quem pode compartilhar. |
match | container | all (padrão) ou any — a lógica inicial. |
max | container | Máximo de condições, até 20. Padrão 15. |
label | container | Texto do botão. Padrão: Filtros. |
field | coluna | A coluna filtrada. Aceita relação: {cidade->estado->nome}, até três níveis. |
label | coluna | O nome da coluna para o usuário. |
type | coluna | text (padrão), number, date, datetime, bool, select, dbcombo, dbsearch. |
ops | coluna | Operadores permitidos, separados por vírgula. Sem o atributo: todos do tipo. |
model, display, order-by | coluna | Fonte das opções de dbcombo e dbsearch. |
opts / :opts | coluna | Opções de select: A:Ativo|B:Bloqueado ou um array PHP. |
true, false | coluna | O que o banco grava em Sim e Não (padrão 1 e 0). |
Publicar e testar
Rail → Teste online → Testar agora
Com o Teste Online já ligado, salvar a página atualiza o app sozinho: o indicador Test Online · há instantes, no topo do editor, confirma a sincronização. Na primeira vez, clique em Testar agora; para os clientes, republique o projeto na hospedagem. O botão Filtros aparece na listagem do app.
No sistema: montar o filtro
App → listagem → botão Filtros (ao lado de exportar e colunas)
O painel abre vazio, com sugestões prontas feitas a partir das colunas liberadas. Clique numa sugestão ou em Adicionar condição.
Cada condição tem três partes: a coluna, o operador e o valor. A lista de colunas tem busca e agrupa as colunas de tabelas relacionadas.
Operadores e valores
Os operadores mudam conforme o tipo da coluna, para o usuário nunca ver uma opção que não faz sentido. O desenvolvedor pode esconder alguns (03).
| Tipo da coluna | Operadores |
|---|---|
| Texto | contém · não contém · é igual a · é diferente de · começa com · termina com · é um dos · está vazio · não está vazio |
| Número | é igual a · é diferente de · maior que · maior ou igual a · menor que · menor ou igual a · entre · é um dos · está vazio · não está vazio |
| Data | é em · antes de · depois de · entre · período · está vazio · não está vazio |
| Sim/Não | é (Sim ou Não) |
| Opções fixas | é · não é · é um dos · não é nenhum dos |
| Tabela relacionada | é · não é · é um dos · não é nenhum dos · está vazio · não está vazio |
Períodos prontos
O operador período oferece: Hoje, Ontem, Esta semana, Semana passada, Este mês, Mês passado, Este ano, Ano passado, Últimos 7, 30 e 90 dias, Próximos 7 e 30 dias. As datas exatas aparecem embaixo do campo.
"É um dos": vários valores de uma vez
Digite um valor e tecle Enter para virar etiqueta, ou cole uma lista separada por vírgula, ponto e vírgula ou quebra de linha, como 3, 7, 12, 21: cada valor vira uma etiqueta. Backspace no campo vazio remove a última.
Aplicar e ver o resultado
Enquanto você monta o filtro, o botão Aplicar mostra quantos registros ele vai trazer. Clique em Aplicar (ou ⌘ Enter / Ctrl+Enter): o painel fecha, a listagem é filtrada e cada condição vira uma etiqueta acima da grade.
Se uma condição ficar sem valor, o painel não aplica: a linha fica em vermelho com Informe um valor e o cursor vai direto para ela.
Todas ou qualquer uma
No topo do painel, escolha se o registro precisa atender a todas as condições ou a qualquer uma delas. A palavra no começo de cada linha mostra a lógica em uso (e ou ou) e também troca a lógica quando clicada.
Filtros salvos
Painel Filtros → Meus filtros (canto inferior esquerdo)
Um filtro que o usuário usa sempre pode ser salvo com um nome. O menu Meus filtros separa os filtros da pessoa dos compartilhados por outros usuários.
Em Salvar filtro atual…, dê um nome e escolha:
- Compartilhar com todos: todos que usam esta tela passam a ver o filtro. Aparece para quem pode compartilhar (04).
- Abrir a tela com este filtro: a listagem já abre filtrada para você.
Com um filtro salvo em uso, o botão da listagem mostra o nome dele. Se o usuário mudar alguma condição, o painel marca o filtro como alterado; basta salvar de novo com o mesmo nome.
Celular e tema escuro
No celular, o painel sobe da parte de baixo da tela e cada condição vira um cartão, com o botão Aplicar ocupando a largura toda.
O filtro segue a cor do tema do projeto e o modo escuro do app.
O que o usuário pode filtrar
- Só as colunas liberadas. O usuário não consegue filtrar por uma coluna que você não liberou, nem forjando a requisição: o servidor confere coluna, operador e valor em toda consulta e ignora o que não estiver na lista.
- Só os registros que a tela já mostra. O filtro avançado restringe a listagem; ele não passa por cima das regras de carregamento, das permissões nem da separação por unidade ou empresa.
- Filtros salvos acompanham a tela. Se você remover uma coluna do filtro avançado, os filtros salvos que a usavam continuam funcionando sem aquela condição, e o usuário vê um aviso.
Qual filtro usar
A listagem tem três formas de filtrar, e elas podem ser usadas juntas:
| Recurso | Quem define as condições | Melhor para |
|---|---|---|
| Filtro avançado | O usuário, com as colunas que você liberou | Buscas variadas, que cada pessoa monta do seu jeito e pode salvar. |
| Filtros da listagem (Filtrar) | Você: campos fixos numa barra, gaveta ou lateral | Os dois ou três filtros que todo mundo usa, sempre à vista. |
| Filtro da coluna (Listagem) | O usuário, no cabeçalho de cada coluna | Um ajuste rápido numa coluna que está na grade. |
Problemas comuns
| O que aparece | Por quê | O que fazer |
|---|---|---|
| O botão Filtros não aparece no app | O app ainda não recebeu a página nova, ou o framework do app é anterior ao 5.94.0. | Clique em Testar agora ou republique o projeto. |
| O botão aparece, mas a lista de colunas está vazia | Nenhuma coluna foi liberada. | Em Filtro avançado, clique em Usar colunas da grade ou Adicionar coluna. |
| Uma coluna mostra o aviso "Coluna não encontrada no modelo" | A coluna foi renomeada ou removida da tabela. | Escolha a coluna de novo no painel da coluna ou remova-a da lista. |
| Aviso "Condições ignoradas" ao abrir um filtro salvo | O filtro usava uma coluna que não está mais liberada. | Ajuste as condições e salve de novo com o mesmo nome. |
| O usuário não vê a opção de compartilhar | O compartilhamento está limitado aos administradores. | Em Opções, mude Quem pode compartilhar para Todos os usuários. |
| Sim/Não não encontra nada | O banco grava valores diferentes de 1/0. | No painel da coluna, preencha Valor de Sim e Valor de Não (por exemplo S e N). |