Iniciando com FreeMarker

FreeMarker é uma template engine, ou seja, uma biblioteca java capaz de gerar uma saída formatada aplicando dados dinâmicos seguindo regras pré-configuradas em um template estático. Ficou confuso? Que tal um exemplo? Imagine que você têm um sistema de e-commerce, e cada vez que seu cliente faz uma compra, você precisa enviar um email confirmando o pedido para ele. Provavelmente, seu email terá um texto padrão, uma formatação fixa e só mudará alguns detalhes, como o nome do cliente e os itens comprados. Você pode criar um template, como por exemplo:

Olá ${nome}
Seu pedido de compra do item ${produto} foi realizado com sucesso!

Obrigado por comprar conosco

Os trechos ${nome} e ${produto} são as partes que vão mudar de acordo com o pedido. O restante será sempre igual. Dessa forma garantimos que o texto segue um padrão mas sem perder a personalização da mensagem.

Mas de onde vem o nome do cliente e o produto comprado? De objetos java é claro. Quem vai fazer essa interpolação de template + objeto java será nosso amigo freemarker e nesse post vamos aprender o básico de como fazer isso através de um projetinho simples.

1 – Vamos começar criando o projeto pelo maven. Crie um diretório qualquer e acesse-o pelo console do DOS ou shell script. Digite o comando abaixo para criar um novo projeto (utilizei o maven versão 3.3.9):

 mvn archetype:generate -DgroupId=com.minhaempresa -DartifactId=freeMarker-exemplo -Dversion=1.0.0-SNAPSHOT -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

 

2 – O maven criou um diretório chamado freeMarker-exemplo com o conteúdo da figura 1:

figura 1 - Estrutura inicial

Figura 1 – Estrutura inicial

3 – Agora vamos alterar o arquivo pom.xml para incluir a dependência do freeMarker. Abra o arquivo e inclua o seguinte trecho entre as tags <dependencies> e </dependencies>:

<dependencies>
 	...	
	<dependency>
		<groupId>org.freemarker</groupId>
		<artifactId>freemarker</artifactId>
		<version>2.3.23</version>
	</dependency>
	...
</dependencies>

4 – Rode o comando mvn install e importe o projeto no eclipse (se aparecer um erro relacionado ao junit, altere a versão da dependência no pom.xml para 4.12).

Figura 2 - Dependencias maven

Figura 2 – Dependencias maven

5 – Precisaremos criar uma classe contendo as configurações mínimas do freeMarker. Essas configurações serão válidas para toda aplicação e o próprio site oficial indica que devemos criar apenas uma instância dessa classe para evitar sobrecarga desnecessária em nosso sistema. Crie um novo package, por exemplo, config e dentro dele crie uma classe para guardarmos as configurações do freeMarker. Essa classe será um singleton.

Figura 3 - Classe de configuração

Figura 3 – Classe de configuração

 

6 –  Note, na figura 3, que criamos um atributo configuration do tipo freemarker.template.Configuration. Esse atributo é o motor que irá interpretar nossos templates e substituir os dados. Para isso, precisaremos fornecer algumas informações para ele. Já que criamos um singleton, vamos definir as configurações no próprio construtor da classe.

Figura 4 - Configuração FreeMarker

Figura 4 – Configuração FreeMarker

Na linha 12 da figura 4, criamos uma nova instância de Configuration, passando como parâmetro a versão que estamos utilizando (2.3.23).

Depois (linha 13) definimos um encoding que será utilizado em nossos templates.

Na linha 14, definimos o local onde ficarão nossos templates. Estou apontando para um diretório templates dentro da pasta resources do projeto (o freemarker encontrará a pasta resources baseado na própria classe. É possível apontar diretamente para um diretório através do método setDirectoryForTemplateLoading, que pode ser útil para carregar o caminho a partir de um banco de dados, por exemplo).
7 – Maravilha, agora que o freeMarker está configurado, vamos criar nosso template. Crie o diretório src/main/resources/templates e dentro dele crie um arquivo com extensão .ftlh. Ficará como na figura 5:

 

Figura 5 - Pasta templates

Figura 5 – Pasta templates

8 – Inclua o mesmo conteúdo da figura 6 no arquivo .ftlh. Perceba que incluímos os valores ${nome} e ${produto}, que são nossas variáveis alimentadas dinamicamente.

 

Figura 6 - Conteúdo do template

Figura 6 – Conteúdo do template

9 – Agora que temos o template, vamos criar uma classe que vai guardar os dados que queremos exibir. Para isso, crie um pacote model e dentro dele, crie uma classe Pedido com os atributos nome e produto, como na figura 7. Cuidado, o freemarker precisa de um método get para os atributos que serão substituídos, portanto, se você tem um ${nome} e um ${produto} no seu template, deverá ter um getNome e getProduto em sua classe :

 

Figura 7 - Classe Pedido

Figura 7 – Classe Pedido

10 – O que falta? Juntar tudo é claro. Vamos fazer isso na classe App.java que o maven ja criou pra gente. Primeiro precisamos pegar a instância de configuration através do singleton que criamos no passo 5. Através do configuration, vamos criar um objeto template que interpretará nosso arquivo e saberá o que é estático e o que é dinâmico. Como você já deve ter imaginado, esse processo de interpretação pode não ser tão leve dependendo do template, por isso o freemarker já cria um cache dos templates para não precisar carregá-los de novo. Agora que temos nosso objeto template, só chamar o método process, passando nosso objeto e a saída que será um writer. Olha só como ficou na figura 8:

Figura 8 - Montando a saída

Figura 8 – Montando a saída

 

11 – Agora só rodar e ver o resultado (figura 9):

Figura 9 - Resultado

Figura 9 – Resultado

Legal, mas o freemarker só faz isso? Nãaaao!! Existem vários comandos, expressões e regras que você pode aplicar nos templates, desde um comando condicional if/else, até repetição em uma lista, valores default, expressões regulares e muito mais. Você pode até criar suas próprias diretivas. O que foi apresentado nesse post foi só uma pontinha do que ele pode fazer. No próximo post vou detalhar mais sobre esse universo de possibilidades, mas se você ficou curioso, dê uma olhadinha no site oficial do freemarker aqui. Você também pode testar os templates nesse site.

Até lá!!

 

 

Por MARCIA TANIMOTO

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

Postado em: 04 de janeiro de 2017

Confira outros artigos do nosso blog

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

Sistemas poliglotas

27 de junho de 2017

Ronaldo Chicareli

CRUD com Spring e Thymeleaf

16 de fevereiro de 2017

Stéffano Bonaiva Batista

Deixe seu comentário