Configurando relatórios

Existe uma diferença importante entre a configuração de um relatório de origem Padrão e Fonte dinâmica. A diferença está nos Fields, pois realizado um relatório de origem padrão todos os campos vêm disponíveis mapeados a serem utilizados no relatório. Mas quando utilizado fonte dinâmica não aparece nenhum campo, portanto, é necessário criá-los manualmente.

As páginas que compõem um relatório, apresentam bandas independentes dos dados como: título, rodapé entre outras faixas que são impressas somente se houver um ou mais registros de dados a serem impressos (cabeçalhos de grupo e a faixa de detalhes). Estas últimas seções podem ser divididas em colunas verticais para aproveitar o espaço disponível. Uma coluna não diz respeito aos campos de registro, mas diz respeito à faixa de detalhe. Isso significa que se tiver um registro com dez campos e desejar uma visualização de tabela, dez colunas não são necessárias. No entanto, o elemento deve ser colocado corretamente para ter um efeito de tabela.

O Jaspersoft Studio permite exportar relatórios em vários formatos, incluindo PDF, XLS, HTML entre outros.

Configurando relatório de origem Padrão

Quando baixado um arquivo do Gerenciador de relatórios, todos os campos selecionados ficam disponíveis no Jaspersoft na opção Fields para serem utilizados. Para ter acesso ao documento completo sobre os Relatórios clique aqui.

Para adicionar um campo ao relatório, clique no campo e arraste-o para o centro da tela, pois quando o objeto é arrastado para dentro da faixa de detalhes, o Jaspersoft cria um elemento de campo de texto.

Para excluir um campo do relatório, clique com o botão direito do mouse no campo desejado e pressione a opção Delete.

Configurando um relatório de origem Fonte Dinâmica

Quando realizado o download de um relatório com Fonte Dinâmica os campos não são apresentados em Fields como apresentado em um relatório de origem Padrão, com isso é necessário inserir um a um manualmente. Para tal propósito, clique com o botão direito do mouse em Field e logo em Create Field, as informações para preenchimento ficam localizadas do lado direito da tela em Object.

A estrutura dos dados definidos para o esquema da fonte deve ser criada conforme a necessidade do relatório, e fica a cargo do desenvolvedor/analista definir os campos e tipos mais adequados. A nomenclatura dos campos segue as mesmas regras de nomenclatura de variáveis e os tipos de dados disponíveis, assim como seus equivalentes no Jaspersoft podem ser conferidos na tabela a seguir:

Nome	Dado JRXML
Esquema.caracter	java.lang.String
Esquema.inteiro	java.lang.Long
Esquema.numero	java.math.BigDecimal
Esquema.data	java.util.Date
Esquema.objeto	java.util.Object
Esquema.lista	java.util.List

Segue exemplo de configuração adequada entre o script e o arquivo do Jaspersoft , conforme tabela anterior:

Como é preciso inserir exatamente os dados informados no esquema do script, será inserido no Jaspersoft exatamente como descrito no esquema abaixo.

Neste exemplo serão inseridas três informações no Field: id, nome e idade.

Como mencionado anteriormente o esquema do nosso exemplo foi criado com as mesmas regras de nomenclatura de variáveis equivalentes no Jaspersoft, veja abaixo nas imagens.

Agora, é possível visualizar todos os campos da fonte de dados criados manualmente em Fields.

Os dados que nosso relatório precisa retornar será às informações conforme o script, consequentemente existem 4 linhas com dados diferentes. Veja na imagem abaixo.

Para realizar a impressão dessas informações dentro do relatório é preciso inserir as colunas na opção Details (1), antes disso clique nesta opção e do lado direito nas propriedades da banda altere o campo Height para 50 (2), assim, o espaço será ampliado facilitando a visualização da banda no centro da tela (3).

Insira um Text Field na banda Detail, para isso segure e arraste até o centro da tela.

Clique duas vezes na caixa de texto inserida no centro da tela. Aparecerá a informação na coluna com os dados do Id. Dê um duplo clique em id (1), logo, aparecerá a expressão $F{id} (2), por último pressione o botão Finish. Repita o processo para todas as colunas que necessitam ser apresentadas.

Assim sendo, as três colunas do exemplo aparecem lado a lado na banda Detail.

Para inserir o nome das colunas, copie e cole as informações inseridas anteriormente em Column Header, porém insira os nomes das colunas que o usuário irá visualizar no relatório (o nome precisa estar entre "aspas"). Se não estiver visível essa banda, aumente os pixels nas propriedades, exatamente como mostrado na banda Detail.

A ferramenta possui ainda uma barra edição, possibilitando alterar cor, tamanho, fonte e alinhamento.

Quando clicado em alguma região no centro da tela, uma linha horizontal na é exibida do lado esquerdo da tela, com ela note o começo e o fim de cada banda.

Realizando esses passos básicos, o relatório já pode ser executado, mas para isso realize upload do arquivo com as alterações realizadas no Gerenciador de relatórios.

Pressione o botão EXECUTAR e conferir o resultado.

Criando bandas do tipo Group

Para criar uma banda do tipo Group realize os passos mostrados anteriormente, logo uma nova janela é aberta para que seja preenchida a descrição do grupo no campo Group Name e a variável que trará a informação desejada, neste exemplo será o tipo_pessoa. Logo após, pressione o botão Next.

Nessa janela é permitido selecionar quais as bandas serão criadas para controle do grupo, sendo elas: Column Header (cabeçalho) e Column Footer (rodapé). Logo, pressione o botão Finish para salvar as informações.

Perceba que os dois itens marcados anteriormente apareceram na árvore do projeto como novas bandas que servirão para o grupo e ficam entre a banda Detail.

Quando essas bandas são criadas, o conteúdo das mesmas é impresso apenas uma vez no início e fim da ocorrência do grupo, respectivamente, e normalmente utiliza-se as mesmas para inserir os dados do agrupamento e totalizadores do grupo. Costuma-se utilizar também essas bandas de grupo em substituição às bandas padrões 'Column Header/Footer'.

Propriedades

Um dos recursos interessante e muito utilizado são as propriedades. Ao clicar em qualquer opção das bandas ou em qualquer recurso do lado esquerdo da tela e/ou em algum objeto no centro da tela, as informações vão mudando na parte direita da tela. Essa parte é chamada de Janela de propriedade. Sendo assim, quando houver necessidade de qualquer configuração um pouco mais detalhada em algum componente do relatório será feito através das propriedades.

Exemplo: quando selecionado um campo de texto, a ferramenta mostra as propriedades desse recurso, mas quando selecionado uma banda outros dados são informados. Observe nas imagens abaixo.

Quando clicado na raiz do relatório "Report" onde tem tudo agrupado referente ao projeto, é apresentado uma série de configurações específicas do lado direito da tela do relatório em si.

Title on a new page	Esta opção especifica que a faixa de título deve ser impressa em uma nova página, o que força uma quebra de página no final da faixa de título. Na primeira página apenas a faixa de título é impressa, no entanto esta página ainda está incluída na contagem total de páginas.
Summary on a new page	Esta opção é semelhante ao Título em uma nova página, exceto que a faixa de resumo é impressa como a última página. Caso precise imprimir esta faixa em uma nova página, conterá apenas um resumo.
Summary with page header and footer	Esta opção especifica se a faixa de resumo deve ser acompanhada pelo cabeçalho ou rodapé da página.
Floating column footer	Esta opção força a impressão do rodapé da coluna imediatamente após a última faixa de detalhes (ou rodapé de grupo) em vez do final da coluna. Esta opção é usada, por exemplo, quando desejar criar tabelas usando os elementos de relatório.
Ignore Pagination	Este item é usado para especificar se deve usar ou não paginação. Por padrão, a paginação é usada, exceto quando exportado para os formatos HTML e Excel.

Se por algum motivo abrir o Jasper e não visualizar essas janelas ou deletar alguma por engano, não se desespere!

Clique no menu Window > Reset Perspective que será resetado e voltará para o layout padrão.

Padrões de formatação caixa de texto

As propriedades do elemento são divididas em categorias, visíveis por meio de guias na visualização de Propriedades. Os atributos disponíveis dependem do tipo de elemento. Aqui, são apresentadas seis abas: Appearance, Borders e Text Field, Inheritance, Hyperlink e Advanced. O layout do relatório é muito importante, pois é por essas abas que se definem os padrões de fonte, cor, bordas entre outras e, é através de um relatório que um desenvolvedor mostra para o cliente o quanto é apresentável e está de acordo com suas necessidades.

Appearance	Define localização, tamanho, cor e estilo de texto do elemento.
Borders	Define o preenchimento e o estilo da borda, a cor e a largura do elemento.
Text Field	Formata e posiciona elementos de campo de texto.
Inheritance	Permite visualizar quaisquer atributos herdados de outro nível e substituir aqueles atributos quando possível.
Hyperlink	Define um hiperlink em um elemento. A guia Hiperlink, disponível para imagem, campo de texto e elementos gráficos.
Advanced	Exibe informações detalhadas sobre o elemento.

É necessário que o desenvolvedor dedique um tempo para que o relatório fique organizado, que esteja com as colunas alinhadas, sem excesso de espaços, com bordas separando informações, em outros termos, precisa estar apresentável para o cliente.

As configurações mais utilizadas para as caixas de textos na banda detail são: fonte Arial, tamanho 9, largura da caixa de texto dependerá da informação que será apresentada, quanto a altura é determinado 3 tamanhos maiores que a fonte, portanto será o tamanho 12 neste exemplo.

Pressione ctrl+c, logo ctrl+v para criar uma nova caixa de texto, assim, não precisará formatá-la novamente, posicione-a para que fiquem lado a lado. Para alterar a informação da caixa copiada dê duplo clique e altere a informação desejada pois abrirá uma caixa de texto com todas as informações disponíveis.

Para aplicar a borda, selecione-as as caixas de texto (o botão shift precisa estar pressionado), logo, clique em Borders, é através desse recurso que será inserido bordas no relatório exibido algumas variações de estilos como: abaixo, acima, abaixo/acima e em todos os lados. Pode-se também mudar a cor, estilo e a espessura da linha da borda. Geralmente a cor é preta, a linha é sólida e a espessura da linha é definida como 0,30. Perceba que a banda detail há um espaço muito grande, caso for executado o relatório dessa maneira será apresentado com todo esse espaço, para diminuir dê duplo clique na banda e automaticamente a ferramenta irá se adequar ao tamanho da caixa de texto ficando mais amigável.

Neste exemplo foi criado um grupo de informações (banda g_tipo_pessoa) para serem agrupadas pessoas do tipo físicas e jurídicas. Dessa forma, para obtermos o nome da coluna, é necessário ser utilizado uma informação proveniente da fonte de dados, que neste caso será utilizado o campo tipo de pessoa. Em algumas situações é necessário utilizar comando get para ler a propriedade da fonte, por exemplo, quando o tipo do campo for um Map (como no caso do campo tipo de pessoa), deve-se utilizar o comando .get() para extrair o valor desejado. Ao dar duplo clique na caixa de texto correspondente o comando deverá ficar como mostra na imagem mostrada abaixo.

Logo, é exibido o conteúdo inserido anteriormente na banda criada.

Agora, salve o documento, realize o upload no Gerenciador de relatório e execute o relatório.

Veja que as informações ficaram misturadas, apareceram pessoas físicas, depois uma jurídica e logo físicas novamente. Para que apareçam as físicas primeiro e depois as jurídicas é preciso ordenar, essa configuração está disponível em Configuração da fonte > Ordenação, como no exemplo está sendo agrupado por Tipo de pessoa será marcado o checkbox correspondente e na classificação será escolhido crescente. Com isso já aparecerá os itens do relatório na ordem desejada. Após inserir as informações, pressione o botão salvar para gravar as informações.

Ao executar é visível a mudança, agora todas as pessoas físicas são apresentadas primeiro. A ordenação ocorreu da forma esperada.

A fonte está bem colada na linha, para corrigir use o recurso Paddings, ele tem por objetivo criar uma margem interna na caixa de texto, neste exemplo como o nome está do lado esquerdo foi usado o número 3 no campo left, perceba que o texto não está mais colado na parte esquerda da borda.

E para centralizar o conteúdo no centro da caixa de texto utilize o recurso mostrado na imagem abaixo.

Text Elements

Um campo de texto permite imprimir uma seção arbitrária de texto (um número ou uma data) criada usando uma expressão.

O caso mais simples de uso de um campo de texto é imprimir uma string constante (java.lang.String) criada usando um expressão assim:

"Isto é um texto"

Um campo de texto que imprime um valor constante como o retornado por esta expressão pode ser facilmente substituído por um campo estático; na verdade, o uso de uma expressão para definir o conteúdo de um campo de texto fornece um alto nível de controle sobre o texto gerado (mesmo que seja apenas texto constante). Um caso comum é quando os rótulos precisam ser internacionalizados e carregados de um pacote de recursos. Em geral, uma expressão pode conter campos, variáveis ​​e parâmetros, para que você possa imprimir em um campo de texto o valor de um campo e definir o formato do valor a ser apresentado. Por este propósito, uma expressão de campo de texto não precisa retornar necessariamente uma string (que é um valor de texto): o campo de texto expressão class name propriedade especifica que tipo de valor é retornado pela expressão. Pode ser um dos seguintes:

Tipos de expressão válidos
java.lang.Object	java.sql.Time	java.lang.Long
java.lang.Boolean	java.lang.Double	java.lang.Short
java.lang.Byte	java.lang.Float	java.math.BigDecimal
java.util.Date	java.lang.Integer	java.lang.String
java.sql.Timestamp

Uma classe de expressão incorreta é frequentemente a causa de erros de compilação. Se você usa Groovy ou JavaScript, pode-se escolher String como tipo de expressão sem causar um erro quando o relatório for compilado. O efeito colateral é que sem especificar a classe de expressão correta, o padrão (definido) não é aplicado ao valor.

Veja quais propriedades podem ser definidas para um campo de texto:

Blank when null	Se definida como true, esta opção evita imprimir o conteúdo do campo de texto caso o resultado da expressão for um objeto nulo que produziria o texto “null” quando convertido em uma string.
Evaluation time	Determina a qual fase da criação do relatório a Expressão do campo Texto será elaborada. Utiliza-se com frequência em caixas de textos alocados em cabeçalhos de grupo que possuem variáveis que são calculadas ao final de um grupo.
Evaluation group	O grupo ao qual o tempo de avaliação se define como Group.
Stretch with overflow	Quando selecionada esta opção permite que o campo de texto adapte-se verticalmente ao conteúdo, caso o elemento não seja suficiente para conter todas as linhas de texto.
Pattern	Permite definir uma máscara para formatar um valor. É usado apenas quando a classe de expressão é congruente com o padrão a ser aplicado, o que significa que é preciso um valor numérico para aplicar uma máscara para formatar um número ou uma data para usar como padrão de data.

Variáveis

São campos que se assemelham aos fields, porém com uma diferença: quando se lê um field teremos um dado fixo originado da fonte de dados, já as variáveis permitem controlar seu conteúdo através de uma expressão, sendo assim, será inserido um valor dentro dela. Exemplo: soma de um determinado campo, uma contagem e assim por diante.

No exemplo abaixo será mostrado em detalhes como fazer para aparecer a quantidade de pessoas existentes em um relatório, será utilizado o mesmo relatório do exemplo anterior. Para criar uma variável clique com o botão direito sobre Variable e logo com o esquerdo em Create Variable.

Neste exemplo será criado uma variável que vai se referir a um contador, ou seja, ela vai contar quantas pessoas têm no relatório. Do lado esquerdo fica visível a variável criada e quando selecionada as propriedades aparecem e nelas são realizadas todas as configurações dessa variável. É nesse estágio que o desenvolvedor precisa ficar atento, pois praticamente todos os campos precisam ser ajustados.

Veja abaixo as configurações de cada campo:

Name

É a descrição dada a variável criada. É neste momento que será criada a caixa de texto e configurada para aparecer a informação desejada. Copie e cole uma caixa de texto e insira no lado esquerdo da tela onde aparecerá o contador. Logo após dê dois cliques na caixa de texto. Logo, em Variables e depois selecione a variável criada, a informação ficará na caixa de texto na parte superior da tela. Por fim, pressione o botão Finish.

A caixa de texto será exibida e associada com a variável criada anteriormente.

Value Class Name

Sabemos que a variável sozinha não faz nada, é necessário explanar a ela qual o tipo de dado resultante da expressão configurada. Depois da criação da mesma é informado qual o tipo através do campo Value Class Name, por padrão vem sempre como String (variável do tipo texto), porém são apresentadas várias alternativas passíveis de seleção.

Neste caso será selecionada a opção Integer, por se tratar de um número inteiro.

Calculation

Neste recurso estão presentes todas as funções de cálculo para uma variável. Por padrão fica marcado a função No Calculation Function (quando utilizado essa função é necessário realizar um cálculo em forma de programação no campo Expression), porém este campo já vem com algumas funções pré-definidas e é permitido trocar por qualquer outra que desejar.

Uma função de cálculo é um atributo que especifica quando uma variável pode ser usada em associação com a expressão para determinar o valor da variável. Ao usar uma função de cálculo, o valor da variável não é determinado diretamente por sua expressão. Em vez disso, ele é passado para a função de cálculo que o utiliza para determinar seu valor.

Confira abaixo todas as funções de cálculo existentes:

Sum	A cada iteração o valor da variável é somado.
Count	A cada iteração o valor da variável é incrementado em uma unidade (somente se a expressão não for nula).
Distinct Count	A cada iteração o valor da variável é incrementada em uma unidade, porém, somente se o valor da expressão nunca foi retornada.
Average	O valor da variável é a média de todos os valores recebidos da expressão.
Lowest	A variável recebe o valor do elemento mais baixo da expressão.
Highest	A variável recebe o valor do elemento mais alto da expressão.
Standard Deviation	Desvio padrão de todos os valores recebidos da expressão.
First	A variável recebe o primeiro valor retornado pela expressão.
System	Nenhum cálculo é feito e a expressão não é avaliada, o valor da variável é o último valor definido nele. Isso é útil para armazenar resultados parciais ou resultados finais de um cálculo.

Neste exemplo será utilizado a função Count, pois ele realizará uma contagem "simples" de pessoas.

Expression

O tipo de uma expressão é determinado pelo contexto da qual a expressão é usada. Por exemplo, se a expressão for usada para avaliar uma condição, a expressão deve ser booleana (true ou false); se estiver criando uma expressão para exibir um campo de texto, provavelmente é uma String ou um número (Integer ou Double). Usando o tipo certo é crucial, pois o Jaspersoft requer precisão ao escolher um tipo de expressão.

Diante disso, aqui é possível escolher qual expressão do dado que ele vai gerar o valor da variável, como neste exemplo está sendo trabalhado com a uma variável do tipo contagem pode-se pegar o campo raiz como nome da pessoa ou até mesmo o Id. Para inserir a informação clique no ícone ao lado do campo Expression, logo, uma nova tela é aberta para que a informação seja inserida, aqui será inserido o Id.

Initial Value Expression

Aqui será informado a inicial que a variável vai iniciar. No exemplo foi informado 0 já que estamos falando de contagem simples. Recomenda-se sempre preencher esse campo com um valor adequado ao tipo da variável. Por exemplo: se a variável for do tipo String, preencher o valor inicial com um texto vazio (“”), se for BigDecimal, preencher com o comando “BigDecimal.ZERO”, e assim por diante.

Increment type e Reset Type

Increment type são regras pré-definidas que mostram opções iguais as bandas a serem utilizadas no relatório. Como padrão vem a opção None, significa que para cada registro lê diretamente da fonte e vai estar executando o que foi marcado na função Expression ($F{id}), ou seja, expressão de contagem. Neste caso, a opção que mais se adequa ao exemplo é o None.

Caso o desenvolvedor realizar a contagem por grupo, é necessário escolher a opção [Group] gtipo_pessoa (para mais detalhes acesse o tópico criando bandas). Exemplo: essa opção possui tipo de pessoas físicas e jurídicas, portanto o relatório começará a contar o grupo da pessoa física 1, 2, 3…, quando chegar no grupo de pessoas jurídicas ele recomeça a contagem 1, 2, 3… e assim por diante. Na opção _None isso não acontece, se possuir 200 pessoas ao todo sendo 100 em cada grupo, quando chegar no grupo de pessoas jurídicas será contado como 101, 102, 103… e assim por diante.

A opção Reset Type também é configurada por banda e ele vai informar quando a variável vai tornar a receber o valor inicial dela. Como padrão vem a opção Report, isso significa que ele nunca irá reiniciar a contagem e é nessa opção que será utilizado nesse exemplo.

O grupo criado será utilizado no seguinte caso: pense em um relatório que está realizando uma contagem de valores de algum campo que é por entidade, então cada entidade precisa contar do zero, porque ele não pode contar sequencialmente. Neste caso é preciso informar o grupo.

A configuração do relatório configurado ficou da maneira mostrada na imagem abaixo.

Ao realizar o upload no Gerenciador e executar o relatório é possível visualizar o que gerou corretamente. Apareceu primeiro as pessoas físicas e logo as pessoas jurídicas.