Relatório analítico com saldo acumulado, sem sair do editor
O tipo de página Relatório monta o relatório contábil clássico: rubricas em bandas, linha descritiva sob cada lançamento, sub-totais com rótulo próprio, coluna de saldo que acumula, e cabeçalho do PDF com o período e os filtros escolhidos. Sete passos, tudo pela interface.
O que você vai obter
Exemplo do relatório publicado, com dados fictícios. Cada parte destacada corresponde a uma opção do editor.
| Data | Documento | Favorecido | Crédito | Débito | Saldo |
|---|---|---|---|---|---|
| 1.01 · Consultoria técnica Valor aprovado: 6.000,00 | |||||
| 02/03/2026 | TED 0001 | Concedente Exemplo | 6.000,00 | 6.000,00 | |
| Repasse da parcela 1 conf. TED 0001 | |||||
| 10/03/2026 | NF 00101 | Fornecedor Exemplo A | 1.500,00 | 4.500,00 | |
| Consultoria técnica conf. NF 00101 | |||||
| 24/03/2026 | NF 00108 | Fornecedor Exemplo A | 1.500,00 | 3.000,00 | |
| Consultoria técnica conf. NF 00108 | |||||
| Sub-Totais da Rubrica | 6.000,00 | 3.000,00 | 3.000,00 | ||
| 1.02 · Material de escritório Valor aprovado: 2.000,00 | |||||
| 05/03/2026 | TED 0002 | Concedente Exemplo | 2.000,00 | 2.000,00 | |
| Repasse da parcela 1 conf. TED 0002 | |||||
| 18/03/2026 | NF 00342 | Fornecedor Exemplo B | 640,00 | 1.360,00 | |
| Material de escritório conf. NF 00342 | |||||
| Sub-Totais da Rubrica | 2.000,00 | 640,00 | 1.360,00 | ||
group-by + group-mask)
Linha descritiva (row-detail)
Sub-total com rótulo (group-total-label)
Saldo acumulado (running)
Crie a página pelo assistente
Barra lateral → Nova página → tipo Relatório
Escolha a tabela de lançamentos e o assistente lê as colunas. Os campos novos ficam abaixo dos agrupamentos: terceiro nível de quebra, função de cada total (soma, média, contagem, mínimo, máximo), Saldo acumulado com as colunas de crédito e débito, e Linha descritiva com uma máscara de campos.
Agrupar pelo valor de uma tabela relacionada. Quando o nível de agrupamento aponta uma coluna de ligação — a rubrica do lançamento, por exemplo — o assistente abre um segundo campo, Coluna de rubrica. Escolha ali o código ou o nome, e a quebra passa a usar esse valor no lugar do número interno; o mesmo campo existe depois no painel da grade, em Agrupamento. Para agrupar por uma tabela filha (os itens de um lançamento, por exemplo), crie o relatório a partir dela.
Agrupar por dia, mês ou ano. Quando o nível de agrupamento é uma coluna de data, o assistente abre o campo Granularidade da data, com Dia já escolhido. É o que faz vendas do mesmo dia em horários diferentes ficarem no mesmo grupo — sem isso, uma coluna que guarda data e hora quebra o relatório a cada segundo, e cada venda vira um grupo com o seu próprio sub-total. Escolha Mês ou Ano para relatórios mensais e anuais. A mesma escolha existe depois no painel da grade, em Agrupamento.
{descricao} conf. {documento}.
Veja o que foi gerado
Aba de código da página → Blade
A página é um <mad-grid> agrupado com uma coluna sintética saldo_acumulado. Tudo que o assistente fez é um atributo que você pode editar depois no painel ou direto no código.
<mad-grid self per-page="0" sticky exportable
group-by="rubrica_id" group-mask="{rubrica->codigo} · {rubrica->nome} Valor aprovado: {rubrica->valor_aprovado|money}"
group-total group-band="cells" group-total-label="Sub-Totais da Rubrica"
row-detail="{descricao} conf. {documento}"
export-title="Analítico Orçamentário" export-subtitle="{PERIOD}">
<mad-columns>
<mad-col field="data" label="Data" date />
<mad-col field="favorecido" label="Favorecido" />
<mad-col field="credito" label="Crédito" money right total="sum" />
<mad-col field="debito" label="Débito" money right total="sum" />
<mad-col field="saldo_acumulado" label="Saldo" money right running="{credito} - {debito}" running-reset="group" />
</mad-columns>
</mad-grid>
Ajuste a banda do grupo e o rótulo do sub-total
Canvas → selecione a grade → painel Propriedades → Agrupamento e Relatório
Banda do grupo em Alinhada às colunas põe os totais da rubrica embaixo das colunas certas, em vez de uma faixa corrida. Rótulo do sub-total troca o "Total" padrão pelo texto do seu relatório. No grupo Relatório ficam a linha descritiva e o título e subtítulo da exportação. Em cada nível de Agrupamento, uma coluna de data mostra também a Granularidade: dia, mês, ano ou o valor exato.
Agrupamento, subtotais e os dois mecanismos de filtro estão explicados em detalhe em Listagem e Filtrar.
Configure a coluna de saldo
Canvas → selecione a coluna Saldo → painel → Cálculo
Saldo acumulado recebe a expressão que vira o delta de cada linha; o construtor lista as colunas irmãs da grade. Zerar o acumulado decide se o saldo recomeça em cada rubrica ou atravessa o relatório inteiro. Saldo inicial aceita um número ou uma expressão. O Total da coluna de saldo mostra o último valor, nunca a soma dos saldos.
{credito} - {debito}, zerar a cada quebra de grupo.per-page="0", que o assistente já define) e uma Ordenação padrão. Com paginação ligada o saldo acumula só dentro da página. O campo saldo_acumulado não existe na tabela: o aviso de coluna desconhecida no painel é esperado nessa coluna.Confira no canvas
Área central do editor
O preview usa dados de exemplo com a estrutura final: banda da rubrica, linha descritiva em itálico sob cada registro, sub-total com o rótulo escolhido e a coluna de saldo crescendo linha a linha, marcada com Σ↓ no cabeçalho.
Monte o cabeçalho e o rodapé do PDF
Barra de ações da grade no canvas → PDF (ou painel da página → Exportação PDF)
O editor de bandas é um canvas em milímetros. Arraste texto fixo (nome da empresa, CNPJ), a logomarca do projeto e os campos dinâmicos. Três campos são novos: {PERIOD} imprime o intervalo filtrado, {FILTERS} lista os filtros escolhidos com seus rótulos, {SUBTITLE} traz o subtítulo da exportação. O modelo Relatório financeiro já vem com essa composição.
Quem emite também entra na banda: {UNIT_NAME} imprime a unidade (filial) ativa da pessoa logada, {USER_NAME} o nome dela e {TENANT_NAME} a empresa. Em app sem multi-unidade ou sem tenancy o campo sai em branco.
Como imprimir o CNPJ (ou outro dado) no cabeçalho
Qualquer dado do app pode virar um campo do PDF. Arraste um elemento de Texto e digite o token entre chaves — {CNPJ}, {ENDERECO}. O editor mostra o token como está (ele não sabe o valor); quem preenche é a tela, no PHP, com o método exportPdfPlaceholders():
protected function exportPdfPlaceholders(): array
{
return ['CNPJ' => '12.345.678/0001-90', 'ENDERECO' => 'Rua X, 100'];
}Valor fixo (CNPJ, endereço) não precisa de código: Configurações do projeto → Exportação de PDF → Campos próprios — vira chip no editor. Valor calculado para todas as telas: botão Criar classe de campos na mesma seção. O valor da tela vence os dois. Guia completo: Cabeçalho e rodapé do PDF. Precisa do Mad Framework 5.80 ou mais novo no app.
Publique e exporte
App publicado → filtre o período → Exportar → PDF
No app, a pessoa escolhe período e projeto e clica em Exportar. O PDF sai em A4 paisagem com o cabeçalho de colunas repetido em toda página, "Página 1 de N", período e filtros no cabeçalho, sub-totais por rubrica e o total geral. Excel e CSV recebem as mesmas colunas e sub-totais; a linha descritiva fica só na tela e no PDF, para não quebrar tabelas dinâmicas.
{FILTERS} depois de republicados, porque as telas são recompiladas na publicação.Referência: o que cada propriedade faz
Para quem também mexe no Blade.
| Propriedade | Valores | Efeito |
|---|---|---|
mad-colrunning | vazio · {credito} - {debito} | Coluna vira saldo acumulado. Sem valor, acumula o próprio campo; com expressão, acumula o resultado dela a cada linha. |
mad-colrunning-reset | none · group · group:1 | Zera o saldo a cada quebra do nível indicado. Padrão: nunca zera. |
mad-colrunning-start | número ou expressão | Saldo inicial de cada escopo (saldo anterior, por exemplo). |
mad-coltotal | sum · avg · count · min · max · last | last é novo: último valor do grupo. Coluna de saldo com sum também devolve o último valor. |
mad-coltotal-mask | texto com {value} | Formata o total da coluna; sub-total e total geral usam a mesma formatação. |
mad-gridrow-detail | máscara {descricao} conf. {documento} | Segunda linha, descritiva, abaixo de cada registro. Tela e PDF; Excel e CSV ignoram. |
mad-gridgroup-by | rubrica_id · rubrica->codigo · data|day · vários níveis separados por vírgula | Coluna que quebra o relatório. Com a seta, agrupa pelo valor da tabela relacionada (um nível de relação). Tabela filha, de muitos registros por lançamento, não agrupa — monte o relatório a partir dela. |
mad-gridgroup-by · granularidade | data|day · data|month · data|year · combina com a seta: venda->data|day | Agrupa a coluna de data por dia, mês ou ano. Sem o sufixo, uma coluna com data e hora quebra pelo valor exato — ou seja, por segundo. |
mad-gridgroup-band | inline · cells | Em cells a banda e o sub-total do grupo alinham cada valor sob a sua coluna. |
mad-gridgroup-total-label | texto, aceita {group} | Rótulo da linha de sub-total. |
mad-gridexport-title · export-subtitle · export-filename | texto, aceita {PERIOD} | Alimentam {TITLE}, {SUBTITLE} e o nome do arquivo. Vencem o título definido no PHP. |
máscaras{campo|money} | formatadores do framework | Formatação dentro de group-mask, row-detail e group-total-label. |
bandas PDF{PERIOD} · {FILTERS} · {SUBTITLE} | tokens do cabeçalho e rodapé | Período filtrado, filtros ativos com rótulo, subtítulo da exportação. |
bandas PDF{UNIT_NAME} · {USER_NAME} · {TENANT_NAME} | tokens do cabeçalho e rodapé | Unidade ativa, nome de quem exportou e empresa. Em branco quando o app não tem multi-unidade ou tenancy. |
bandas PDF{SEU_TOKEN} | texto livre + exportPdfPlaceholders() | Campo próprio do app, preenchido no PHP da tela (ou na classe global App\Support\PdfExportPlaceholders). |
Problemas comuns
O saldo muda de valor a cada vez que abro o relatório
Falta a Ordenação padrão. Sem ela o banco devolve as linhas em qualquer ordem e o acumulado acompanha. Ordene pela data do lançamento (e pela rubrica, se houver quebra).
O saldo não zera na troca de rubrica
Zerar o acumulado está em "Nunca". Troque para "A cada quebra de grupo" no painel da coluna Saldo.
O período não aparece no cabeçalho do PDF
O chip {PERIOD} só imprime quando a tela tem um filtro de período preenchido. Confira o campo de período do relatório e se a pessoa escolheu datas antes de exportar.
{FILTERS} sai em branco no app
O app foi publicado antes desta versão. Republique o projeto: as telas são recompiladas e o cabeçalho passa a receber os filtros.
{UNIT_NAME} ou {TENANT_NAME} sai em branco
O app não tem multi-unidade/tenancy, a pessoa logada não está vinculada a uma unidade, ou o app roda um Mad Framework anterior ao 5.79. Atualize o framework do app e confira o vínculo da pessoa com a unidade.
O meu {CNPJ} apareceu literal no PDF
Ninguém definiu o valor: cadastre em Configurações do projeto → Exportação de PDF → Campos próprios (valor fixo), ou devolva-o na classe de campos / no método exportPdfPlaceholders() da tela, e republique.
A linha descritiva não veio no Excel
É proposital. A segunda linha quebraria tabelas dinâmicas e filtros do Excel; ela existe na tela e no PDF.