This document details how to use Rythm to write template source.
Rythm Template Engine is a text generator that merges dynamic content into static template.
In order to use Rythm to generate a text file, the essential work is to create template file which write down the static part and use Rythm syntax to define the dynamic parts. It is also important to understand that a template file has one or more arguments which is the origin of the dynamic content. The Java program pass parameters to template file via arguments to generate different result.
So a template file is a text file, some parts of which have placeholders for dynamically generated content. The template’s dynamic elements are written using the Java language.
Dynamic elements are resolved during template execution. The rendered result is then sent as part of the HTTP response.
The Rythm template syntax is designed to be easy to learn and what you need to understand is one fact:
The magic @ character is used to lead all rythm element.
@ character, you need to double it. E.g.This is an email address in template: someone@@gmail.com
All static content (those text not defined in Rythm elements including script blocks) are output literally including whitespace and new lines.
one line comment start with @//
@// this is one line comment
multiple lines comment are put inside @* and *@ block.
@*
this is a multiple line comment.
The text inside this block will be ignore by Rythm template processor
*@
Output expression is the core function of Rythm template, it is used to emit dynamic content passed into the template, including emission of object fields and methods, class fields and methods:
@args User user, Foo foo
// emit instance field
@foo.bar
// emit instance method
@user.getName()
// emit class field
@Long.MAX_VALUE
@Integer.MAX_VALUE
// emit class method
@Boolean.parseBoolean("true")
The bracket ( ) can be used to compose complicated expressions or to separate an expression from other part of the template:
@(1 + 5) @// print out the result of 1 + 5
@// use ( ) to separate expression from other part of the template
@(foo.bar)_and_some_other_string
As shown in the above example, the instances/classes/fields/methods inside an expression could come from anyone of the followings:
- Template arguments
- Template built-ins
- Variable declared in scripting blocks
- Directly referenced classes
- Variable declared with
@assign()directive - Variable declared with
.assign()extension to template call
TBD