Introduction à Apache Velocity

1. Vue d'ensemble

Velocity est un moteur de création de modèles basé sur Java.

Il s'agit d'un framework Web open source conçu pour être utilisé comme composant de vue dans l'architecture MVC, et il offre une alternative à certaines technologies existantes telles que JSP.

Velocity peut être utilisé pour générer des fichiers XML, SQL, PostScript et la plupart des autres formats textuels.

Dans cet article, nous allons explorer comment il peut être utilisé pour créer des pages Web dynamiques.

2. Fonctionnement de Velocity

La classe principale de Velocity est le VelocityEngine .

Il orchestre l'ensemble du processus de lecture, d'analyse et de génération de contenu à l'aide d'un modèle de données et d'un modèle de vitesse.

En termes simples, voici les étapes à suivre pour toute application de vitesse typique:

  • Initialiser le moteur de vitesse
  • Lire le modèle
  • Mettre le modèle de données dans l'objet de contexte
  • Fusionner le modèle avec les données de contexte et rendre la vue

Passons en revue un exemple en suivant ces étapes 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. Dépendances de Maven

Pour travailler avec Velocity, nous devons ajouter les dépendances suivantes à notre projet Maven:

 org.apache.velocity velocity 1.7   org.apache.velocity velocity-tools 2.0 

La dernière version de ces deux dépendances peut être ici: outils de vitesse et de vitesse.

4. Langage de modèle de vitesse

Le langage de modèle de vitesse (VTL) fournit le moyen le plus simple et le plus propre d'incorporer le contenu dynamique dans une page Web à l'aide de références VTL.

La référence VTL dans le modèle de vitesse commence par un $ et est utilisée pour obtenir la valeur associée à cette référence. VTL fournit également un ensemble de directives qui peuvent être utilisées pour manipuler la sortie du code Java. Ces directives commencent par #.

4.1. Références

Il existe trois types de références dans Velocity, variables, propriétés et méthodes:

  • variables - définies dans la page à l'aide de la directive #set ou de la valeur renvoyée par le champ de l'objet Java:
    #set ($message="Hello World")
  • propriétés - font référence à des champs dans un objet; ils peuvent également faire référence à une méthode getter de la propriété:
    $customer.name
  • méthodes - reportez-vous à la méthode sur l'objet Java:
    $customer.getName()

La valeur finale résultant de chaque référence est convertie en chaîne lorsqu'elle est rendue dans la sortie finale.

4.2. Directives

VTL fournit un riche ensemble de directives:

  • set - il peut être utilisé pour définir la valeur d'une référence; cette valeur peut être affectée à une variable ou à une référence de propriété:
    #set ($message = "Hello World") #set ($customer.name = "Brian Mcdonald")
  • conditionals - Les directives #if, #elseif et #else fournissent un moyen de générer le contenu basé sur des vérifications conditionnelles:
    #if($employee.designation == "Manager") 

    Manager

    #elseif($employee.designation == "Senior Developer")

    Senior Software Engineer

    #else

    Trainee

    #end
  • loops - La directive #foreach permet de boucler sur une collection d'objets:
    
          
      #foreach($product in $productList)
    • $product
    • #end
  • include - L' élément #include offre la possibilité d'importer des fichiers dans le modèle:
    #include("one.gif","two.txt","three.html"...)
  • parse - L' instruction #parse permet au concepteur de modèle d'importer un autre fichier local qui contient VTL; Velocity analysera ensuite le contenu et le rendra:
    #parse (Template)
  • evaluate#evaluate directive can be used to evaluate VTL dynamically; this allows the template to evaluate a String at render time, for example to internationalise the template:
    #set($firstName = "David") #set($lastName = "Johnson") #set($dynamicsource = "$firstName$lastName") #evaluate($dynamicsource)
  • break#break directive stops any further rendering of current execution scope (i.e. #foreach, #parse)
  • stop#stop directive stops any further rendering and execution of the template.
  • velocimacros#macro directive allows the template designer to define a repeated segment of VTL:
    #macro(tablerows)  #end

    This macro now can be put in any place in the template as #tablerows():

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

4.3. Other Features

  • math – a handful built-in mathematical functions, which can be used in templates:
    #set($percent = $number / 100) #set($remainder = $dividend % $divisor)
  • range operator – that can be used in conjunction with #set and #foreach:
    #set($array = [0..10]) #foreach($elem in $arr) $elem #end

5. Velocity Servlet

The primary job of the Velocity Engine is to generate content based on a template.

The Engine doesn't contain any web related functionalities in itself. To implement a web application, we need to use a servlet or servlet-based framework.

Velocity provides one out of the box implementation VelocityViewServlet, which is a part of the velocity-tools subproject.

To make use of the built-in functionality provided by VelocityViewServlet, we can extend our servlet from VelocityViewServlet and override the handleRequest() method:

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. Configuration

6.1. Web Configuration

Let's now see how to configure the VelocityViewServlet in the web.xml.

We need to specify the optional initialization parameters which include velocity.properties and toolbox.xml:

 apache-velocity //...  velocity org.apache.velocity.tools.view.VelocityViewServlet  org.apache.velocity.properties /WEB-INF/velocity.properties   //...  

We also need to specify the mapping for this servlet. All the requests for velocity templates (*.vm) need to be served by the velocity servlet:

 velocityLayout *.vm 

6.2. Resource Loader

Velocity provides flexible resource loader system. It allows one or more resource loader to be in operation at the same time:

  • FileResourceLoader
  • JarResourceLoader
  • ClassPathResourceLoader
  • URLResourceLoader
  • DataSourceResourceLoader
  • WebappResourceLoader

These resource loaders are configured in velocity.properties:

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

7. Velocity Template

Velocity template is the place where all the view generation logic is written. These pages are written using 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()

8. Managing the Page Layout

Velocity provides a simple layout control and customizable error screens for Velocity Tool based application.

VelocityLayoutServlet encapsulates this capability to render the specified layouts. VelocityLayoutServlet is an extension to VelocityViewServlet.

8.1. Web Configuration

Let's see how to configure the VelocityLayoutServlet. The servlet is defined for intercepting the requests for velocity template pages and the layout specific properties are defined in velocity.properties file:

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

8.2. Layout Templates

Layout template defines the typical structure of a velocity page. By default, the VelocityLayoutServlet searches for Default.vm under the layout folder. Overriding few properties can change this location:

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

The layout file consists of header template, footer template, and a velocity variable $screen_content which renders the contents of requested velocity page:

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

8.3. Layout Specification in the Requested Screen

Layout for a particular screen can be defined as a velocity variable at the beginning of a page. That is done by putting this line in the page:

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

8.4. Layout Specification in the Request Parameter

We can add a request parameter in the query string layout=MyOtherLayout.vm and VLS will find it and render the screen within that layout instead of searching for default layout.

8.5. Error Screens

Customized error screen can be implemented using velocity layout. VelocityLayoutServlet provides two variables $error_cause and $stack_trace to present the exception details.

Error page can be configured in velocity.properties file:

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

9. Conclusion

Dans cet article, nous avons appris comment Velocity est un outil utile pour le rendu des pages Web dynamiques. De plus, nous avons vu différentes manières d'utiliser les servlets fournis par vitesse.

Nous avons également un article axé sur une configuration Velocity avec Spring MVC ici à Baeldung.

Le code complet de ce didacticiel est disponible à l'adresse over sur GitHub.