Introdução ao Velocity
em 02/12/2002
, por Rafael Steil
Tem sintaxe clara e fácil de entender;
Integra-se fácil a qualquer tipo de aplicação baseada em Java;
Não é restrito à internet; pode ser usado em qualquer área;
É rápido. Possui configurações de caching para deixá-lo mais rápido ainda.
Essa instrução cria uma variáve chamada $site com o conteúdo "GUJ". Nesta primeira parte do tuturial não vamos ver os detalhes da VTL, porém já adiantamos que é bem simples de aprender (são pouquíssimas diretivas) e mais simples ainda de usar. Nosso primeiro programa de exemplo consiste em mostrar o tamanho e os itens de um ArrayList através de um arquivo de template. Por padrão tais arquivo s tem a extensão "vm", mas isso não é obrigatório. Primeiramente vamos criar o arquivo que será usado como template. Não se preocupe em entender tudo agora, vamos explicar o que faz cada parte do código. Crie um arquivo chamado "template1.vm" e digite o seguinte código:
Salve o arquivo. Vamos ver para que serve para coisa. A linha:
irá mostrar o total de itens contidos no ArrayList após ser processada. $lista nesse caso é a nossa variável, e size() - pasmem - é o método size() da classe ArrayList. Se você já juntou as pecinhas deve ter notado que podemos usar qualquer método público dos objetos. Isso é uma excelente coisa! Continuando:
mostra os itens da lista em si. #foreach é a diretiva, $item é a nossa variável de template que representa um item em específico da ArrayList, e $list é a variável que contém os itens da lista (se fosse Java puro, $lista seria uma instância de ArrayList. Bom, de certa maneira $lista é, mas de uma forma diferente). Quando a engine do Velocity encontrar a linha que contém $item, essa variável irá ser substituida pelo valor da posição atual da lista. Por final, #end especifica que a instrução #foreach termina naquele ponto. Como você pode ter deduzido, o #foreach percebe que a varável $list é um Collection, e usa o iterator dela para fazer esse loop. O #foreach também trabalha com arrays e enumarations. O velocity tem um alto poder de instrospecção, que será detalhado no próximo tutorial. Como podemos ver, é tudo muito auto-explicativo e simples de escrever, pois não precisamos nos preocupar com tipos de variáveis, por exemplo. Qualquer designer iria perceber o que este código pretendia fazer.
Salve como VelocityListProcess.java. Na página seguinte, vamos ver agora o que faz cada linha de código!
Aqui criamos uma instância da classe VelocityEngine e iniciamos a mesma. Esse é o código básico, sem ele nada funciona. Note que é altamente recomendável chamar ve.init() logo após criar o objeto, pois deixar para criar em outra parte pode resultar em alguns bugs que podem ser meio chatos de descobrir quando se esta começando com Velocity. Após isso,
cria um contexto, o qual é usado para interagir com o arquivo de templates, como por exemplo setando as variáveis e valores usadas no mesmo.
é usado para representar nosso arquivo de templates no código. As linhas:
criam uma nova ArrayList e adicionam 5 itens nela, os quais irão ser mostrados através do template. A chamada a
diz ao Velocity que quando ele encontrar, no arquivo de template, uma variável chamada "$lista" é para usar os métodos e propriedades do objeto "list" (o qual representa nossa ArrayList, internamente). Por fim, as linhas:
simplesmente associam nosso template a um StringWriter, processam o template junto com o contexto e exibem o resultado na tela. Após a execução do programa, o resultado deverá ser esse:
Introdução
Este tutorial esta dividido em 2 partes. A primeira parte irá dar uma introdução sobre o que é e para que serve o Velocity, quais são suas vantagens e mostrará um exemplo de uso. A parte 2 explicará em detalhes a VTL, a linguagem de templates, tanto como exemplos mais complexos.
O Velocity é um "Template-Engine" feito em Java, ele é um conjunto de classes, e não um programa diferente, em outra linguagem. Uma de suas maiores utilidades é no desenvolvimento de aplicações Web, onde o código Java fica totalmente separado do código HTML, tornando assim a aplicação muito mais modularizada e fácil de manter. Apesar do seu maior uso ser nesta área, não esta limitado a apenas isso, muito pelo contrário. O Velocity pode ser usado para quase tudo o que possa ser imaginado em relação a processamento de textos, como por exemplo formatação de mensagens com base em um template, criação de documentos RTF (Rich Text Format), SQL enfim, o que sua mente conseguir imaginar. Outra ampla utilização de templates engines é para gerar XML.
Para o desenvolvimento Web os templates do Velocity implementam a camada View do pattern MVC (Model View Controller), ou seja, a camada visual. Dessa forma, os designers não precisam se preocupar em entender os complicados códigos Java/JSP e os programadores não precisam ficar adaptando loops e variáveis no meio do HTML.
O Velocity é uma ferramenta opensource, produzida por vários programadores ao redor do mundo, e é um subprojeto do projeto Jakarta, da Apache Foundation. Você pode usá-lo comercialmente sem custo algum e, logicamente, tem acesso ao código fonte, sendo inclusive estimulado a ajudar para com o projeto. Apenas por curiosidade, ele foi inspirado no projeto "WebMacro" (http://www.webmacro.org).
Projetado para ser uma ferramenta fácil de usar e que servisse como ferramenta genérica de templates, o Velocity é ideal em qualquer tipo de programa Java que necessite de formatação de dados e apresentação dos mesmos. Algumas das razões para usá-lo são:
Iniciando
Você deve baixar o Velocity aqui: http://jakarta.apache.org/builds/jakarta-velocity/release/v1.3/. Você pode pegar outra versão, se quiser. Mas não pegue as versões "rc" (release candidate).
Depois de descompactar, você vai encontrar dois .jars. Você deve utilizar o que tem -dep do lado, indicando que este jar vem com todos os outros pacotes do jakarta que ele necessita. Coloque este jar em seu classpath, ou lembre-se de onde ele está para referenciá-lo em linha de comando.
Templates
Mas o que é um template? É um arquivo texto, onde você vai dar a "cara" do que você quer como saída.
Em algum momento do seu programa, em java mesmo, você vai pedir para que o template seja processado, e que algumas partes deste template sejam substituídas por alguma outra coisa. Isto é, você da a receita do bolo (template), e depois você utiliza esta receita para montar um bolo um pouco diferente (template + variáveis).
Para escrever o template, além de colocar variáveis, você também terá algumas diretivas (ou comandos, se você prefere). Isto tudo forma uma pequena linguagem que o seu template deverá respeitar.
VTL
No mundo Velocity existe algo chamada VTL, Velocity Template Language (Linguagem de Templates Velocity), que é a forma usada para incorporar conteúdo dinâmico no arquivo de template. Toda diretiva é precedida pelo caracter "#", como por exemplo:
Essa instrução cria uma variáve chamada $site com o conteúdo "GUJ". Nesta primeira parte do tuturial não vamos ver os detalhes da VTL, porém já adiantamos que é bem simples de aprender (são pouquíssimas diretivas) e mais simples ainda de usar. Nosso primeiro programa de exemplo consiste em mostrar o tamanho e os itens de um ArrayList através de um arquivo de template. Por padrão tais arquivo s tem a extensão "vm", mas isso não é obrigatório. Primeiramente vamos criar o arquivo que será usado como template. Não se preocupe em entender tudo agora, vamos explicar o que faz cada parte do código. Crie um arquivo chamado "template1.vm" e digite o seguinte código:
Salve o arquivo. Vamos ver para que serve para coisa. A linha:
irá mostrar o total de itens contidos no ArrayList após ser processada. $lista nesse caso é a nossa variável, e size() - pasmem - é o método size() da classe ArrayList. Se você já juntou as pecinhas deve ter notado que podemos usar qualquer método público dos objetos. Isso é uma excelente coisa! Continuando:
mostra os itens da lista em si. #foreach é a diretiva, $item é a nossa variável de template que representa um item em específico da ArrayList, e $list é a variável que contém os itens da lista (se fosse Java puro, $lista seria uma instância de ArrayList. Bom, de certa maneira $lista é, mas de uma forma diferente). Quando a engine do Velocity encontrar a linha que contém $item, essa variável irá ser substituida pelo valor da posição atual da lista. Por final, #end especifica que a instrução #foreach termina naquele ponto. Como você pode ter deduzido, o #foreach percebe que a varável $list é um Collection, e usa o iterator dela para fazer esse loop. O #foreach também trabalha com arrays e enumarations. O velocity tem um alto poder de instrospecção, que será detalhado no próximo tutorial. Como podemos ver, é tudo muito auto-explicativo e simples de escrever, pois não precisamos nos preocupar com tipos de variáveis, por exemplo. Qualquer designer iria perceber o que este código pretendia fazer.
Juntando o template com a variável
Agora que temos o nosso arquivo de template pronto, vamos fazer o programa que irá ler e processar o mesmo. Abra o seu editor preferido e digite o seguinte código:
Salve como VelocityListProcess.java. Na página seguinte, vamos ver agora o que faz cada linha de código!
Aqui criamos uma instância da classe VelocityEngine e iniciamos a mesma. Esse é o código básico, sem ele nada funciona. Note que é altamente recomendável chamar ve.init() logo após criar o objeto, pois deixar para criar em outra parte pode resultar em alguns bugs que podem ser meio chatos de descobrir quando se esta começando com Velocity. Após isso,
cria um contexto, o qual é usado para interagir com o arquivo de templates, como por exemplo setando as variáveis e valores usadas no mesmo.
é usado para representar nosso arquivo de templates no código. As linhas:
criam uma nova ArrayList e adicionam 5 itens nela, os quais irão ser mostrados através do template. A chamada a
diz ao Velocity que quando ele encontrar, no arquivo de template, uma variável chamada "$lista" é para usar os métodos e propriedades do objeto "list" (o qual representa nossa ArrayList, internamente). Por fim, as linhas:
simplesmente associam nosso template a um StringWriter, processam o template junto com o contexto e exibem o resultado na tela. Após a execução do programa, o resultado deverá ser esse:
Conclusão
O Velocity é uma ferramenta extremamente poderosa, podendo aumentar em muito sua produtividade e tornar o desenvolvimento mais simples. Ele conta com diretivas próprias para o processamento dos dados e manipulação de objetos, os quais veremos na parte 2 deste tutorial, juntamente com a utilização dele com servlets. Caso tenha alguma dúvida, sugestão ou problema basta postar no fórum que teremos o maior prazer em lhe ajudar.
A página oficial do Velocity esta localizada no endereço:
http://jakarta.apache.org/velocity
Abraços e até a próxima.