1. バックスラッシュ \ エスケープルール

事前定義変数：#set($dog = "woof woof")

1. Velocityの変数名は文字から始める必要があり、$10.0は変数と認識されずそのまま出力。マイクロソフト$10.0ドルのような記述にはエスケープ不要；
2. 連続するバックスラッシュは2つごとに相殺；\$の組み合わせだけがドル記号をエスケープ可能；
3. ページ上に$変数名をそのまま表示するには標準で\$dogを使う。

2. #if による条件分岐構文

#set($ages = 22)
#if ($ages <13)
    <h1>あなたは子供です</h1>
#elseif ($ages <18)
    <h1>あなたは少年です</h1>
#elseif ($ages <35)
    <h1>あなたは青年です</h1>
#elseif ($ages <60)
    <h1>あなたは中年です</h1>
#else
    <h1>あなたは高齢者です</h1>
#end

実行結果

$ages=22、条件 22 < 35 に該当 → 出力：<h1>あなたは青年です</h1>

注意点

1. ブロック終端には必ず#endを記述。省略すると構文エラー；
2. キーワード：#elseif（#else if と空白を入れてはいけません、これは不正な書き方）；
3. 条件で利用可能：< > <= >= == != && || などの演算子；
4. 上から順に判定し、最初に条件成立した分岐だけ実行、以降の分岐は実行されない。

エスケープとif条件

一、バックエンド Personエンティティコード（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;
    }

    //引数なしインスタンスメソッド
    public string getMyName()
    {
        return this.name;
    }

    //複数引数を持つインスタンスメソッド
    public string JoinStr(string str1, string str2)
    {
        return str1 + str2;
    }
}

C#バックエンドコードでオブジェクト変数を設定

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

二、VTLテンプレートコード & レンダリング解説

メソッド呼び出し<br />
$pTest.getMyName();

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

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

1. $pTest.getMyName()

• オブジェクトの引数なしメソッド getMyName()を呼び出す
• 戻り値：Tom

Velocity 引数なしメソッド呼び出し：丸括弧()は省略可、$pTest.getMyName は $pTest.getMyName()と同等

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

• 文字列引数を2つ受け取るメソッドを実行
• VTLが先に$a、$bを解釈し、実引数"hello"、"foxdevelop"を渡す
• 連結結果を返却：hellofoxdevelop

まとめ

1. メソッド名は大文字小文字を区別
   C# getMyName() ≠ GetMyName()、テンプレートはコードの記述と完全に一致させる必要があります。
2. 引数には変数をそのまま記述
   クォートは不要、$pTest.JoinStr($a,$b)が正しい。$pTest.JoinStr("$a","$b")と書かないでください（文字列”$a”が渡されてしまいます）
3. プロパティとメソッドの違い

• $pTest.Name → プロパティアクセス（getter）
• $pTest.getMyName() → メソッド呼び出し

1. 戻り値は自動出力される
   テンプレート上で$オブジェクト.メソッド()と記述するとVelocityが戻り値を自動出力。出力不要な場合は#setで結果を受け取ります：

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

三、最終ページ出力結果

メソッド呼び出し
Tom;

hellofoxdevelop;

拡張メソッド

変数事前定義：#set ($valok = "hello foxdevelop")

変数の境界 ${} と . によるアクセスの違い

${valok}.cn 変数＋接尾辞の連結
${valok.cn} valokオブジェクト配下のcnプロパティにアクセス

シングルクォート / ダブルクォート & 変数の結合

コード	描画結果	仕様解説
what$valok	whathello foxdevelop	直接連結、Velocityが自動で変数の境界を判定
what$"valok"	what$”valok”	構文エラー。$直後にクォートを置けず変数を解析できません
what"$valok"	what”hello foxdevelop“	クォートは単なる文字、テンプレート内では文字列構文として扱われず変数は正常に展開されます
what'$valok'	what’hello foxdevelop‘	上記と同様、シングルクォートも普通の文字です
$valokwhat	$valokwhat	変数認識失敗！Velocityはvalokwhat全体を変数名とみなし、存在しなければ元のテキストを出力
${valok}what	hello foxdevelopwhat	波括弧で境界を固定、変数と文字が繋がる問題を解決

まとめ

1. 変数が他の文字と続く場合は必ず ${変数名} を使う
   誤り：$valokwhat；正しい：${valok}what
2. 接尾文字列を付けるとき：${valok}.cn、${valok.cn}と書かない
3. $!変数 サイレント参照：変数が無いときは空文字を出力、$xxxが表示されません
4. テンプレートHTML内の引用符は通常の文字；#set代入文の内部だけシングルクォート（変数展開しない）とダブルクォート（変数展開する）の挙動が異なります

#set($a = "$valok") // ダブルクォート：変数展開、a=hello bamn
#set($a = '$valok') // シングルクォート：変数展開しない、a=$valok

変数境界に関する補足

1. 文字列Listを走査する

C#バックエンドコード

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

Velocityテンプレートコード

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

実行結果：リストの各文字列をループで取り出し、改行して出力します。

構文解説

#foreach(ループ変数 in コレクション) でループ開始、#end でループを閉じます。

2. 独自エンティティクラスのListを走査

1. Personエンティティ（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. バックエンドで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.テンプレートでプロパティにアクセスする書き方

テンプレートコード：

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

データが取得できません！エラーまたは空出力になります

根本的な仕組み

Velocityのオブジェクトプロパティアクセスルール：
$per.xxx は自動的に 公開Getメソッド GetXxx() を探します

• $per.name → per.getName()を呼び出そうとします
• $per.age → per.getAge()を呼び出そうとします

作成したエンティティ：

• プライベートフィールド：name、age
• 公開プロパティは先頭大文字：Name、Age、対応メソッド GetName()、GetAge()

正しいテンプレート記述：

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

補足：C#ではプロパティの先頭文字を大文字にする慣習、Javaのエンティティプロパティは小文字が一般的です。初心者がハマりやすい大文字小文字の落とし穴です。

3. #foreach組み込み変数

ループ内で直接利用可能な変数です：

サンプル：

#foreach($per in $pList)
    $foreach.count 、氏名：$per.Name
#end

4. テーブル表示

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

まとめ

1. #foreach(変数 in コレクション) + #end がVelocity標準ループ構文；
2. 通常のList走査時は$変数をそのまま出力；
3. エンティティオブジェクト走査：$オブジェクト.プロパティ名 大文字小文字を一致させ、プライベートフィールドにアクセスしない；
4. C#エンティティのプロパティは先頭大文字に統一し、テンプレート側も合わせる；
5. データが空の場合、まずプロパティの大文字小文字、getアクセサの存在を確認してください。

コレクション走査

1. テンプレートコメントの違い

開発のヒント：業務向けコードコメントは##または#* *#を優先して使い、ソースコードへのコメント漏洩を防ぎます。

2. 変数の命名ルール

公式の基本ルール

1. 変数の先頭文字はアルファベット（a‑z / A‑Z）必須
2. それ以降に使用可：英字、数字0‑9、アンダーバー_、ハイフン-

ハイフン - による演算子の曖昧さ

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

実行時にエラーが発生：Encountered "name" ... Was expecting one of:
原因：Velocityが - を減算演算子と判断するため！
エンジンは$name - dと解釈し、変数$nameから変数dを引く処理とみなし構文エラーになります。

二つの解決方法：

1. 推奨：アンダーバーによる命名（曖昧なし、一般的な慣習）

#set($name_d = "hello world")

2. 波括弧で変数範囲を明示（ハイフン付き変数名に対応）

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

有効・無効な記述例

# 正常
#set($name_d = "アンダーバー")
#set($name12d = "英字始まり＋数字")
#set(${name-1_2d} = "ハイフン使用時は波括弧必須")

# 波括弧なしでハイフン → 解析エラー
#set($name-d = "エラー発生！")
#set($name-1_2d = "エラー発生！")

3. #set 構文の記述ルール

標準的な書き方（括弧周囲の空白は柔軟、統一したスタイル推奨）

#set($変数名 = "値")

文字列は二重引用符で囲む必要があります。イコールの両側に空白を入れると可読性が向上します。

コメント

1. 主な役割

Velocityテンプレートエンジンは #include / #parse によってテンプレートの再利用を実現します。
ページヘッダーナビゲーション_head.htm、フッターコピーライト_footer.htmといった共通部分を別サブテンプレートに切り出し、各ページから読み込むことでHTMLの重複記述を回避できます。

2. 二つの命令の本質的な違い

1. #include("ファイルパス")

ファイルの内容をそのまま出力するだけ。サブテンプレート内のVelocity変数（$!{xxx}）は解釈されません

• サブテンプレート内の $!{testinclude} はレンダリングされず、文字列そのまま出力されます$!{testinclude}
• 複数ファイルをまとめて読み込み可能：#include("a.htm","b.htm")
• 向いている用途：変数を含まない静的HTML、静的コード断片

2. #parse("ファイルパス")

サブテンプレートを読み込み、Velocity文法を完全に解釈実行します。親テンプレートから渡した変数がサブテンプレート内で利用できます。

• サブテンプレートの $!{testinclude} はコンテキスト変数を参照し、バックエンドから渡された値に置き換わります
• 読み込めるファイルは1つだけ、複数同時読み込みには対応していません
• 向いている用途：ヘッダー・フッターなど変数を使用する共通テンプレート（ページタイトル、動的コピーライトなど）

手元メモより：
#includeはサブテンプレートのコードを単純に埋め込むだけで解析しない。#parseは文法解析を実行する

3. 実演サンプル

1. バックエンドコード（.cs）

context.Put("testinclude", "サブテンプレートの文字列：");

2. サブテンプレート _footer.htm の内容

コピーライト $!{testinclude}

ケース① #include("./themes/default/_footer.htm")を使用

ページ出力結果：

コピーライト $!{testinclude}

変数が解釈されず、プレースホルダーがそのまま表示されます。

ケース② #parse("./themes/default/_footer.htm")を使用

ページ出力結果：

コピーライト サブテンプレートの文字列：

変数が正しく展開されます。プロジェクトでヘッダー・フッターに#parseを優先する理由がここにあります。

4. 利用シナリオ推奨

開発ルール：
動的変数が使われる可能性のあるナビゲーションやフッターには#parseを統一利用。完全静的なテキスト・スタイル断片には#includeを使います。

テンプレート再利用

1. 変数定義 #set()

変数定義は2通りあります：
方法1：バックエンドのC#/Javaコードで事前定義し、テンプレート側で読み込む；
方法2：テンプレート内で直接 #set() を使い変数を定義（今回の講義のポイント）

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

• #set(変数 = 値)：文字列、数値、配列、オブジェクトプロパティ、他変数からの代入に対応
• 弱い型付け。型宣言は不要

2. 変数出力の記法とルール

2.1 基本書式

• $name：変数が存在しない場合、$name をそのまま出力
• $!name：サイレント出力。変数が無ければ空文字を出力。画面に $xxx が出るのを防ぐため推奨
• 推奨記法：${name}（波括弧で変数範囲を明確に）

2.2 境界に関する注意例

#set($name = "hello")
$namehello     × $namehello という変数として解釈され見つからない
${name}hello   √ $name を展開した後 hello を連結、正しく動作

3. 1行コメント ##

## ここはコメント。最終的な画面に出力されない
#set($name = "test") ## 行末にコメントを書くことも可能

1. コメント内容はレンダリング結果に出力されません；
2. ブラウザでページソースを表示してもコメントは見えません（テンプレートエンジン側で破棄される）。

4. #set で利用できる代入の種類

## 文字列代入
#set($name = "hello world")

## 変数を別変数へ代入
#set($obj= $name)

## オブジェクトプロパティへ代入
#set($obj.Friend = "monica")
#set($obj.Blame = $whitehouse.Leak)

## メソッド呼び出し戻り値を代入
#set($obj.Plan = $spindoctor.weave($web))

## 数値代入
#set($obj.Number = 123)

## 配列代入
#set($obj.Say = ["Not", $my, "fault"])

5. 変数が存在しない場合の特殊仕様

$sadfsdfsd

テンプレートエンジンが変数を解決できないとき：

• 通常記法 $sadfsdfsd：そのまま文字列 $sadfsdfsd を出力
• $!sadfsdfsd の場合：変数無しなら空文字を出力

テンプレート内で変数を設定する

1. PageInfoエンティティクラス

これまでは単純な文字列だけ渡していましたが、効率が悪く保守も大変です。エンティティクラスにデータをまとめることでコードが読みやすくなります。

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

• プライベートフィールドIsShowImage、公開プロパティIsShowImage1で外部へ公開
• テンプレートからのアクセス：$info.IsShowImage1

2. コンテキストへデータをセット

//テンプレートコンテキストコンテナ
IContext context = new VelocityContext();

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

//オブジェクトpiをキー名infoでコンテキストに格納
context.Put("info",pi);

//文字列変数の例
context.Put("infotitle","こんにちは");

context.Put("キー名",データ)：テンプレートへデータを渡し、テンプレート側は$キー名で取得します。

二、Velocityテンプレートの基本構文

1. ディレクティブ記号 #

#から始まる記述がディレクティブです。よく使うもの：
#if、#else、#end、#foreach、#set、#include

条件分岐の例：

2枚の画像を用意し、サイトルート配下のContents/Imagesへ配置します。IsShowImage1の値を切り替えて表示画像を変更します。

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

ロジック：IsShowImage1=trueのときa.gifを表示、それ以外はb.gifを表示

2. 変数記号 $

• $変数名：変数の値を出力
• ${変数名}：変数範囲の明示（重要！）

利用シーン：変数直後に文字が続く場合、エンジンが変数名の区切りを判別できなくなる

誤った書き方：$infotitlefoxdevelop.com
エンジンは変数名を infotitlefoxdevelop と認識し存在しない扱いになります。

正しい書き方：${infotitle}foxdevelop.com
infotitleを変数として解釈し、後ろにfoxdevelop.comの文字列を連結

3. サイレント出力修飾子 ! → $!変数名

既定動作：変数が存在しない場合、ページに$変数名がそのまま出力されます
$!変数名：変数が無い、またはnullのとき何も出力せず、$記号も表示しません

比較例：

完全なテストコード：

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

まとめ

1. 変数の後に文字列を連結するときは必ず ${変数} で囲む
2. 運用環境では $!{変数名} を優先して使い、null時に$xxxが出力されレイアウトが崩れるのを防ぐ
3. #ifで真偽値プロパティを判定するときは#if($info.IsShowImage1)と記述、==trueは不要

基本テンプレート構文

概要

ASP.NETプロジェクトで広く利用されています；
ASP.NET MVCにはRazorテンプレートが標準搭載；

従来の .aspx ページプロジェクトにMVCモデルを導入したい場合、多くの開発者がNVelocityを選択します。

NVelocityはすでに保守が停止されており、古い.NET Frameworkのレガシープロジェクトでのみ使用します。新規プロジェクトではRazorやHandlebars.NETなど最新のテンプレートエンジンを優先してください。

.NET Frameworkとバージョンの対応一覧

Velocityは古くから存在するJavaテンプレートエンジンで、#、$ をテンプレート記号とする簡潔な文法が特徴です。NVelocityはこの文法を完全に移植しています；

ダウンロード

公式リポジトリの最終更新は2018年、最新バージョンは1.2.0です

下記リンクからソースコードを取得できます

オープンソースでGitHubで公開されています castleproject/NVelocity: Castle’s NVelocity

公式配布ファイルにはコンパイル済みDLLは含まれません。ダウンロード後自身でビルドするか、プロジェクトをソリューションに直接取り込んでください。

Visual Studioでslnソリューションファイルを開く

最終リリース版は.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         # ブルーテーマのテンプレート

実行時に設定から有効なテーマ名を読み込み、NVelocityが対応するテーマフォルダのテンプレートを読み込みます；
テーマ切り替えの仕組み：設定の参照先フォルダを変更するだけで、業務ロジックのコード修正は不要；
古いASP.NET WebForm（aspx）プロジェクトのフロントテーマ切り替えに適しています。

aspx

サイトルートに Register.aspx を新規作成し、デモ用ページとします。

Themes/default 配下に register.htm テンプレートファイルを作成。こちらがNVelocityテンプレートでHTMLとVelocity文法を記述します

Register.aspx を開き、ページディレクティブのみ残し、その他すべてのHTMLを削除します：

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

aspxファイルは画面描画を行わずエントリーポイントの役割のみを担い、裏側のコードがNVelocityを呼び出し register.htm を読み込んでHTMLを出力します。

サイトルート
├─ Register.aspx          # アクセス入口
├─ Register.aspx.cs       # サーバーサイドロジック
└─ Themes
    └─ default
        └─ register.htm   # NVelocityテンプレートファイル

続いて Register.aspx.cs にコードを記述し、現在のテーマの register.htm を読み込み、モデルデータを渡して最終的なHTMLを生成します

テーマを切り替える際は参照先のディレクトリ設定を変更するだけで、対応フォルダの register.htm が読み込まれます

aspx.cs

サーバーコードファイル Register.aspx.cs を開き、Page_Load メソッド内にNVelocity描画処理を記述し、ページ読み込み時にテンプレートを解析・出力します。

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でテンプレートを読み込み描画するコードを記述
        }
    }
}

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/>"));
}

このコードはHTMLテンプレートを読み込み変数を作成し、テンプレート内のプレースホルダーを置換する処理です

1. VelocityEngineのインスタンス生成 独立したエンジンオブジェクト。グローバル静的 Velocity.Init() と違い、複数の独立設定を利用可能。
2. エンジン初期化と設定

• RESOURCE_LOADER=file：ローカルファイルからテンプレートを読み込む指定；
• FILE_RESOURCE_LOADER_PATH：テンプレート検索のルートパス設定；
• ve.Init(pros)：設定を読み込み初期化を実行。

3. テンプレート読み込み GetTemplate() 設定されたルートパスを基に themes/default/register.htm を読み込みます。
4. VelocityContext データコンテキストcontext.Put(キー, 値) でC#変数をテンプレートに渡し、htmファイル内で$websiteName、$domainName と記述し取得します。
5. テンプレートMerge描画template.Merge(コンテキスト, 出力ストリーム) 変数を埋め込み完全なHTML文字列を作成。StringWriter に描画後のテキストを保持します。
6. 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>

上記の$xxxxxxxはPage_Loadで定義した変数のプレースホルダーで、描画時に対応する値に置き換わります。

1. 変数記法 $変数名 $websiteName、$domainName はNVelocity(VTL)の変数文法です。コード内 context.Put("websiteName", "FoxDevelop") で値を設定すると、描画時に自動的に置換されます：

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

実行結果

サイト：FoxDevelop
ドメイン：foxdevelop.com

NVelocity 概要