Sunday, November 27, 2011

StringTemplate 4 Note for Java Programmers

StringTemplate is a very simple and powerful template engine. The existing documents are fairly complete. As long as one knows where to find those documents, learning StringTemplate is quite easy. This note is intended to help users to quickly find needed documents.

To learn StringTemplate means to learn the following three aspects of it:
  1. The core concepts and the relationship among them
  2. Syntax of templates and template groups
  3. API

In this document, users can find:
  • A brief introduction to StringTemplate 4
  • Instructions to setup Java programs to use StringTemplate 4
  • Syntax of templates and groups  
  • StringTemplate 4 Java API
The syntax documentation is quite formal and is in (a variation of?) the Backus-Naur Form notation. Programmers who are not used to such formal notation may feel that the syntax documentation is hard to understand. For those programmers, my recommendation is to spend one hour to learn the Backus-Naur Form notation. Of course, examples also help.

This article from the creator of StringTemplate provides:
  • An overview of StringTemplate
  • The philosophy of StringTemplate
  • The theoretical foundation of StringTemplate
  • A few examples showing the main features of StringTemplate, namely:
    • attribute (and attribute property) reference
    • map operation (i.e. applying a template to an attribute that is a list of objects or applying a list of templates alternatively to an attribute that is a list of objects), 
    • conditional include
    • recursive template.
Many template users say that certain other template engines are more powerful than StringTemplate. This article helps users to understand why those features existing in other template engines are purposely excluded from StringTemplate for very good reasons.

In this article by the creator of StringTemplate, the author provides a comprehensive introduction, explaining the major concepts in StringTemplate with examples:
  • Template
  • Template group
  • Expression
  • Attribute
  • Multi-valued attribute
  • Implicitly set attribute
  • Template include
  • Conditional include
  • Template application, to a single or multiple attributes
  • Anonymous inline template
  • Recursive template
  • Group inheritance and overriding
  • Template region
  • Group interface
  • Map (dictionary) and list
  • Renderer
This is the deepest document about core concepts in StringTemplate. Consider this article as the must-read in order to really mater StringTemplate. The syntax of template is up to date. However,  the Java API has been changed since the publication of this article. Therefore the Java code examples in this article are out of date.