The writings of John Snyders, mostly about software.

On Learning StringTemplate

I have been thinking lately about the learnability (the ease with which something can be learned) of StringTemplate. I like StringTemplate and would like to see more people make use of it. To that end I think there are some things that can help make it easier for people to get started with it.

StringTemplate is both a language for describing text generation and a tool (template engine) that implements that language and provides an API to connect the tool to another program.

StringTemplate is not a general purpose language and cannot stand on its own. By design it has no way to perform general computation. It also has no general way to create data and limited ability to specify literal data. It is up to some driving program to produce and or make data available to the StringTemplate template engine. This is not a negative â€“ this is it’s strength. See this excellent paper for why.

However, the lack of readily available data makes learning the template language difficult without also learning the StringTemplate API. In order to try StringTemplate out one must learn the template syntax and semantics, and the API and then write a program to produce some data and call the template engine.

In theory one benefit of the separation of presentation from business logic is that a project can be divided between people who work on the business logic (the program) and people who work on the presentation (the templates). The people working on presentation don’t need to be programmers.

The current documentation for StringTemplate describes both the template syntax and the Java API at the same time. In some cases it is confusing to learn two things at once and more importantly it excludes non-programmers from learning StringTemplate.

In contrast, trying out XSLT is is easy (even if mastering XSLT is hard) because all you need is a text editor to create both your input documents and your style sheet and an XSLT program to process the style sheet with the input documents. Likewise trying out HTML is easy, all you need is a text editor and a browser. Interpreted languages like Python that have an interactive mode also make it easy to jump right in and get the feel of things. (I’m not saying that StringTemplate is like XSLT, HTML or Python, I’m just comparing the ease with which one can dive in and try the technology out.)

So what StringTemplate needs is a literal representation for data that can be used as input and a stand alone program to read the data and templates to produce the output text.

I created a command line tool called StringTemplate Standalone Tool (STST). It takes as input the name of a file containing data in JSON format, the name of a template and optionally the name of a group as well as various options.

Look ma, no programming.

Here is a simple example of how it is used.

Create a JSON file called data.js with this content:{ "audience": "World" }

Create a StringTemplate file called first.st with this content:Hello $audience$!

From a command prompt in the same folder as the above two files type> stst first data.js
The output isHello World!

It also works with group files and can use the angle bracket lexer. For command usage type: stst -h

The next thing StringTemplate needs is a tutorial that focuses on the template syntax independent of the API. STST enables this kind of tutorial. Separate documentation can focus primarily on the API.

6 thoughts on “On Learning StringTemplate”

I’m glad you found this interesting. If you have a need for a UI then go for it. You might look around I think someone may have created an editor for StringTemplate that does syntax coloring. And because JSON is a subset of JavaScript many editors or IDEs already support it.

You can find information about StringTemplate in Tarence Parr’s excellent book The Definitive ANTLR Reference, chapter 9.

Hey, very interesting, thanks for your work, I was thinking on making a kind of user interface for it for fast prototyping :), what do you think ?

What is sad about stringtemplate is that I couldn’t found a book for it. I mean, stringtemplate is such a very meaningful project for the java comunity and there is no resource that can help you understand it from top to tail

Great work!
I havent been using StringTemplate a lot, but while stst is a good step in the right direction,
what could give more bang for the buck is integration with some of the popular MVC web development frameworks like Turbogears and RubyonRails.

Doing this for Turbogears seems to be really easy. just write a plugin that interfaces the template engine api and the stringtemplate api. i have just begun fiddling with this idea.