Filtrar
Toda tela que lista dados tem dois cortes diferentes, e confundi-los é a origem da maioria dos problemas de listagem. Um é a régua que o sistema aplica sempre, sem a pessoa ver; o outro é a barra que a pessoa usa para apertar o resultado. Você configura os dois no editor, sem escrever consulta.
Quem filtra o quê
Regras de carregamento é o corte que o sistema aplica sempre, antes de a tela aparecer, e que a pessoa não vê nem desliga; Filtros é a barra na tela, que a pessoa preenche e limpa quando quiser.
| Você quer | Onde configurar |
|---|---|
| Mostrar só os registros ativos, para todo mundo, sempre | Regras de carregamento |
| Mostrar só os registros da unidade de quem está logado | Regras de carregamento |
| Deixar a pessoa escolher o período que quer ver | Filtros |
| Deixar a pessoa procurar por situação ou responsável | Filtros |
| Um campo de busca por uma coluna, no cabeçalho da tabela | Filtro da coluna |
| Deixar a pessoa montar o próprio filtro — coluna, operador e valor — e salvá-lo | Filtro avançado (guia) |
| Procurar por qualquer palavra nas colunas visíveis | Busca da listagem |
| Cortar as opções de um campo de escolha | DB Combo |
| Filtrar os números de um painel de indicadores | Painel de indicadores |
O corte do sistema: Regras de carregamento
A mesma janela aparece em dezesseis lugares do editor: na listagem, no DB Combo, no kanban, no cartão de indicador. Aprendeu uma vez, vale em todos.
- Selecione a grade e abra a seção Regras de carregamento no painel.
- Clique em Configurar filtros para abrir a janela.
- Clique em + Regra.
- Coluna: a coluna da tabela que entra na comparação — ex.: estado_id.
- Operador: igual, diferente, maior, contém, está na lista…
- Valor: o tipo mais comum é Valor literal, em que você digita o valor.
- Confira o Preview do PHP gerado e clique em Aplicar.
Clique no print para ampliar.
Exemplo montado: estado_id = 1.
O corte da pessoa: a barra de filtros
- Com a listagem aberta, clique em Configurar Filtros da Listagem na barra superior do editor.
- Estilo: escolha como a barra aparece — Toolbar (filtros na linha), Chips, Drawer (painel lateral), Modal ou Sidebar.
- Em Colunas da tabela, marque as colunas que viram filtro. Cada coluna marcada cria um filtro pronto.
- Em Filtros declarados, ajuste cada um: o rótulo, o tipo de campo e se ele começa preenchido.
- Feche a janela e salve a tela.
Clique no print para ampliar.
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 listagem | Só aparecem os registros que a regra de carregamento permite. |
| Contar o total no rodapé | O total também respeita a regra — ele não conta o que foi cortado. |
| Usar um filtro da barra | A lista aperta mais, sobre o que já estava cortado. |
| Limpar os filtros | A lista volta ao que a regra de carregamento permite — e não a tudo. |
| Trocar de página com um filtro ativo | O filtro continua valendo na página 2. |
| Entrar com outro usuário | A regra que usa a sessão do sistema mostra os dados dele, não os seus. |
Problemas comuns
A listagem abriu vazia depois que mexi nos filtros
Uma regra de carregamento está cortando tudo. Abra a janela de regras e leia o Preview do PHP gerado: ele mostra o corte exato que está valendo.
Limpo os filtros e ainda faltam registros
Isso é o esperado: limpar a barra remove o corte da pessoa, não o do sistema. O que continua faltando está sendo cortado pelas Regras de carregamento.
O filtro da barra não aparece na tela publicada
A barra existe mas nenhuma coluna foi marcada em Colunas da tabela — ou a tela não foi salva depois de fechar a janela.
Cada usuário deveria ver só os seus dados, mas todos veem tudo
A regra está com um valor fixo em vez de Sessão do sistema. Troque o tipo do valor para que ele venha de quem está logado.
Os filtros ocupam a tela toda
Passou de meia dúzia. Troque o Estilo para Drawer ou Modal: o botão fica no alto e o painel abre só quando a pessoa quer filtrar.
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 |
|---|---|---|
| Regras de carregamento | :filters · :query | sem corte |
| Filtros (barra da tela) | <mad-grid-filters> | sem barra |
| Estilo da barra | style | toolbar |
| Botão que abre a barra | trigger | automático |
| Título da barra | title | — |
| Nome (ID) | name | mad-grid-filters-toolbar |
| Filtro da coluna | <mad-col-filter> | desligado |