FreeMarker

O que é FreeMarker?

FreeMarker é um “mecanismo de templates”, uma ferramenta genérica para geração de saída de texto(nada de HTML para auto-geração de código fonte) baseado em templates. É um pacote java para programadores, não uma aplicação para usuários finais, mas algo para programadores adicionarem aos seus códigos.

Desenvolvido para tornar prática a geração de Web Pages, particularmente baseado em aplicações servlets MVC(Model View Controller). A idéia iniciou-se utilizando o MVC para páginas dinâmicas, separando os desenvolvedores HTML dos programadores. A idéia é ajudar a separar bem as coisas, criando por exemplos, templates para cuidar de todo o acesso ao banco de dados(Selects), deixando o código mais limpo e de fácil manutenção.

Embora FreeMarker tem alguns recursos de programação, não é uma linguagem de programação completa, como PHP. Em vez disso, os programas Java preparar os dados a serem exibidos (como consultas questão SQL), e FreeMarker apenas gera páginas de texto que são apresentados os dados elaborados usando modelos.

Se você está procurando um sistema de template para ser usado na sua aplicação (seja ela web ou não), Freemarker pode ser uma boa pedida. Trata-se de um engine que, baseado em templates pré-definidos, gera um arquivo de saída. Esse arquivo pode ser qualquer coisa: HTML, XML, texto simples, etc. Você pode usá-lo em sua aplicação web para gerar conteúdo dinâmico (no lugar de JSP) ou pode usá-lo em qualquer aplicação que precise gerar uma saída de texto variável

As classes/arquivos criados tem a extensão .FTL e necessitam estar nesta estrutura:

Links para mais informações:

http://www.devmedia.com.br/articles/viewcomp.asp?comp=10552

http://freemarker.org/

Gerando código com o FreeMarker (DevMedia)

Neste artigo será apresentado o FreeMarker, um poderoso framework de templates, similar ao famoso Velocity da Jakarta.

O FreeMarker é muito utilizado por alguns frameworks Web MVC como a principal tecnologia utilizada na camada de apresentação, substituindo o JSP, que é o caso por exemplo do framework WebWork.

Embora muitos utilizem o FreeMarker no lugar do JSP, o seu principal objetivo é ser um simples e rápido framework de templates, o qual pode ser utilizado para automatizar a geração de determinado código. Um exemplo de aplicação que utiliza o FreeMarker com esta finalidade é o HibernateTools, ferramenta bem conhecida dos usuários do Hibernate..

Neste artigo será apresentado como escrever um simples template em FreeMarker, e separar a lógica de negócios do “design” do seu template.

FreeMarker

Para rodar o exemplo deste artigo, faça o download do FreeMarker 2.3.8:

Þ      http://prdownloads.sourceforge.net/freemarker/freemarker-2.3.8.tar.gz

Após fazer o download, coloque o arquivo “freemarker.jar” no classpath do seu projeto.

Utilizando o FreeMarker

A classe abaixo demonstra como utilizar o FreeMarker. O método “parseTemplate” recebe um Map com os parâmetros e o nome do template. O resultado é uma String (texto) com o template processado.

É recomendado que seja criado somente uma instância da classe “Configuration”, e para isto uma variável privada e estática foi declarada na classe.

Note que a constante “TEMPLATES_FOLDER” define o local onde estão os templates. O valor da constante está fixa no código para facilitar o exemplo.

import java.io.File;

import java.io.IOException;

import java.io.StringWriter;

import java.util.Map;

import freemarker.template.Configuration;

import freemarker.template.DefaultObjectWrapper;

import freemarker.template.Template;

import freemarker.template.TemplateException;

public class FreemarkerUtils {

private static Configuration cfg = new Configuration();

private static final String TEMPLATES_FOLDER = ”templates”;

public static final String parseTemplate(Map map,String templateName)throws TemplateException, IOException  {

//diretório onde estão templates

cfg.setDirectoryForTemplateLoading(new File(TEMPLATES_FOLDER));

cfg.setObjectWrapper(new DefaultObjectWrapper());

//recupera o template

Template t = cfg.getTemplate(templateName);

StringWriter writer = new StringWriter();

/** Freemarker **/

t.process(map, writer);

writer.flush();

writer.close();

return writer.toString();

}

}

Exemplo

Para utilizar a classe anterior, vamos criar um arquivo de template chamado “teste.ftl” na pasta “templates”. Se você estiver usando o Eclipse, a pasta “templates” pode ser criada na raiz do seu projeto:

teste.ftl

${data?string(“dd/MM/yyyy”)}

Prezado ${usuario}, segue a lista de produtos:

<#list produtos as p>

- ${p.nome} - R$${p.preco}

</#list>

O template acima demonstra como construir um “email” para enviar aos usuários de um sistema. No template, a data atual e o nome do usuário são exibidos, e também uma possível lista de produtos selecionados para este usuário.

Para rodar o exemplo crie a classe Produto, conforme abaixo:

public class Produto {

private String nome;

private double preco;

public Produto(String nome, double preco) {

super();

this.nome = nome;

this.preco = preco;

}

public String getNome() {

return nome;

}

public double getPreco() {

return preco;

}

}

E finalmente, uma pequena classe que executa o template “teste.ftl”, passando os parâmetros necessários:

public class HelloTemplate {

public static void main(String[] args) throws IOException,TemplateException {

Map map = new HashMap();

map.put(“data”, new Date());

map.put(“usuario”, ”Ricardo”);

List produtos = new ArrayList();

produtos.add(new Produto(“Produto A1″,300.14));

produtos.add(new Produto(“Produto B2″,401.56));

produtos.add(new Produto(“Produto C3″,555.77));

map.put(“produtos”, produtos);

String s = FreeMarkerUtils.parseTemplate(map, ”teste.ftl”);

System.out.println(s);

}

}

A saída do programa pode ser visualizada abaixo:

13/11/2006

Prezado Ricardo, segue a lista de produtos:

- Produto A1 – R$300.14

- Produto B2 – R$401.56

- Produto C3 – R$555.77

Conclusão

O template construído neste artigo, poderia ser um “email” enviado a uma lista de usuários de um sistema. Tente criar um template, onde a saída seja um arquivo HTML, e enviá-lo por email com a API Commons-email descrita neste artigo:

http://www.devmedia.com.br/articles/viewcomp.asp?comp=3306

O FreeMarker é sem dúvida muito simples, sendo possível utilizá-lo para gerar código, ou até mesmo em aplicações Web, substituindo o JSP na camada de visualização.

Referências:

Þ      http://freemarker.sourceforge.net/

Þ    http://www.javaworld.com/javaworld/jw-01-2001/jw-0119-freemarker.html?page=2

MANUAL

• Preface
• I   Template Author’s Guide
  • 1   Getting Started
    • Template + data-model = output
    • The data-model at a glance
    • The template at a glance
  • 2   Values, Types
    • Basics
    • The types
  • 3   The Template
    • Overall structure
    • Directives
    • Expressions
    • Interpolations
  • 4   Miscellaneous
    • Defining your own directives
    • Defining variables in the template
    • Namespaces
    • White-space handling
    • Alternative (square bracket) syntax
• II   Programmer’s Guide
  • 1   Getting Started
    • Create a configuration instance
    • Create a data-model
    • Get the template
    • Merging the template with the data-model
    • Putting all together
  • 2   The Data Model
    • Basics
    • Scalars
    • Containers
    • Methods
    • Directives
    • Node variables
    • Object wrappers
  • 3   The Configuration
    • Basics
    • Shared variables
    • Settings
    • Template loading
    • Error handling
  • 4   Miscellaneous
    • Variables
    • Charset issues
    • Multithreading
    • Bean wrapper
    • Logging
    • Using FreeMarker with servlets
    • Configuring security policy for FreeMarker
    • Legacy XML wrapper implementation
    • Using FreeMarker with Ant
    • Jython wrapper
• III   XML Processing Guide
  • Preface
  • 1   Exposing XML documents
    • The DOM tree
    • Putting the XML into the data-model
  • 2   Imperative XML processing
    • Learning by example
    • Formal description
  • 3   Declarative XML Processing
    • Basics
    • Details
• IV   Reference
  • 1   Built-in Reference
    • Built-ins for strings
    • Built-ins for numbers
    • Built-ins for dates
    • Built-ins for booleans
    • Built-ins for sequences
    • Built-ins for hashes
    • Built-ins for nodes (for XML)
    • Seldom used and expert built-ins
  • 2   Directive Reference
    • if, else, elseif
    • switch, case, default, break
    • list, break
    • include
    • import
    • noparse
    • compress
    • escape, noescape
    • assign
    • global
    • local
    • setting
    • User-defined directive (<@…>)
    • macro, nested, return
    • function, return
    • flush
    • stop
    • ftl
    • t, lt, rt
    • nt
    • attempt, recover
    • visit, recurse, fallback
  • 3   Special Variable Reference
  • 4   Reserved names in FTL
  • 5   Deprecated FTL constructs
    • List of deprecated directives
    • List of deprecated built-ins
    • Old-style macro and call directives
    • Transform directive
    • Old FTL syntax
    • #{…}: Numerical interpolation
• V   Appendixes
  • A   FAQ
  • B   Installing FreeMarker
  • C   Building FreeMarker
  • D   Versions
    • 2.3.16
    • 2.3.15
    • 2.3.14
    • 2.3.13
    • 2.3.12
    • 2.3.11
    • 2.3.10
    • 2.3.9
    • 2.3.8
    • 2.3.7
    • 2.3.7 RC1
    • 2.3.6
    • 2.3.5
    • 2.3.4
    • 2.3.3
    • 2.3.2
    • 2.3.1
    • 2.3
    • 2.2.8
    • 2.2.7
    • 2.2.6
    • 2.2.5
    • 2.2.4
    • 2.2.3
    • 2.2.2
    • 2.2.1
    • 2.2
    • 2.1.5
    • 2.1.4
    • 2.1.3
    • 2.1.2
    • 2.1.1
    • 2.1
    • 2.01
    • 2.0
    • 2.0 RC3
    • 2.0 RC2
    • 2.0 RC1
  • E   License
• Glossary
• Alphabetical Index