Um pouco mais sobre FreeMarker

Olá! No post anterior apresentei uma breve introdução sobre o freemarker e expliquei como montar um projeto java simples que substituía trechos de um texto por outro. Nesse post vamos falar um pouco mais sobre alguns elementos básicos dessa interessante ferramenta.

Primeiro, vamos relembrar o que foi feito no post anterior. Criamos um template que era basicamente uma arquivo texto com algumas palavras entre ${} e preenchemos essas palavras por valores fornecidos pelo código java (Figura 1).

Figura 1 - Template freemarker
Figura 1 – Template

Nesse exemplo o que fizemos foi definir um template utilizando a linguagem ftl (freemarker template language) e aplicamos um data model para interpolar os dados e gerar uma saída. Vamos entender como a linguagem ftl funciona e quais tipos de dados podem ser aplicados.

Os templates freemarker podem conter basicamente 4 elementos:

  • trechos que devem ser substituídos, ou pontos de interpolação (ficam entre ${}),
  • tags ftl (ficam entre #{}),
  • comentários (ficam entre <#– –>) e
  • Texto estático.

E podem ter 4 tipos de dados aplicados ou data models:

  • scalars,
  • hashes,
  • sequences,
  • collections.

 Tipos de dados ou data models

Data model é o conjunto de informações que serão utilizados para montagem do template. Os data models seguem uma estrutura tree like, ou seja, podem ser montados e acessados de forma hierárquica. Um data model pode conter tanto dados simples, como textos ou números, quanto objetos ou lista de objetos. Todo template possui um elemento raiz (root) que conterá todos os outros elementos utilizados no template. O elemento raiz é um elemento do tipo hash e deve ser fornecido no momento de gerar o template (no método process da classe freemarker.template.Template, lembra?).

Os tipos de dados scalar são tipos primitivos que podem ser strings (textos), numbers (números, inteiros ou decimais), datas ou booleans (verdadeiro ou falso).

Os tipos hash são valores que guardam outros valores e que podem ser identificados por um nome. (como em objetos ou mapas em java).

Os tipos sequence são listas de valores que são identificados por um índice numérico começando de zero (como um array).

Os tipos collection são listas de valores que não possuem identificação por índice ou nomes, devendo ser acessados sequencialmente (como listas em java).

Por exemplo, digamos que a classe da figura 2 será usada para alimentar um template:

Figura 2 - Data Model fornecido
Figura 2 – Data Model fornecido

 

O atributo nome e id são dados scalars, a lista de pedidos é uma collection e o endereco um hash. Perceba que o template aceita que um data model possua objetos dentro dele. Para acessar a rua do endereço, por exemplo, posso utilizar o seguinte valor no template:

${endereco.rua}

Para percorrer a lista de pedidos, posso utilizar a diretiva list, explicada mais adiante:

<#list pedidos as pedido><p>${pedido}</p></#list>

Elementos ftl

A linguagem ftl é utilizada para compor os templates e possui, além dos pontos de interpolação, também diretivas (ou tags) e funções, que podem ser utilizadas para aplicar transformações específicas nos data models. É importante lembrar que, apesar de fornecer ferramentas para programar lógica no template, o ideal é que os dados já sejam fornecidos calculados pelo back-end e com a lógica correta, deixando para o template apenas algumas poucas formatações.

Os pontos de interpolação são variáveis ou valores recebidos de data models que serão substituídos no arquivo de saída. Foi o que fizemos no exemplo do post anterior ao declarar a variável nome entre ${} para que fosse substituído pelo valor do atributo nome do objeto pedido.

Podemos incluir também operações matemáticas nos pontos de interpolação. Por exemplo:

${contador + 1}

Ou concatenação de strings:

${"Ola " + user}

Além da substituição da variável propriamente dita, podemos também utilizar funções built-in, ou seja, já fornecidos pelo freemarker, indicados por um “?”. Por exemplo, podemos transformar todo o texto da variável user em maiúsculo:

${user?upper_case}

Ou apenas a primeira letra:

${user?cap_first}

Ou incluir 3 espaços antes do texto:

${user?left_pad(3)}

Posso verificar o tamanho de uma lista:

${minhaLista?size}

Ou aplicar um formato para data:

${minhaData?string["dd.MM.yyyy, HH:mm"]}

Ou aplicar mais de um built-in ao mesmo tempo:

${user?cap_first?left_pad(2)}

Entre várias outras funções. A lista completa pode ser encontrada aqui.

Tags ftl são como tags html, em que palavras chave (diretivas) indicam um tipo de operação que deve ser aplicado a determinado trecho do template.

Por exemplo, se quisermos imprimir uma mensagem específica somente se o usuário estiver logado no sistema, poderíamos incluir no template a tag (considerando que o valor de usuarioLogado foi fornecido por um data model):

<#if usuarioLogado == true>Você está logado no sistema</#if>

Poderíamos também incluir um texto alternativo, caso o usuário não esteja logado:

<#if usuarioLogado == true>Você está logado no sistema<#else>Faça login para acessar este recurso</#if>

Podemos percorrer uma lista de pedidos e imprimi-los na saída através da tag list (considerando que a variável “pedidos” tenha sido fornecido por um data model e seja uma lista de strings):

<#list pedidos as pedido><p>${pedido}</p></#list>

Ou separar os pedidos por vírgula utilizando a tag sep:

<#list pedidos as pedido>${pedido}<#sep>,<#/list>

Ou até incluir o conteúdo de outro arquivo:

<#include "/copyright_footer.html">

A lista completa de diretivas disponíveis podem ser encontrados aqui.

Além das diretivas fornecidas pelo freemarker, é possível também criar suas próprias diretivas, em código java, mas isso vai ficar para um próximo post.

Agora que já sabemos um pouco mais sobre o freemarker, podemos criar templates mais complexos, formatar os dados, controlar a exibição do conteúdo de acordo com uma determinada condição e muito mais. Dê uma olhadinha nas listas de diretivas e funções disponíveis do freemarker e comece a utilizá-los hoje mesmo.

Até a próxima!!

 

 Observações:

  • Os templates podem ser criados em arquivos html ou xml like. Quando definimos a extensão ftlh, estamos indicando que é um template html. Para indicar um template em xml devemos utilizar a extensão ftlx.
  • O objetivo do template é apenas apresentar os dados, por isso a lógica complexa deve sempre ser realizada na linguagem responsável por montar os data models.
  • O freemarker oferece um site para testar e validar comandos ftl. Vale a pena utilizá-lo.

Por MARCIA TANIMOTO

Formada em Informática - UEM/Maringá. Analista de Sistemas, apaixonada pela profissão, curiosa e MATERANA de coração.

Postado em: 16 de fevereiro de 2017

Confira outros artigos do nosso blog

Copa do Mundo: Integrando planilha Google com uma aplicação Firebase

19 de junho de 2018

Flavia Domingues

Como funciona a Blockchain?

11 de junho de 2018

Alan Cesar Elias

Tutorial: Carga de dados com o SQL Loader

17 de abril de 2018

Ricardo Silveira

Aprendendo Spring Framework

09 de abril de 2018

Hivison Moura

Deixe seu comentário