Introdução ao Apache Velocity

1. Visão geral

Velocity é um mecanismo de modelos baseado em Java.

É uma estrutura da web de código aberto projetada para ser usada como um componente de visualização na arquitetura MVC e fornece uma alternativa para algumas tecnologias existentes, como JSP.

O Velocity pode ser usado para gerar arquivos XML, SQL, PostScript e a maioria dos outros formatos baseados em texto.

Neste artigo, exploraremos como ele pode ser usado para criar páginas da web dinâmicas.

2. Como funciona a velocidade

A classe principal de velocidade é oVelocityEngine.

Ele orquestra todo o processo de leitura, análise e geração de conteúdo usando o modelo de dados e o modelo de velocidade.

Simplificando, aqui estão os passos que precisamos seguir para qualquer aplicação típica de velocidade:

Inicialize o mecanismo de velocidade
Leia o modelo
Coloque o modelo de dados no objeto de contexto
Mesclar o modelo com dados de contexto e renderizar a visualização

Let’s go through an example seguindo estas etapas simples:

VelocityEngine velocityEngine = new VelocityEngine();
velocityEngine.init();

Template t = velocityEngine.getTemplate("index.vm");

VelocityContext context = new VelocityContext();
context.put("name", "World");

StringWriter writer = new StringWriter();
t.merge( context, writer );

3. Dependências do Maven

Para trabalhar com o Velocity, precisamos adicionar as seguintes dependências ao nosso projeto Maven:


    org.apache.velocity
    velocity
    1.7
    

     org.apache.velocity
     velocity-tools
     2.0

A versão mais recente de ambas as dependências pode estar aqui:velocityevelocity-tools.

4. Linguagem do modelo de velocidade

A Velocity Template Language (VTL) fornece a maneira mais simples e limpa de incorporar o conteúdo dinâmico em uma página da Web usando referências VTL.

A referência VTL no modelo de velocidade começa com$e é usada para obter o valor associado a essa referência. O VTL também fornece um conjunto de diretivas que podem ser usadas para manipular a saída do código Java. Essas diretivas começam com#.

4.1. Referências

Existem três tipos de referências no Velocity, variáveis, propriedades e métodos:

variables - definido na página usando a diretiva#set ou valor retornado do campo do objeto Java:
```
#set ($message="Hello World")
```
properties - refere-se a campos dentro de um objeto; eles também podem se referir a um métodogetter da propriedade:
```
$customer.name
```
methods - refere-se ao método no objeto Java:
```
$customer.getName()
```

O valor final resultante de cada referência é convertido em uma sequência quando é renderizado na saída final.

4.2. Diretivas

A VTL fornece um rico conjunto de diretivas:

set - pode ser usado para definir o valor de uma referência; este valor pode ser atribuído a uma variável ou referência de propriedade:
```
#set ($message = "Hello World")
#set ($customer.name = "Brian Mcdonald")
```

As diretivasconditionals -#if, #elseife#else fornecem uma maneira de gerar o conteúdo com base em verificações condicionais:

#if($employee.designation == "Manager")
     Manager 
#elseif($employee.designation == "Senior Developer")
     Senior Software Engineer 
#else
     Trainee 
#end

A diretivaloops -#foreach permite o loop em uma coleção de objetos:


    #foreach($product in $productList)
         $product 
    #end

O elementoinclude -#include fornece a capacidade de importar arquivos para o modelo:
```
#include("one.gif","two.txt","three.html"...)
```
A instruçãoparse -#parse permite que o designer de modelo importe outro arquivo local que contenha VTL; O Velocity analisará o conteúdo e o renderizará:
```
#parse (Template)
```
A diretivaevaluate -#evaluate pode ser usada para avaliar VTL dinamicamente; isso permite que o modelo avalie umString no momento da renderização, por exemplo, para internacionalizar o modelo:
```
#set($firstName = "David")
#set($lastName = "Johnson")

#set($dynamicsource = "$firstName$lastName")

#evaluate($dynamicsource)
```
A diretivabreak -#break interrompe qualquer renderização adicional do escopo de execução atual (ou seja, #foreach,#parse)
A diretivastop -#stop interrompe qualquer renderização e execução adicionais do modelo.

A diretivavelocimacros -#macro permite que o designer de modelo defina um segmento repetido de VTL:

#macro(tablerows)
    
        
        
    
#end

Esta macro agora pode ser colocada em qualquer lugar no modelo como #tablerows():

#macro(tablerows $color $productList)
    #foreach($product in $productList)
        
            $product.name
        
    #end
#end

4.3. Outras características

math - um punhado de funções matemáticas integradas, que podem ser usadas em modelos:
```
#set($percent = $number / 100)
#set($remainder = $dividend % $divisor)
```
range operator - que pode ser usado em conjunto com#sete#foreach:
```
#set($array = [0..10])

#foreach($elem in $arr)
    $elem
#end
```

5. Velocity Servlet

A principal tarefa do Velocity Engine é gerar conteúdo com base em um modelo.

O mecanismo não contém nenhuma funcionalidade relacionada à web em si. Para implementar um aplicativo da web, precisamos usar um servlet ou estrutura baseada em servlet.

O Velocity fornece umVelocityViewServlet de implementação pronto para uso, que faz parte do subprojeto de ferramentas de velocidade.

Para usar a funcionalidade integrada fornecida porVelocityViewServlet,, podemos estender nosso servlet deVelocityViewServlete substituir o métodohandleRequest():

public class ProductServlet extends VelocityViewServlet {

    ProductService service = new ProductService();

    @Override
    public Template handleRequest(
      HttpServletRequest request,
      HttpServletResponse response,
      Context context) throws Exception {

        List products = service.getProducts();
        context.put("products", products);

        return getTemplate("index.vm");
    }
}

6. Configuração

6.1. Configuração da Web

Agora vamos ver como configurarVelocityViewServlet emweb.xml.

Precisamos especificar os parâmetros de inicialização opcionais que incluemvelocity.propertiesetoolbox.xml:


    apache-velocity
      //...

    
        velocity
        org.apache.velocity.tools.view.VelocityViewServlet

        
            org.apache.velocity.properties
            /WEB-INF/velocity.properties
        
    
        //...

Também precisamos especificar o mapeamento para este servlet. Todas as solicitações de modelos de velocidade (*.vm) precisam ser atendidas pelo servlet de velocidade:


    velocityLayout
    *.vm

6.2. Resource Loader

O Velocity fornece um sistema flexível de carregador de recursos. Ele permite que um ou mais carregadores de recursos estejam em operação ao mesmo tempo:

FileResourceLoader
JarResourceLoader
ClassPathResourceLoader
URLResourceLoader
DataSourceResourceLoader
WebappResourceLoader

Esses carregadores de recursos são configurados emvelocity.properties:

resource.loader=webapp
webapp.resource.loader.class=org.apache.velocity.tools.view.WebappResourceLoader
webapp.resource.loader.path =
webapp.resource.loader.cache = true

7. Modelo de velocidade

O modelo de velocidade é o local em que toda a lógica de geração de visualizações é gravada. Estas páginas foram escritas usando a Velocity Template Language (VTL):


    ...
    
        
        ...
        $products.size() Products on Sale!
        

            We are proud to offer these fine products
            at these amazing prices.
        ...
        #set( $count = 1 )
        
            #foreach( $product in $products )
            
            #set( $count = $count + 1 )
            #end
        
            
                Serial #
                Product Name
                Price
            

                $count)
                $product.getName()
                $product.getPrice()

Serial #	Product Name	Price
$count)	$product.getName()	$product.getPrice()

8. Gerenciando o Layout da Página

O Velocity fornece um controle de layout simples e telas de erro personalizáveis para aplicativos baseados no Velocity Tool.

VelocityLayoutServlet encapsula esse recurso para renderizar os layouts especificados. VelocityLayoutServlet é uma extensão paraVelocityViewServlet.

8.1. Configuração da Web

Vamos ver como configurar oVelocityLayoutServlet. O servlet é definido para interceptar as solicitações de páginas de modelo de velocidade e as propriedades específicas do layout são definidas no arquivovelocity.properties:


    // ...
    
        velocityLayout
        org.apache.velocity.tools.view.VelocityLayoutServlet

        
            org.apache.velocity.properties
            /WEB-INF/velocity.properties
        
    
    // ...
    
        velocityLayout
        *.vm
    
    // ...

8.2. Modelos de Layout

O modelo de layout define a estrutura típica de uma página de velocidade. Por padrão,VelocityLayoutServlet procuraDefault.vm na pasta de layout. A substituição de poucas propriedades pode alterar este local:

tools.view.servlet.layout.directory = layout/
tools.view.servlet.layout.default.template = Default.vm

O arquivo de layout consiste em um modelo de cabeçalho, um modelo de rodapé e uma variável de velocidade$screen_content que processa o conteúdo da página de velocidade solicitada:


    
        Velocity
    
    
        
            #parse("/fragments/header.vm")
        
        
            
            $screen_content
        
        
            #parse("/fragments/footer.vm")

8.3. Especificação de layout na tela solicitada

O layout de uma tela específica pode ser definido como uma variável de velocidade no início de uma página. Isso é feito colocando esta linha na página:

#set($layout = "MyOtherLayout.vm")

8.4. Especificação de layout no parâmetro de solicitação

Podemos adicionar um parâmetro de solicitação na string de consultalayout=MyOtherLayout.vme o VLS o encontrará e renderizará a tela dentro desse layout, em vez de pesquisar o layout padrão.

8.5. Telas de erro

A tela de erro personalizada pode ser implementada usando o layout de velocidade. VelocityLayoutServlet fornece duas variáveis$error_causee$stack_trace para apresentar os detalhes da exceção.

A página de erro pode ser configurada no arquivovelocity.properties:

tools.view.servlet.error.template = Error.vm

9. Conclusão

Neste artigo, aprendemos como o Velocity é uma ferramenta útil para renderizar as páginas dinâmicas da web. Além disso, vimos diferentes maneiras de usar servlets fornecidos pela velocidade.

Também temos um artigo focado em uma configuração de velocidade com Spring MVChere at example.

O código completo para este tutorial está disponívelover on GitHub.

TOC

Introdução ao Apache Velocity