Penjelasan NVelocity - Tutorial NVelocity

Mesin templat untuk platform .NET, hasil porting Velocity yang awalnya dikembangkan untuk platform Java.

Pengantar

Sering digunakan di proyek ASP.NET;
ASP.NET MVC sudah menyediakan templat Razor bawaan;

Banyak pengembang memilih NVelocity ketika ingin menerapkan pola MVC pada proyek lama yang menggunakan halaman .aspx.

Pengembangan NVelocity sudah dihentikan sejak lama, hanya cocok untuk proyek lawas berbasis .NET Framework. Untuk proyek baru, sebaiknya pakai mesin templat modern seperti Razor, Handlebars.NET dan sejenisnya.

Korelasi versi dengan .NET Framework

Versi .NET Framework	Versi NVelocity
.NET 4.0	1.0 (versi resmi terbaru)
.NET 2.0	0.5
.NET 1.0	0.48

Velocity adalah mesin templat lawas untuk Java dengan sintaks yang ringkas, menggunakan simbol # dan $ sebagai penanda templat. NVelocity memindahkan sintaks ini secara utuh ke .NET;

Unduhan

Pembaruan resmi terakhir dilakukan tahun 2018, versi terbaru adalah 1.2.0

Pembaca bisa mengunduh melalui tautan berikut

Proyek ini bersifat open source dan dihosting di GitHub castleproject/NVelocity: Castle’s NVelocity

Berkas yang diunduh dari situs resmi belum berupa dll hasil kompilasi. Anda bisa mengkompilasi sendiri kode sumbernya atau langsung masukkan proyek ini ke dalam solusi proyek Anda.

Buka berkas sln menggunakan Visual Studio

Versi terakhir dikembangkan untuk .NET Core 2.1, disarankan untuk meningkatkan target kerangka kerja menjadi .NET 4.8

Setelah dikompilasi, berkas dll akan muncul di direktori output

Kemudian masukkan berkas NVelocity.dll ke proyek web ASP.NET lainnya. Tambahkan NVelocity.dll ke proyek web Anda.

Integrasi ke Proyek

Tambahkan referensi rakitan NVelocity.dll ke proyek
Kelebihan utama: mesin templat ini memudahkan penerapan fitur ganti tampilan (ganti tema) situs web

Buat folder bernama Themes di direktori akar situs sebagai tempat penyimpanan semua templat
Di dalam Themes, buat beberapa folder tema, contohnya:

Kita buat folder Themes di direktori utama situs untuk menyimpan tema tampilan

Struktur Direktori Tema

Buat folder default sebagai templat bawaan.
Nantinya bisa menambahkan templat lain seperti Themes/blue, Themes/dark dan sebagainya.

Direktori akar situs
└── Themes
    ├── default      # Berkas templat tema bawaan
    ├── dark         # Berkas templat tema gelap
    └── blue         # Berkas templat tema biruCode language: PHP (php)

Saat aplikasi berjalan, nama tema aktif dibaca dari konfigurasi, lalu NVelocity akan memuat templat dari folder tema terkait.
Cara kerja ganti tema: ubah konfigurasi agar menunjuk folder tema lain, tidak perlu mengubah kode logika bisnis.
Cocok untuk proyek lawas ASP.NET WebForm (.aspx) yang memerlukan fitur ganti tampilan halaman depan.

aspx

Buat halaman aspx baru bernama Register.aspx di direktori akar situs sebagai halaman demo.

Di direktori Themes/default, buat templat bernama register.htm. Berkas ini merupakan templat NVelocity yang berisi kode HTML dan sintaks Velocity.

Buka Register.aspx, hanya biarkan direktif halaman saja, hapus semua konten HTML lainnya:

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

Berkas aspx tidak lagi bertugas merender halaman, hanya berfungsi sebagai titik masuk pengontrol. Kode belakang akan memanggil NVelocity untuk memuat templat register.htm dan menampilkan hasilnya.

Direktori akar situs
├─ Register.aspx          # Titik akses halaman
├─ Register.aspx.cs       # Logika sisi server
└─ Themes
    └─ default
        └─ register.htm   # Templat NVelocityCode language: CSS (css)

Selanjutnya tulis kode di Register.aspx.cs untuk memuat templat register.htm dari tema aktif, mengirim model data dan menghasilkan HTML akhir.

Jika ingin berganti tema, cukup ubah arah direktori tema, mesin akan memuat berkas register.htm dari folder tema yang dipilih.

aspx.cs

Buka berkas kode belakang Register.aspx.cs. Logika rendering NVelocity ditulis di metode Page_Load, akan dieksekusi ketika halaman dibuka.

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)
        {
            // Tempatkan kode untuk memuat templat dan merender halaman menggunakan NVelocity di sini
        }
    }
}Code language: C# (cs)

Tambahkan kode berikut di Page_Load

protected void Page_Load(object sender, EventArgs e)
{
    //Langkah 1 Buat instansi mesin VelocityEngine
    VelocityEngine ve = new VelocityEngine();

    //Langkah 2 Siapkan konfigurasi mesin
    ExtendedProperties pros = new ExtendedProperties();
    pros.AddProperty(RuntimeConstants.RESOURCE_LOADER, "file"); // Muat templat dari berkas lokal
    pros.AddProperty(RuntimeConstants.FILE_RESOURCE_LOADER_PATH, Server.MapPath(@"")); // Direktori utama templat
    ve.Init(pros); // Inisialisasi mesin dengan konfigurasi yang sudah disiapkan

    //Langkah 3 Muat berkas templat
    Template template = ve.GetTemplate("themes/default/register.htm");

    //Langkah 4 Buat konteks untuk mengirim variabel ke templat
    IContext context = new VelocityContext();
    context.Put("websiteName", "FoxDevelop");
    context.Put("domainName", "foxdevelop.com");

    //Langkah 5 Gabungkan templat dan data untuk menghasilkan HTML
    StringWriter writer = new StringWriter();
    template.Merge(context, writer); // Hasil rendering disimpan di writer

    //Langkah 6 Tampilkan halaman ke browser
    Response.Write(writer.ToString().Replace("\r\n", "<br/>"));
}Code language: C# (cs)

Kode ini berfungsi membaca berkas templat HTML, membuat variabel baru untuk mengganti penanda tempat di dalam kode HTML.

Pembuatan VelocityEngine: Objek mesin terpisah, berbeda dengan Velocity.Init() statis global, mendukung beberapa konfigurasi mandiri.
Inisialisasi dan konfigurasi mesin

RESOURCE_LOADER=file: menentukan templat dimuat dari berkas lokal;
FILE_RESOURCE_LOADER_PATH: mengatur direktori dasar pencarian templat;
ve.Init(pros): menerapkan konfigurasi dan menyelesaikan inisialisasi.

Pemuatan templat GetTemplate(): membaca berkas themes/default/register.htm berdasarkan jalur dasar dari konfigurasi.
Konteks data VelocityContext. context.Put(kunci, nilai): mengirim variabel C# ke templat, di berkas htm dapat diakses menggunakan $websiteName, $domainName.
Render templat dengan Merge. template.Merge(konteks, aliranOutput) memasukkan nilai variabel ke templat dan menghasilkan string HTML lengkap. StringWriter digunakan untuk menampung teks hasil render.
Tampilan melalui Response: mengirim HTML akhir ke browser. Replace("\r\n","<br/>") mengubah karakter ganti baris kode sumber menjadi tag ganti baris HTML.

Templat htm

Ubah berkas register.htm di direktori tema

<!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>
    Situs: $websiteName <br />
    Domain: $domainName
</body>
</html>Code language: HTML, XML (xml)

Dua penanda $xxxxxxx di atas adalah tempat variabel yang dibuat di Page_Load, akan diganti dengan nilai yang sesuai saat proses rendering.

Penanda variabel $namaVariabel. $websiteName, $domainName adalah sintaks variabel NVelocity (VTL). Nilai ditentukan melalui kode context.Put("websiteName", "FoxDevelop"), mesin akan menggantinya secara otomatis saat rendering:

$websiteName → FoxDevelop
$domainName → foxdevelop.com

Hasil eksekusi

Situs: FoxDevelop
Domain: foxdevelop.comCode language: HTTP (http)

Penjelasan NVelocity