Criar um relatório

Um relatório é um documento impresso a partir dos dados da app: uma listagem, uma factura, um mapa de fecho do mês. Sai em PDF — paginado, com cabeçalhos que se repetem e totais no fim — ou em Excel, e pode ser gerado à mão, por um botão de um ecrã, por um script, por um workflow, ou por um agendamento que o envia por email.

O modelo é o de bandas: um relatório não é um ecrã que cresce para baixo, é uma sequência de faixas que o motor repete conforme a regra de cada uma — uma vez, por página, por linha, por grupo. É isso que torna a paginação possível.

A unidade é o milímetro, em todo o lado. É a unidade do papel e sobrevive à mudança de A4 para Letter.

Nesta página desenhamos o relatório Oportunidades por conta da app Gestão de Clientes: o pipeline comercial agrupado por conta, com os contactos de cada uma, o total por conta e um gráfico no fim.

#Onde vivem os relatórios

Os relatórios estão no minitab Dados da árvore da app, por baixo das fontes de dados. Clicar no nome abre o desenho num separador.

Uma app sem relatórios mostra "Sem relatórios — cria um para o desenhares.".

#Criar um relatório

1. Passa o rato pela linha do grupo Relatórios e clica em Novo relatório.
2. Escreve o Nome — por exemplo Facturas do mês.
3. Clica em Criar.

"Cria um relatório na raiz. Podes movê-lo para uma pasta depois." O relatório nasce em A4 retrato, com as cinco bandas fixas e sem dados ligados, e o desenho abre logo.

#O desenho

O separador tem três colunas e uma barra em cima:

Zona	O que é
Barra do topo	O nome, o identificador do relatório (rpt_…, o que o código usa para lhe chamar), o estado da gravação, desfazer/refazer, as medidas do papel e os botões Excel e Pré-visualizar.
Coluna da esquerda	A paleta Elementos, os Dados, os Agrupamentos, os Parâmetros e os Agendamentos.
Centro	A superfície de desenho: uma régua em milímetros e as bandas, umas por cima das outras pela ordem em que saem no papel.
Direita	As propriedades — do relatório, da banda seleccionada ou do elemento seleccionado.

Como no resto da plataforma, não há botão de gravar: o desenho grava-se sozinho.

#As bandas

As bandas são um conjunto fixo — não se acrescentam faixas à vontade, porque cada uma tem uma regra de repetição própria que o motor conhece pelo nome.

Banda	Quando sai
Cabeçalho do relatório	"Sai uma única vez, no início da primeira página." Logótipo, título, data de emissão.
Cabeçalho de página	"Repete-se no topo de todas as páginas — logótipo, títulos de coluna."
Detalhe	"Sai uma vez por cada linha de dados. É esta banda que enche o relatório."
Rodapé de página	"Repete-se no fundo de todas as páginas — número de página, data."
Rodapé do relatório	"Sai uma única vez, no fim — totais gerais." Nasce desligado.

A estas juntam-se, quando há agrupamentos, um cabeçalho e um rodapé por nível — ver Gráficos e subrelatórios.

Clicar no título de uma banda selecciona-a; o painel da direita passa a mostrar as propriedades dela.

Propriedade	O que faz
Altura (mm)	A altura da faixa. Também se arrasta a linha divisória, na superfície de desenho.
Activa	"Desligada, a banda não sai no relatório nem ocupa espaço."
Regras da banda	Suprimir a banda conforme os dados.

Sobre as regras: "suprimir a banda conforme os dados. Suprimida, não sai nem ocupa espaço — é o que substitui ter várias bandas de detalhe". Em vez de três faixas de detalhe com condições diferentes, uma faixa e regras que a escondem quando não é caso disso.

#O papel

Com nada seleccionado, o painel da direita mostra as propriedades do relatório e da página:

Campo	Opções
Nome / Descrição	Identificação, para quem constrói.
Formato	A4, A3, A5, Letter, Legal ou Personalizado (largura e altura em mm).
Orientação	Retrato ou Paisagem.
Margens (mm)	Superior, Inferior, Esquerda, Direita.

"O espaço entre o papel e o conteúdo. A largura útil que sobra é a da superfície de desenho" — mudar as margens muda a largura em que desenhas, e a régua acompanha.

A secção Vista, no fim do painel, tem o Zoom da superfície de desenho. Não afecta o documento; é só a lupa de quem desenha.

#Os dados

Um relatório sem dados ligados não tem campos para arrastar. Abre Conjuntos de dados no + da secção Dados:

Cada conjunto tem:

Campo	Notas
Nome do conjunto	Como os elementos lhe chamam (oportunidades, contactos).
Papel	principal, ligado ou avulso — ver a tabela abaixo.
API de tabela	A API da app de onde vêm as linhas.
Filtros (where)	A mesma gramática de filtros do resto da plataforma. Pode comparar com parâmetros do relatório.
Carregamento / Por página	Como as linhas são lidas.

Os três papéis:

Papel	O que significa
principal	"A banda de detalhe percorre-o, uma linha impressa por cada linha dele." Só há um.
ligado	"Pertence a uma linha de outro conjunto pelo campo que indicares — a factura e as linhas dela."
avulso	"Nem percorrido nem ligado, serve para o cabeçalho ou para um total geral."

Um conjunto ligado pede mais três campos: o Conjunto pai, o Campo no pai ("o campo que identifica a linha do pai — normalmente a chave") e o Campo neste conjunto ("o campo que aponta de volta para o pai").

Na coluna da esquerda, cada conjunto aparece com o número de campos e expande-se com a seta. Arrastar um campo para uma banda cria um elemento Campo já ligado — é a forma mais rápida de encher a banda de detalhe.

#Os parâmetros

Parâmetros são "valores que o relatório recebe de quem o manda correr" — o mês, a fase, o cliente. Usam-se nos filtros dos conjuntos de dados.

Campo	Notas
Nome	Como o filtro e o código lhe chamam.
Etiqueta	O que se lê quando o valor é pedido.
Tipo	Texto, Número, Data ou Sim/Não.
Obrigatório	Sem valor, o relatório recusa-se a correr.
Valor por omissão	Usado quando quem chama não dá nenhum.

#Os elementos

A paleta Elementos tem tudo o que se põe numa banda. Arrasta-se para a banda; larga-se onde deve ficar.

Elemento	Para que serve
Texto	Texto fixo — títulos, etiquetas, rodapés.
Campo	O valor de um campo do conjunto. É o que sai de arrastar um campo.
Agregado	Uma conta sobre um conjunto: Soma, Média, Contagem, Mínimo, Máximo.
Campo de sistema	Número da página, Total de páginas, Página X de Y, Data de emissão, Nome do relatório.
Linha	Separadores e molduras.
Rectângulo	Fundos e caixas, com preenchimento, contorno e cantos.
Imagem	Um ficheiro da app, um endereço, ou o conteúdo de um campo.
Gráfico	Nove tipos, com os mesmos dados dos ecrãs.
Subrelatório	Outro relatório desenhado dentro deste.
Código de barras	Code 128, EAN-13 ou QR.

Os últimos três têm página própria: Gráficos e subrelatórios.

#As propriedades de um elemento

Clica num elemento na superfície de desenho:

Secção	O que tem
Posição e tamanho	X (mm), Y (mm), Largura (mm), Altura (mm). O y conta a partir do topo da banda.
Aspecto	Tipo de letra, Corpo (pt), negrito/itálico/sublinhado, alinhamento, Alinhamento vertical, cor, Preenchimento, Contorno (mm) e Cor do contorno, Quebrar linha.
Formato (campos e agregados)	Máscara de apresentação, com a mesma gramática das colunas da tabela.
Exportação	Nome da coluna no Excel. "Vazio usa o nome do campo. No papel não aparece — lá o cabeçalho é um texto que desenhas onde quiseres."
Regras de formatação	Ver abaixo.

Sobre Quebrar linha: "desligado, o texto que não cabe é cortado em vez de passar para a linha seguinte" — é o que se quer numa coluna de tabela, para uma linha comprida não empurrar a página toda.

Seleccionando vários elementos (com a caixa de selecção ou com Shift), o painel diz quantos são e move-os em conjunto, com o rato ou com as setas.

#Regras de formatação

Cada elemento pode ter regras que "mudam o aspecto conforme os dados da linha: pintar um valor em atraso, esconder uma etiqueta, pôr um total a negrito quando é negativo". São o mesmo motor e o mesmo editor das regras dos widgets.

A última regra que bater é a que manda — ordena-as da mais geral para a mais específica.

#Ver o resultado

Dois botões, no canto superior direito:

• Pré-visualizar gera o PDF com os dados reais da app e abre-o ali mesmo, paginado. É assim que se confere o desenho: nem sempre o que cabe na superfície de desenho cabe na página.
• Excel gera a folha de cálculo e descarrega-a. Aqui não há bandas nem páginas: sai uma tabela, com uma coluna por elemento da banda de detalhe, e os cabeçalhos vêm do Nome da coluna de cada um.

Se o relatório tiver parâmetros obrigatórios, são pedidos antes de gerar.

#Perguntas frequentes

A banda de detalhe sai vazia. Não há conjunto principal, ou o filtro dele não devolve linhas. Abre Conjuntos de dados e confirma que há um com o papel principal, e que os parâmetros que o filtro usa têm valor.

Um campo numa banda de cabeçalho sai vazio. É esperado fora das bandas de grupo. No Cabeçalho do relatório e no Rodapé do relatório não há "linha actual" — mostrar a primeira de todas seria inventar um valor. Num cabeçalho de grupo, o campo lê a primeira linha do grupo, que é o que se quer.

O relatório demora ou trunca. Cada conjunto tem um tecto de linhas por leitura. Filtra mais — por data, por estado — em vez de imprimir a tabela inteira. Um relatório de 4.000 páginas não é lido por ninguém.

Preciso de mais do que um agendamento sabe fazer. Escreve um script Python e chama reports.render(...) — ver Agendar e enviar.