Описание NVelocity - Учебное пособие NVelocity

Движок шаблонов для платформы .NET, портированная версия Java-движка Velocity.

Обзор

Широко используется в проектах ASP.NET;
Для ASP.NET MVC предусмотрен собственный шаблонизатор Razor;

Многие разработчики выбирали NVelocity, когда нужно было добавить архитектуру MVC в старые проекты на страницах .aspx.

Разработка NVelocity давно прекращена, он подходит только для устаревших проектов на .NET Framework. В новых проектах лучше использовать современные движки шаблонов: Razor, Handlebars.NET и другие.

Соответствие версий и платформы .NET Framework

Версия .NET Framework	Версия NVelocity
.NET 4.0	1.0 (последняя официальная версия)
.NET 2.0	0.5
.NET 1.0	0.48

Velocity — старый проверенный шаблонизатор для Java с лаконичным синтаксисом, для разметки используются символы # и $. NVelocity полностью переносит этот синтаксис на .NET;

Загрузка

Последнее официальное обновление состоялось в 2018 году, актуальная версия — 1.2.0

Скачать исходные файлы можно по ссылке ниже

Проект распространяется с открытым исходным кодом, репозиторий размещён на GitHub castleproject/NVelocity: Castle’s NVelocity

В официальном архиве нет готовых скомпилированных dll-файлов. Вы можете собрать библиотеку самостоятельно или сразу добавить проект в существующее решение.

Откройте файл sln в Visual Studio

Последняя сборка написана под .NET Core 2.1, рекомендуется обновить её до .NET 4.8

После компиляции готовые dll появятся в целевой папке

Затем подключите полученный файл NVelocity.dll к вашему ASP.NET Web-проекту.

Интеграция в проект

Добавьте ссылку на сборку NVelocity.dll в проект
Основное преимущество: движок позволяет очень удобно реализовать смену шаблонов (скинов) на сайте

Создайте в корне сайта папку Themes — она будет хранить все наборы шаблонов.
Внутри Themes создайте отдельные директории для разных тем, например:

Создаём каталог Themes в корневой директории сайта для хранения тем оформления

Структура каталога тем

Создайте папку default для стандартного шаблона.
Позже можно добавить другие наборы: Themes/blue, Themes/dark и т.д.

Корень сайта
└── Themes
    ├── default      # Файлы стандартной темы
    ├── dark         # Файлы тёмной темы
    └── blue         # Файлы синей темыCode language: PHP (php)

При запуске приложение читает имя активной темы из настроек, после чего NVelocity загружает шаблоны из соответствующей папки.
Смена темы сводится к изменению параметра конфигурации — править бизнес-логику не нужно.
Отличное решение для реализации смены оформления в старых проектах ASP.NET WebForm (.aspx).

aspx

Создайте новую страницу aspx Register.aspx в корне сайта для демонстрации работы.

В каталоге Themes/default создайте шаблон register.htm. Это файл NVelocity, где размещается HTML-код и синтаксис VTL.

Откройте Register.aspx и оставьте только директиву страницы, удалите весь остальной HTML:

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

Страница aspx больше не занимается рендерингом контента, она выступает лишь точкой входа контроллера. Код бэкенда обращается к NVelocity, загружает шаблон register.htm и выводит готовый результат.

Корень сайта
├─ Register.aspx          # Точка входа для запросов
├─ Register.aspx.cs       # Логика серверной части
└─ Themes
    └─ default
        └─ register.htm   # Шаблон NVelocityCode language: CSS (css)

Далее в файле Register.aspx.cs пропишите код, который загружает шаблон register.htm из активной темы, передаёт модель данных и генерирует финальный HTML.

Чтобы переключить тему, достаточно изменить путь к каталогу тем, движок подгрузит файл register.htm из нужной директории.

aspx.cs

Откройте серверный код Register.aspx.cs. Логика рендеринга NVelocity размещается в методе Page_Load, она выполняется при открытии страницы.

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)
        {
            // Здесь размещаем код загрузки шаблона и рендеринга через NVelocity
        }
    }
}Code language: C# (cs)

Добавьте такой код в Page_Load

protected void Page_Load(object sender, EventArgs e)
{
    //Шаг 1 Создаём экземпляр движка VelocityEngine
    VelocityEngine ve = new VelocityEngine();

    //Шаг 2 Настраиваем параметры движка
    ExtendedProperties pros = new ExtendedProperties();
    pros.AddProperty(RuntimeConstants.RESOURCE_LOADER, "file"); // Загрузка шаблонов из файлов
    pros.AddProperty(RuntimeConstants.FILE_RESOURCE_LOADER_PATH, Server.MapPath(@"")); // Корневой каталог шаблонов
    ve.Init(pros); // Инициализация с заданными параметрами

    //Шаг 3 Загружаем файл шаблона
    Template template = ve.GetTemplate("themes/default/register.htm");

    //Шаг 4 Создаём контекст, передаём переменные в шаблон
    IContext context = new VelocityContext();
    context.Put("websiteName", "FoxDevelop");
    context.Put("domainName", "foxdevelop.com");

    //Шаг 5 Объединяем шаблон и данные, формируем HTML
    StringWriter writer = new StringWriter();
    template.Merge(context, writer); // Результат рендеринга сохраняем в writer

    //Шаг 6 Вывод контента на страницу
    Response.Write(writer.ToString().Replace("\r\n", "<br/>"));
}Code language: C# (cs)

Этот код загружает html-шаблон, инициализирует переменные для замены плейсхолдеров внутри разметки.

Создание VelocityEngine: отдельный экземпляр движка, в отличие от глобального статического Velocity.Init() поддерживает независимые наборы настроек.
Инициализация и конфигурация движка

RESOURCE_LOADER=file: указывает, что шаблоны загружаются с локального диска;
FILE_RESOURCE_LOADER_PATH: задаёт корневой путь для поиска шаблонов;
ve.Init(pros): применяет параметры и запускает движок.

Загрузка шаблона через GetTemplate(): по заданному корневому пути считывается файл themes/default/register.htm.
Контекст VelocityContext. Метод context.Put(ключ, значение) передаёт переменные C# в шаблон, в htm-файле к ним обращаются через $websiteName, $domainName.
Рендеринг через Merge. template.Merge(контекст, поток) подставляет значения переменных в шаблон и создаёт готовую строку HTML. Для приёма текста используется StringWriter.
Вывод через Response: финальный HTML отправляется в браузер. Replace("\r\n","<br/>") преобразует переводы строк исходного кода в HTML-тег переноса строки.

htm-шаблон

Отредактируйте файл register.htm в каталоге выбранной темы

<!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>
    Сайт: $websiteName <br />
    Домен: $domainName
</body>
</html>Code language: HTML, XML (xml)

Конструкции вида $xxxxxxx — это плейсхолдеры переменных, созданных в Page_Load. Во время рендеринга они заменяются соответствующими значениями.

Обозначение переменных $имяПеременной. $websiteName, $domainName — синтаксис VTL движка NVelocity. Значения задаются кодом context.Put("websiteName", "FoxDevelop"), движок автоматически подставляет их при обработке шаблона:

$websiteName → FoxDevelop
$domainName → foxdevelop.com

Результат выполнения

Сайт: FoxDevelop
Домен: foxdevelop.comCode language: HTTP (http)

Описание NVelocity