shepherdwindVelocity.js
A JavaScript implementation of the Apache Velocity template engine.
Features
- ✨ Full support for both client-side and server-side rendering
- 🔄 Separation of template parsing and rendering phases
- 🎯 Complete compatibility with Java Velocity syntax
- 🚀 High performance and lightweight
Installation
npm install velocityjs
Quick Start
import { render, parse, Compile } from 'velocityjs';
// Simple rendering
const result = render('Hello $name!', { name: 'World' });
console.log(result); // Output: Hello World!
// With macros
const macros = {
include: (path) => `Included content from ${path}`,
};
const template = '#include("header.vm") Hello $name!';
const rendered = render(template, { name: 'World' }, macros);
API Reference
Core Methods
render(vm, context, macros)
Renders a Velocity template string with the provided context and macros.
Parameters:
vm(string) - Velocity template stringcontext(object) - Data context for template variablesmacros(object) - Custom macro functions
Returns: (string) Rendered output
parse(vm, config, ignorespace)
Parses a Velocity template into an AST (Abstract Syntax Tree).
Parameters:
vm(string) - Velocity template stringconfig(object) - Parsing configurationignorespace(boolean) - Whether to ignore whitespace trimming
Returns: (Array) AST nodes
Compile
Compiles parsed AST into a renderable template.
import { parse, Compile } from 'velocityjs';
const asts = parse('Hello $name!');
const template = new Compile(asts);
const result = template.render({ name: 'World' });
Configuration Options
Compile Configuration
escape(boolean) - Enable HTML escaping for variables (default: false)unescape(object) - Specify variables to exclude from escapingenv(string) - Set to 'development' to throw errors on null valuesvalueMapper(function) - Custom value transformation for #set directivescustomMethodHandlers(Array) - Custom function behavior implementations
Context and Macros
Context Object
The context object provides data and methods to your templates:
- Properties are accessed using dot notation:
$user.name - Methods can be called directly:
$formatDate($date) - Methods have access to an
evalmethod for dynamic rendering
Macros
Custom macro functions can be defined for directives like #include:
import { render } from 'velocityjs';
const macros = {
include: (path) => {
// Custom include implementation
return readFile(path);
},
};
Supported Directives
#set- Variable assignment#foreach- Loop iteration#if/#else/#elseif- Conditional logic#macro- Template macro definition#break- Loop control#stop- Template execution control
Getting Help
- 📝 Create an issue
- 📧 Email: eward.song at gmail.com
License
MIT License