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 choose JSON as the literal data format. The reasons are:

  • Its a standard
  • It is becoming increasingly well known
  • It is easy to type in and not overly verbose
  • I had already made changes to get a Java JSON library to play nice with StringTemplate.
  • It supports all the data shapes that StringTemplate works with.

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 is
Hello 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.

Download STST here

This tool can have other uses as well. Here are some ideas:

  • It is a quick way to try out template syntax without having to write or modify a program. This can benefit seasoned template authors as well as beginners.
  • It could be part of a test framework for StringTemplate itself or for a set of templates in an application. The templates can easily be processed with known data and the expected results asserted.
  • It enables development of the templates before or in parallel with code by creating a JSON data file that represents what the code will produce.
  • It could be used as part of shell scripts where some existing program outputs JSON data and STST is used to generate text from it. The data could come from a web service for example.

What could you use it for?

Future possible directions for STST

  • Integrate the functionality into an IDE for StringTemplate
  • Expose the functionality in an interactive servlet (web app).
  • Support other data formats like CSV, YAML, or XML
  • More support for renderers

6 Responses to “On Learning StringTemplate”

  1. Ram Says:

    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.

    cheers
    ram

  2. Ram Says:

    I have saved my notes here for now.
    http://ramontg.blogspot.com/

    would be great if some one could write a StringTemplate Version of the 20 minute wiki tutorial.
    Thanks
    cheers
    ram

  3. Rob Williams Says:

    I would like to see WebStringTemplate adapted for Python and TurboGears. I may end up doing it myself…

  4. David Hofmann Says:

    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 :(

    Well maebe it is just because I am using it just a couple of days

  5. John Snyders Says:

    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.

  6. jolsys Says:

    Hi i have a problem, it looks as JSTL

    Administrator

    User

    how to do this stringTemplate