Présentation de NVelocity

Moteur de template pour la plateforme .NET, portage .NET de Velocity initialement conçu pour Java.

Présentation

Il est largement utilisé sur les projets ASP.NET ;
ASP.NET MVC dispose nativement du moteur de template Razor.

Nombreux développeurs ont choisi NVelocity lorsqu’ils souhaitaient intégrer le modèle MVC à des projets reposant sur des pages .aspx traditionnelles.

Le projet NVelocity n’est plus maintenu aujourd’hui. On ne l’utilise que sur d’anciens projets hérités sous .NET Framework. Sur les nouveaux projets, préférez des moteurs modernes comme Razor ou Handlebars.NET.

Correspondance entre versions de .NET Framework et de NVelocity

Version .NET Framework	Version NVelocity
.NET 4.0	1.0 (dernière version officielle)
.NET 2.0	0.5
.NET 1.0	0.48

Velocity est un moteur de template Java historique à la syntaxe épurée, utilisant les symboles # et $ comme marqueurs de template. NVelocity reprend cette syntaxe dans son intégralité.

Téléchargement

La dernière mise à jour officielle date de 2018, la version la plus récente est la 1.2.0.

Vous pouvez récupérer les sources à l’adresse ci-dessous.

C’est un projet open-source hébergé sur GitHub castleproject/NVelocity: Castle’s NVelocity

Les archives officielles ne contiennent pas de DLL compilée. Vous devrez soit compiler le code vous-même après téléchargement, soit intégrer directement le projet dans votre solution.

Ouvrez le fichier sln avec Visual Studio.

La dernière version est basée sur .NET Core 2.1 ; nous vous recommandons de la migrer vers .NET 4.8.

Après compilation, vous trouverez la DLL dans le dossier de sortie.

Vous pouvez ensuite ajouter cette DLL à un autre projet web ASP.NET. Intégrez NVelocity.dll dans votre projet web.

Intégration au projet

Ajoutez une référence à l’assembly : NVelocity.dll
Point fort : ce moteur facilite grandement la mise en place d’un système de changement de thèmes sur un site web.

Créez un dossier Themes à la racine du site, qui contiendra l’ensemble des templates.
À l’intérieur de Themes, créez plusieurs dossiers de thèmes, par exemple :

Nous créons le dossier Themes à la racine du site pour stocker nos thèmes.

Arborescence des thèmes

Créez ensuite un dossier default pour le template par défaut.
Vous pourrez ajouter par la suite d’autres ensembles de templates comme Themes/blue ou Themes/dark.

Racine du site
└── Themes
    ├── default      # Fichiers du thème par défaut
    ├── dark         # Fichiers du thème sombre
    └── blue         # Fichiers du thème bleuLangage du code : PHP (php)

Lors de l’exécution, la configuration indique le thème actif, et NVelocity charge les templates du dossier correspondant.
Changer de thème revient simplement à modifier la configuration pour pointer vers un autre dossier, sans toucher au code métier.
Cette solution convient aux anciens projets ASP.NET WebForm (.aspx) souhaitant proposer un changement d’apparence côté front.

Fichier aspx

Créez une nouvelle page aspx : ajoutez Register.aspx à la racine du site pour servir d’exemple.

Dans le dossier Themes/default, créez le template register.htm. Ce fichier est interprété par NVelocity et contient du HTML associé à la syntaxe Velocity.

Ouvrez Register.aspx et ne conservez que la directive de page ; supprimez tout le reste du code HTML :

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Register.aspx.cs" Inherits="NVelocityStudy.Web.Register" %>Langage du code : HTML, XML (xml)

Le fichier aspx ne s’occupe plus du rendu visuel, il agit uniquement comme point d’entrée du contrôleur. Le code serveur appelle NVelocity pour charger register.htm et produire le contenu final.

Racine du site
├─ Register.aspx          # Point d’accès
├─ Register.aspx.cs       # Logique serveur
└─ Themes
    └─ default
        └─ register.htm   # Template NVelocityLangage du code : CSS (css)

Vous écrirez ensuite le code dans Register.aspx.cs : il chargera le template register.htm du thème actif, transmettra le modèle de données et générera le HTML final.

Pour changer de thème, il suffit de modifier le chemin du dossier cible afin de charger le fichier register.htm du bon thème.

Fichier aspx.cs

Ouvrez le fichier code-behind Register.aspx.cs et implémentez la logique de rendu NVelocity dans la méthode Page_Load. Le parsing du template s’exécutera au chargement de la page.

using System;
using System.Collections.Generic;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;

namespace NVelocityStudy.Web
{
    public partial class Register : System.Web.UI.Page
    {
        protected void Page_Load(object sender, EventArgs e)
        {
            // Code de chargement et rendu du template NVelocity à placer ici
        }
    }
}Langage du code : C# (cs)

Ajoutez le code ci-dessous dans Page_Load.

protected void Page_Load(object sender, EventArgs e)
{
    //Étape 1 : instancier le moteur VelocityEngine
    VelocityEngine ve = new VelocityEngine();

    //Étape 2 : initialiser les paramètres du moteur
    ExtendedProperties pros = new ExtendedProperties();
    pros.AddProperty(RuntimeConstants.RESOURCE_LOADER, "file"); // Chargement des templates depuis des fichiers
    pros.AddProperty(RuntimeConstants.FILE_RESOURCE_LOADER_PATH, Server.MapPath(@"")); // Dossier racine des templates
    ve.Init(pros); // Initialisation du moteur avec ces paramètres

    //Étape 3 : charger le fichier template
    Template template = ve.GetTemplate("themes/default/register.htm");

    //Étape 4 : créer le contexte et transmettre des variables au template
    IContext context = new VelocityContext();
    context.Put("websiteName", "FoxDevelop");
    context.Put("domainName", "foxdevelop.com");

    //Étape 5 : fusionner template et données pour produire du HTML
    StringWriter writer = new StringWriter();
    template.Merge(context, writer); // Le rendu est stocké dans writer

    //Étape 6 : envoyer le contenu au navigateur
    Response.Write(writer.ToString().Replace("\r\n", "<br/>"));
}Langage du code : C# (cs)

Ce code lit le template HTML, crée des variables et remplace les emplacements réservés présents dans le fichier.

1. Instanciation de VelocityEngine : objet moteur indépendant, contrairement à l’appel statique global Velocity.Init(), il permet de gérer plusieurs configurations séparées.
2. Initialisation et paramétrage du moteur

• RESOURCE_LOADER=file : indique que les templates sont chargés depuis des fichiers locaux ;
• FILE_RESOURCE_LOADER_PATH : définit le dossier de base où chercher les templates ;
• ve.Init(pros) : applique la configuration et termine l’initialisation.

3. Chargement du template GetTemplate() : récupère le fichier themes/default/register.htm à partir du chemin racine configuré.
4. Contexte de données VelocityContext : la méthode context.Put(clé, valeur) passe des variables C# au template, que l’on récupère dans le fichier htm avec $websiteName et $domainName.
5. Rendu par fusion Merge : template.Merge(contexte, flux_sortie) insère les valeurs dans le template pour générer une chaîne HTML complète ; StringWriter reçoit le texte final.
6. Sortie via Response : transmettre le HTML final au navigateur ; Replace("\r\n","<br/>") convertit les sauts de ligne du code source en balises HTML de saut de ligne.

Template htm

Modifiez le fichier register.htm situé dans le dossier du thème.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title></title>
</head>
<body>
    Site : $websiteName <br />
    Domaine : $domainName
</body>
</html>Langage du code : HTML, XML (xml)

Les deux chaînes $xxxxxxx sont les emplacements réservés correspondant aux variables créées dans Page_Load, ils seront remplacés par leurs valeurs au moment du rendu.

1. Notation des variables $nom_variable $websiteName et $domainName suivent la syntaxe variable de NVelocity (VTL). Lorsque le code exécute context.Put("websiteName", "FoxDevelop"), le moteur remplace automatiquement la variable au rendu :

• $websiteName → FoxDevelop
• $domainName → foxdevelop.com

Résultat de l’exécution

Site : FoxDevelop
Domaine : foxdevelop.comLangage du code : CSS (css)

Présentation de NVelocity