Introducción a NVelocity - Tutorial de NVelocity

Motor de plantillas para la plataforma .NET, que constituye el port para .NET de Velocity, el motor para plataforma Java.

Introducción

Se usa ampliamente en proyectos ASP.NET;
ASP.NET MVC cuenta con el motor de plantillas Razor integrado;

Muchos desarrolladores eligen NVelocity cuando desean incorporar el patrón MVC a proyectos tradicionales de páginas .aspx.

NVelocity ya no recibe mantenimiento y solo se emplea en proyectos antiguos basados en .NET Framework. En proyectos nuevos, se recomiendan motores modernos como Razor o Handlebars.NET.

Relación entre versiones y .NET Framework

Versión .NET Framework	Versión NVelocity
.NET 4.0	1.0 (última versión oficial)
.NET 2.0	0.5
.NET 1.0	0.48

Velocity es un veterano motor de plantillas para Java, con una sintaxis sencilla que usa # y $ como marcadores de plantilla. NVelocity trasplanta completamente esta sintaxis;

Descarga

Su última actualización oficial fue en 2018 y la versión más reciente es la 1.2.0

Puede descargarlo desde la siguiente dirección

Es un proyecto de código abierto alojado en GitHub castleproject/NVelocity: Castle’s NVelocity

El archivo oficial descargado no contiene una DLL compilada. Puede descargar el código fuente y compilarlo por su cuenta, o agregar directamente el proyecto a la solución de su aplicación.

Abra el archivo sln con Visual Studio

La última versión está desarrollada sobre .NET Core 2.1. Se aconseja actualizar el proyecto a .NET 4.8

Tras compilar, encontrará las DLL en el directorio de salida

Luego solo tiene que integrarlo en otros proyectos web ASP.NET. Añada el archivo NVelocity.dll a su proyecto web.

Integración en el proyecto

Agregue la referencia al ensamblado NVelocity.dll en su proyecto
Ventaja principal: este motor facilita implementar el cambio de múltiples plantillas (cambio de temas) en el sitio web

Cree una carpeta llamada Themes en el directorio raíz del sitio web, que servirá como directorio principal de todas las plantillas
Dentro de Themes cree varias carpetas independientes para cada tema, por ejemplo:

Cree la carpeta Themes en el directorio raíz web como directorio de temas

Directorio de temas

A continuación cree una carpeta default para la plantilla predeterminada
Más adelante podrá añadir otros conjuntos de plantillas como Themes/blue, Themes/dark

Directorio raíz web
└── Themes
    ├── default      # Archivos de la plantilla predeterminada
    ├── dark         # Archivos del tema oscuro
    └── blue         # Archivos del tema azulLenguaje del código: PHP (php)

En tiempo de ejecución se lee el nombre del tema activo desde la configuración y NVelocity carga las plantillas del directorio correspondiente.
Cambiar la plantilla consiste básicamente en modificar la configuración para apuntar a otra carpeta de temas, sin alterar el código de lógica de negocio.
Ideal para proyectos antiguos ASP.NET WebForm (.aspx) que requieren funcionalidad de cambio de apariencia de la interfaz pública.

aspx

Cree una nueva página aspx en el directorio raíz del sitio: Register.aspx, que usaremos como ejemplo de acceso.

Dentro de Themes/default cree un archivo de plantilla register.htm. Este archivo actúa como plantilla NVelocity y contiene código HTML y sintaxis Velocity.

Abra Register.aspx, conserve únicamente la directiva de página y elimine todo el resto del contenido HTML:

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Register.aspx.cs" Inherits="NVelocityStudy.Web.Register" %>Lenguaje del código: HTML, XML (xml)

El archivo aspx ya no se encarga de renderizar la página, solo actúa como punto de entrada del controlador. El código trasero invoca NVelocity para cargar la plantilla register.htm y generar el contenido de salida.

Directorio raíz web
├─ Register.aspx          # Punto de acceso
├─ Register.aspx.cs       # Lógica del código trasero
└─ Themes
    └─ default
        └─ register.htm   # Plantilla NVelocityLenguaje del código: CSS (css)

Luego escriba el código en Register.aspx.cs para indicar que se cargue la plantilla register.htm del tema activo, pasar el modelo de datos y generar finalmente el HTML.

Si desea cambiar de tema, solo debe modificar la ruta del directorio de temas para cargar el archivo register.htm de la carpeta correspondiente.

aspx.cs

Abra el archivo de código trasero Register.aspx.cs. Escriba la lógica de renderizado de NVelocity dentro del método Page_Load, que se ejecutará para procesar la plantilla al cargarse la página.

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)
        {
            // Escriba aquí el código para cargar la plantilla y renderizar la página con NVelocity
        }
    }
}Lenguaje del código: C# (cs)

Añada el siguiente código dentro de Page_Load

protected void Page_Load(object sender, EventArgs e)
{
    //Paso 1: Crear instancia de VelocityEngine
    VelocityEngine ve = new VelocityEngine();

    //Paso 2: Inicializar configuración del motor
    ExtendedProperties pros = new ExtendedProperties();
    pros.AddProperty(RuntimeConstants.RESOURCE_LOADER, "file"); // Cargar plantillas desde archivos
    pros.AddProperty(RuntimeConstants.FILE_RESOURCE_LOADER_PATH, Server.MapPath(@"")); // Directorio raíz de plantillas
    ve.Init(pros); // Inicializar motor con la configuración

    //Paso 3: Leer archivo de plantilla
    Template template = ve.GetTemplate("themes/default/register.htm");

    //Paso 4: Crear contexto y pasar variables a la plantilla
    IContext context = new VelocityContext();
    context.Put("websiteName", "FoxDevelop");
    context.Put("domainName", "foxdevelop.com");

    //Paso 5: Combinar plantilla y datos para renderizar HTML
    StringWriter writer = new StringWriter();
    template.Merge(context, writer); // El resultado renderizado se guarda en writer

    //Paso 6: Enviar contenido al navegador
    Response.Write(writer.ToString().Replace("\r\n", "<br/>"));
}Lenguaje del código: C# (cs)

Este código lee el archivo HTML de plantilla, crea variables y sustituye los marcadores que aparecen en el HTML por sus valores correspondientes.

Instanciar VelocityEngine: Objeto motor independiente, distinto a la llamada estándar global Velocity.Init(). Permite usar múltiples configuraciones separadas.
Inicialización y configuración del motor

RESOURCE_LOADER=file: Especifica que las plantillas se cargan desde archivos locales;
FILE_RESOURCE_LOADER_PATH: Define el directorio raíz donde se buscan las plantillas;
ve.Init(pros): Carga la configuración y finaliza la inicialización.

Cargar plantilla con GetTemplate(): Lee el archivo themes/default/register.htm tomando como base el directorio raíz configurado.
Contexto de datos VelocityContext: Con context.Put(clave, valor) se envían variables C# a la plantilla. Dentro del archivo htm accede a ellas con $websiteName y $domainName.
Renderizado Merge de plantillas: template.Merge(contexto, flujoSalida) inserta las variables en la plantilla y genera una cadena HTML completa. Se usa StringWriter para recibir el texto renderizado.
Salida mediante Response: Envía el HTML final al navegador. Replace("\r\n","<br/>") convierte los saltos de línea del código fuente en etiquetas HTML de salto de línea.

Plantilla htm

Modifique el archivo register.htm dentro del directorio de temas

<!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>
    Sitio web: $websiteName <br />
    Dominio: $domainName
</body>
</html>Lenguaje del código: HTML, XML (xml)

Las dos expresiones con $xxxxxxx son los marcadores de las variables definidas en Page_Load, y serán sustituidos por sus valores durante el renderizado.

Identificador de variable $nombreVariable $websiteName y $domainName corresponden a la sintaxis VTL de NVelocity. Se asignan valores en el código con context.Put("websiteName", "FoxDevelop") y el motor los reemplaza automáticamente al renderizar:

$websiteName → FoxDevelop
$domainName → foxdevelop.com

Resultado de ejecución

Sitio web: FoxDevelop
Dominio: foxdevelop.comLenguaje del código: CSS (css)

Introducción a NVelocity