1. Backslash \ Escape Rules

Pre‑defined variable：#set($dog = "woof woof")

1. Velocity variable names must start with a letter，$10.0 will not be treated as variable and outputs as‑is；so writing Microsoft $10.0 USD in text requires no extra escaping；
2. Consecutive backslashes cancel out in pairs；only the \$ combination can escape dollar‑sign；
3. To display $variableName literally on page, standard syntax：\$dog.

2. #if Branch Conditional Syntax

#set($ages = 22)
#if ($ages <13)
    <h1>You are a child</h1>
#elseif ($ages <18)
    <h1>You are a teenager</h1>
#elseif ($ages <35)
    <h1>You are a young adult</h1>
#elseif ($ages <60)
    <h1>You are middle‑aged</h1>
#else
    <h1>You are elderly</h1>
#end

Execution Result

$ages=22, satisfies 22 < 35 → output：<h1>You are a young adult</h1>

Notes

1. You must close block with #end, missing it will trigger parsing error；
2. Keyword：#elseif（do NOT write as #else if, that is invalid syntax）；
3. Supported operators：< > <= >= == != && || and more；
4. Matching rule: evaluate conditions top‑down. Once one branch matches, subsequent branches are skipped.

Escape characters and #if conditionals

1. Backend Person Entity Code (C#)

public class Person
{
    private string name;
    public string Name
    {
        get { return name; }
        set { name = value; }
    }
    private int age;
    public int Age
    {
        get { return age; }
        set { age = value; }
    }

    //Parameter‑less constructor
    public Person(){}
    //Parameterized constructor
    public Person(string name, int age)
    {
        this.name = name;
        this.age = age;
    }

    //Parameter‑less instance method
    public string getMyName()
    {
        return this.name;
    }

    //Multi‑parameter instance method
    public string JoinStr(string str1, string str2)
    {
        return str1 + str2;
    }
}

Set object variables in C# backend code

Person pTest = new Person("Tom", 22);
context.Put("pTest", pTest);

2. VTL Template Code & Rendering Notes

Method call<br />
$pTest.getMyName();

#set($a = "hello")
#set($b = "foxdevelop")

$pTest.JoinStr($a, $b);

1. $pTest.getMyName()

• Call object parameter‑less method getMyName()
• Return Tom

Velocity parameter‑less method call: parentheses () can be omitted, $pTest.getMyName is equivalent to $pTest.getMyName()

2. $pTest.JoinStr($a, $b)

• Invoke method with two string parameters
• VTL parses $a, $b first, pass actual arguments "hello", "foxdevelop"
• Return concatenated result: hellofoxdevelop

Summary

1. Method name is case‑sensitive
   C# getMyName() ≠ GetMyName(), template must match source code casing.
2. Pass variables directly
   No extra quotes needed, $pTest.JoinStr($a,$b) is correct; do not write $pTest.JoinStr("$a","$b") (will pass literal string “$a”)
3. Difference between properties and methods

• $pTest.Name → access property (getter)
• $pTest.getMyName() → invoke method

1. Return values output automatically
   Directly write $object.method() inside template, Velocity prints return value automatically; use #set to capture result if output is unwanted:

#set($result = $pTest.JoinStr($a,$b))

3. Final Page Render Output

Method call
Tom;

hellofoxdevelop;

Extension methods

Variable preset: #set ($valok = "hello foxdevelop")

Variable Boundary ${} vs . Access Distinction

${valok}.cn Variable plus suffix concatenation
${valok.cn} Access property cn under object valok

Single / Double Quotes & Variable Concatenation

Code	Rendered Output	Explanation
what$valok	whathello foxdevelop	Direct concatenation, Velocity auto‑detects variable boundary
what$"valok"	what$”valok”	Invalid syntax. $ cannot be immediately followed by quote, variable cannot be parsed
what"$valok"	what”hello foxdevelop“	Quotes are plain text inside template, they do not trigger string parsing; variable renders normally
what'$valok'	what’hello foxdevelop‘	Same as above, single quotes are ordinary literal characters
$valokwhat	$valokwhat	Variable unrecognizable! Velocity treats valokwhat as full variable name, prints raw text when not found
${valok}what	hello foxdevelopwhat	Curly braces lock boundary, fixes variable‑text merging issue

Summary

1. Always use ${variableName} when variable merges with adjacent text
   Wrong: $valokwhat；Correct: ${valok}what
2. Append literal suffix: use ${valok}.cn instead of ${valok.cn}
3. $!variable silent reference: outputs blank if variable missing, raw $xxx will not appear
4. Single / double quotes inside template HTML are plain characters；Only inside #set assignments do single quotes (no variable parsing) and double quotes (parse variables) behave differently

#set($a = "$valok") // Double quotes: resolve variable, a=hello bamn
#set($a = '$valok') // Single quotes: skip variable resolution, a=$valok

Supplementary notes on variable boundaries

1. Iterate over String List

C# Back‑end Code

List<string> strList = new List<string>() {"dsd","sdfsd","asdfsd","asdfsdfsd"};
context.Put("strList", strList);

Velocity Template Code

#foreach($str in $strList)
    $str <br/>
#end

Execution result: Loop through each string in the list and output with line breaks.

Syntax Explanation

#foreach(loopVariable in collection) starts the loop, #end closes the loop.

2. Iterate over List of Custom Entity Classes

1. Person Entity (C#)

public class Person
{
    private string name;
    public string Name
    {
        get { return name; }
        set { name = value; }
    }
    private int age;
    public int Age
    {
        get { return age; }
        set { age = value; }
    }
    public Person(){}
    public Person(string name,int age)
    {
        this.name = name;
        this.age = age;
    }
}

2. Back‑end Assemble List

List<Person> pList = new List<Person>();
pList.Add(new Person("Jack", 1));
pList.Add(new Person("Ben", 11));
pList.Add(new Person("Kevin", 100));
pList.Add(new Person("Simon", 500));
pList.Add(new Person("Lulu", 20));
context.Put("pList", pList);

3. Template Property Access Syntax

Template code:

#foreach($per in $pList)
<tr>
    <td>$per.name</td>
    <td>$per.age</td>
</tr>
#end

Cannot read data! Errors or blank output

Underlying Principle

Velocity rules for accessing object properties:
$per.xxx automatically looks for public Get method GetXxx()

• $per.name → Attempts to call per.getName()
• $per.age → Attempts to call per.getAge()

Your entity:

• Private fields: name, age
• Public properties start with uppercase: Name, Age, corresponding methods GetName(), GetAge()

Correct template syntax:

#foreach($per in $pList)
<tr>
    <td>$per.Name</td>
    <td>$per.Age</td>
</tr>
#end

Note: C# convention uses uppercase first‑letter for properties; Java entity properties are usually lowercase. This is a common case‑sensitivity pitfall for beginners.

3. Built‑in Variables for #foreach

Variables available directly inside loops:

Example:

#foreach($per in $pList)
    $foreach.count , Name: $per.Name
#end

4. Render as HTML Table

<table border="0" cellpadding="0" cellspacing="0">
#foreach($per in $pList)
    <tr>
        <td>$per.Name</td>
        <td>$per.Age</td>
    </tr>
#end
</table>

Summary

1. #foreach(variable in collection) + #end is Velocity standard loop syntax;
2. For ordinary List iteration, output $variable directly;
3. Iterate entity objects: $object.propertyName match property case‑sensitivity, never access private fields;
4. C# entities should use uppercase first‑letter for properties, keep consistent naming in templates;
5. When data shows blank, first check property case and existence of get accessor.

Iterate collections

1. Distinction of Template Comments

Development suggestion: Use ## / #* *# for business‑related code comments to avoid leaking comment content in page source.

2. Variable Naming Rules

Official basic naming rules

1. The first character of variable must be an English letter (a‑z / A‑Z)
2. Subsequent allowed characters: letters, digits 0‑9, underscore _, hyphen -

Hyphen - causes operator ambiguity

#set($name-d = "test")

It throws runtime error: Encountered "name" ... Was expecting one of:
Cause: Velocity interprets - as subtraction operator!
Engine parsing logic: $name - d, treated as variable $name minus variable d, leading to syntax conflict.

Two solutions:

1. Recommended: use underscore naming (no ambiguity, common convention)

#set($name_d = "hello world")

2. Use curly braces to define variable boundary (compatible with hyphen‑containing names)

#set(${name-d} = "hello world")
${name-d}

Valid / Invalid Examples Comparison

#  Valid
#set($name_d = "underscore")
#set($name12d = "letter start plus number")
#set(${name-1_2d} = "hyphen requires curly braces")

#  Direct hyphen without curly braces → parse error
#set($name-d = "Error!")
#set($name-1_2d = "Error!")

3. #set Syntax Specification

Standard writing (spaces around brackets are flexible, consistent style is suggested)

#set($variableName = "value")

String values must be wrapped in double quotes; keep spaces around equal sign for better readability.

Comments

1. Core Purpose

The Velocity template engine achieves template reuse via #include / #parse.
Common webpage sections such as page header navigation _head.htm and footer copyright _footer.htm can be extracted into separate sub‑templates and imported in pages, avoiding duplicate HTML code across multiple places.

2. Key Differences Between the Two

1. #include("file path")

Outputs the raw file content as‑is; Velocity variables ($!{xxx}) inside the sub‑template will NOT be parsed

• $!{testinclude} in sub‑templates will not be rendered; the literal string $!{testinclude} gets printed directly
• Supports importing multiple files at once: #include("a.htm","b.htm")
• Best for: static‑only HTML and static snippets without any VTL variables

2. #parse("file path")

Imports the sub‑template and fully interprets Velocity syntax. Variables passed from the parent template render normally inside sub‑templates

• $!{testinclude} inside sub‑templates reads context variables and resolves to values supplied by backend code
• Accepts only one single file path; multiple simultaneous imports are not supported
• Best for: common templates with variables such as headers and footers (page titles, dynamic copyright text, etc.)

From your screenshot notes:
#include simply pastes sub‑template source code into the main template without parsing, while #parse performs full syntax parsing

3. Practical Example

1. Backend code (.cs)

context.Put("testinclude", "Text from sub‑template:");

2. Content of sub‑template _footer.htm

Copyright info $!{testinclude}

Case ① Using #include("./themes/default/_footer.htm")

Page output:

Copyright info $!{testinclude}

The variable stays unparsed; the placeholder is printed literally.

Case ② Using #parse("./themes/default/_footer.htm")

Page output:

Copyright info Text from sub‑template:

Variables render correctly. This explains why #parse is preferred for shared header and footer templates in real‑world projects.

4. Recommended Usage Scenarios

Development guidelines:
Use #parse consistently for shared components likely requiring dynamic variables, such as navigation bars and footer copyright blocks. Use #include for plain static text and style fragments.

Template reuse

1. Defining Variables with #set()

Two ways to declare variables:
Method 1: Define variables in advance via backend C#/Java code, read them in template pages;
Method 2: Define variables directly inside templates with #set() (core content of this lesson)

#set($name = "hello foxdevelop.com")
#set($okay = "common baby")
#set($nameokay = "$name|$okay")

• #set(variable = value) supports strings, numbers, arrays, object properties and assignments from other variables
• Weak‑typed, no need to declare variable types

2. Two Variable‑Rendering Syntax and Specifications

2.1 Basic Forms

• $name: If the variable does not exist, outputs literal text $name
• $!name: Silent rendering; outputs blank content when variable is missing (recommended to avoid stray $xxx text on pages)
• Recommended standard syntax: ${name} (curly braces mark variable boundaries explicitly)

2.2 Boundary Issue Example

#set($name = "hello")
$namehello     × Engine parses variable as $namehello and cannot resolve it
${name}hello   √ Correct: resolves $name then appends plain‑text hello

3. Single‑Line Comments ##

## This is a comment and will never appear in rendered output
#set($name = "test") ## End‑of‑line comments are also supported

1. Comment content will not be printed into the final rendered page;
2. You cannot see comment text when viewing browser page source (comments get discarded during template‑engine processing).

4. Multiple Assignment Types Supported by #set

## String assignment
#set($name = "hello world")

## Assign one variable to another
#set($obj= $name)

## Assign object properties
#set($obj.Friend = "monica")
#set($obj.Blame = $whitehouse.Leak)

## Call methods and assign return values
#set($obj.Plan = $spindoctor.weave($web))

## Numeric assignment
#set($obj.Number = 123)

## Array assignment
#set($obj.Say = ["Not", $my, "fault"])

5. Special Rules for Non‑existent Variables

$sadfsdfsd

When the template engine cannot resolve a variable:

• Ordinary syntax $sadfsdfsd: outputs literal string $sadfsdfsd
• Using $!sadfsdfsd: outputs empty string for missing variables

Define variables inside templates

1.1 PageInfo Entity Class

Previously we passed simple strings, which is inefficient and hard‑to‑maintain. Wrapping data into entity objects makes code much clearer.

public class PageInfo
{
    private bool IsShowImage;
    public bool IsShowImage1
    {
        get { return IsShowImage; }
        set { IsShowImage = value; }
    }
}

• Private field IsShowImage, exposed via public property IsShowImage1
• Template access syntax: $info.IsShowImage1

1.2 Populate Context Data

//Template context container
IContext context = new VelocityContext();

PageInfo pi = new PageInfo();
pi.IsShowImage1 = true;

//Store object pi under key name info into context
context.Put("info",pi);

//String variable sample
context.Put("infotitle","Hello");

context.Put("keyName",data): pass data to template, template reads values by $keyName.

2. Core Velocity Template Syntax

2.1 Directive Marker #

Statements starting with # are directives, common ones:
#if, #else, #end, #foreach, #set, #include

Conditional rendering example:

Prepare two image files and place them under Contents/Images in website root directory. Toggle IsShowImage1 to render different images.

#if($info.IsShowImage1)
    <img src="./Contents/Images/a.gif" />
#else
    <img src="./Contents/Images/b.gif" />
#end

Logic: render a.gif when IsShowImage1=true, otherwise render b.gif

2.2 Variable Marker $

• $variableName: output variable value
• ${variableName}: variable boundary delimiter (critical!)

Scenario: text directly follows variable, engine cannot tell where variable name ends.

Incorrect: $infotitlefoxdevelop.com
Engine parses whole string as variable infotitlefoxdevelop, which does not exist!

Correct: ${infotitle}foxdevelop.com
Engine resolves infotitle variable then concatenate foxdevelop.com string

2.3 Silent‑output Modifier ! → $!variableName

Default: if variable missing, page outputs raw text $variableName
$!variableName: output blank when variable missing or null, do not print dollar sign

Comparison example:

Full test snippet:

${infotitle}foxdevelop.com <br/>
$!infotitlefoxdevelop.com <br/>
$infotitle <br/>
$!infotitle <br/>

Summary

1. Always wrap variable with ${variable} when concatenating text after variable
2. Prefer $!{variableName} in production environment, avoid raw $xxx breaking layout on null variables
3. For boolean property check with #if, write directly #if($info.IsShowImage1), no need extra ==true

Fundamental template syntax

Introduction

Widely adopted within ASP.NET projects;
ASP.NET MVC ships with the Razor template engine;

Many developers turn to NVelocity when they want to introduce the MVC pattern into legacy .aspx web form projects.

NVelocity is no longer actively maintained and should only be used for older .NET Framework legacy projects. New projects are recommended to adopt modern template engines such as Razor and Handlebars.NET.

Version compatibility with .NET Framework

Velocity is a mature Java template engine known for its clean syntax that uses # and $ as template markers. NVelocity fully implements this syntax specification.

Download

The official repository received its last update in 2018, with version 1.2.0 being the newest release.

You can grab the source code via the link below

It is open-source and hosted on GitHub castleproject/NVelocity: Castle’s NVelocity

Official downloads do not include precompiled DLL binaries. You may compile the source yourself after downloading, or directly import the project into your existing solution.

Open the solution file with Visual Studio

The final release targets .NET Core 2.1. Developers are advised to migrate it to .NET 4.8.

After compilation, you can locate the compiled DLL inside the output directory

You can then reference NVelocity.dll within your other ASP.NET Web projects.

Project Integration

Reference the assembly: NVelocity.dll
Core benefit: This template engine greatly simplifies dynamic template switching (theme skinning) for websites.

Create a folder named Themes at your website root as the root directory for all templates
Inside Themes, create separate folders for different themes, for example:

Create the Themes folder at website root to store all theme resources

Theme Directory Structure

Create a folder named default for your base template set.
Additional theme folders such as Themes/blue and Themes/dark can be added later.

Website Root
└── Themes
    ├── default      # Default theme template files
    ├── dark         # Dark theme template files
    └── blue         # Blue theme template files

On runtime, the engine reads the active theme name from configuration and loads templates from the corresponding theme folder.
Template switching simply updates configuration values to point to another theme directory without modifying business logic.
This approach works well for legacy ASP.NET WebForm (.aspx) projects implementing front-end skin switching.

aspx

Create a new .aspx page called Register.aspx in the website root for demonstration purposes.

Create a template file named register.htm under Themes/default. This file serves as the NVelocity template containing HTML markup and Velocity syntax.

Open Register.aspx, keep only the page directive and remove all other HTML markup:

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Register.aspx.cs" Inherits="NVelocityStudy.Web.Register" %>

The .aspx page will no longer handle rendering directly and acts merely as an entry point. Backend code invokes NVelocity to load the register.htm template and output rendered HTML content.

Website Root
├─ Register.aspx          # Access entry point
├─ Register.aspx.cs       # Backend logic
└─ Themes
    └─ default
        └─ register.htm   # NVelocity template file

You will implement logic within Register.aspx.cs to load the register.htm template from the active theme, inject model data and produce final HTML output.

To switch themes, modify the directory path setting so the engine loads register.htm from another theme folder.

aspx.cs

Open the backend file Register.aspx.cs. Implement NVelocity rendering logic inside the Page_Load method to parse templates when the page loads.

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)
        {
            // Implement template loading and rendering logic here
        }
    }
}

Insert the following code inside Page_Load

protected void Page_Load(object sender, EventArgs e)
{
    // Step 1: Instantiate VelocityEngine
    VelocityEngine ve = new VelocityEngine();

    // Step 2: Configure engine settings
    ExtendedProperties pros = new ExtendedProperties();
    pros.AddProperty(RuntimeConstants.RESOURCE_LOADER, "file"); // Load templates from local files
    pros.AddProperty(RuntimeConstants.FILE_RESOURCE_LOADER_PATH, Server.MapPath(@"")); // Template root directory
    ve.Init(pros); // Initialize engine with configuration

    // Step 3: Load template file
    Template template = ve.GetTemplate("themes/default/register.htm");

    // Step 4: Create context and pass variables to template
    IContext context = new VelocityContext();
    context.Put("websiteName", "FoxDevelop");
    context.Put("domainName", "foxdevelop.com");

    // Step 5: Merge template with data and render HTML
    StringWriter writer = new StringWriter();
    template.Merge(context, writer); // Store rendered output

    // Step 6: Send output to browser
    Response.Write(writer.ToString().Replace("\r\n", "<br/>"));
}

This code reads the HTML template file, defines variables and replaces placeholder markers inside the template.

1. Instantiate VelocityEngine Creates an isolated engine instance, unlike the static global Velocity.Init(), allowing separate configurations.
2. Engine initialization and configuration

• RESOURCE_LOADER=file : Specifies local filesystem template loading;
• FILE_RESOURCE_LOADER_PATH : Sets root path for template lookup;
• ve.Init(pros) : Applies settings and completes initialization.

3. Template loading via GetTemplate() Reads themes/default/register.htm relative to the configured root path.
4. VelocityContext data contextcontext.Put(key, value) passes C# variables into templates, accessible in htm files using $websiteName, $domainName.
5. Template Merge renderingtemplate.Merge(context, stream) injects variables into templates to build full HTML strings. StringWriter captures rendered text output.
6. Response output Sends final HTML to browsers; Replace("\r\n","<br/>") converts source line breaks into HTML break tags.

htm Template

Modify the register.htm file within your theme directory

<!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>
    Website：$websiteName <br />
    Domain：$domainName
</body>
</html>

These two $xxxxxxx markers correspond to variables defined in Page_Load and will be substituted with actual values during rendering.

1. Variable syntax $VariableName $websiteName and $domainName follow NVelocity (VTL) variable syntax. Values assigned with context.Put("websiteName", "FoxDevelop") get replaced automatically by the engine:

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

Runtime Output

Website：FoxDevelop
Domain：foxdevelop.com

Introduction to NVelocity