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

I Like Python

I recently started learning Python and to my surprise find it to be a very nice language.

I had heard good things about it years ago but never gave it a look. I noticed that Joel Spolsky gave Python half credit as a safe choice of language to develop enterprise applications in. Still, I was (and still am) happy working in Java.

What prompted me to look at Python is my new Job. I now work at BEA. The BEA WebLogic Server has a tool for configuring and managing domains called WebLogic Scripting Tool (WLST). WLST is based on Jython (Jython is Python implemented in Java).

I started reading a Python tutorial. The first thing I noticed is that code blocks are identified by indenting. This seemed very strange and uncomfortable after years of using curly brackets. Now it makes sense to me. I was going to indent my code anyway so why shouldn’t the language make use of that fact. A side benefit is no more arguing over if the curly brackets belong on the same line or a new line. If arguing about code style floats your boat be comforted that you can still argue over how many spaces to indent.

So far I have created two small utility programs in Python. One gathers some information about files and outputs an XML file. The other processes an XML file using SAX and outputs a new XML file. (I didn’t use XSLT because I needed to write files, run a program and include it’s output as new element content.) Even with the learning curve I was able to write these programs faster then I could have in Java. Also the code is much smaller than their Java counter parts would be.

Some things I like about Python:

  • Simple but powerful syntax is quick and easy to learn. It seems to me to be minimally complete. In other words it doesn’t have lots of unnecessary junk.
  • Very good documentation including tutorials.
  • The interactive interpreter makes it easy to try things out. This facilitates learning.
  • Like JavaScript, Python has a syntax for creating rich literal data structures. It is so much easier to do this:
    fruit = { "apples": [ "Cortland", "Braeburn"], 'pears': [ "Bartlett", "Bosc" ] }

    Than it is to do this:

    HashMap fruit = new HashMap();
    ArrayList apples = new ArrayList();
    ArrayList pears = new ArrayList();
    fruit.put("apples", apples);
    fruit.put("pears", pears);

  • List comprehension – a concise syntax to make new lists from existing lists without the usual for loop. Example: [ x**2 for x in range(5) ] produces this list: [0, 1, 4, 9, 16]
  • An extensive standard library of functions and classes.
  • The map() and reduce() functions.

Python will replace Perl as my scripting language of choice.

A box to put my music in

If you have ever watched a toddler play with an empty box you know how simple and satisfying a box can be. Put something in and it stays there. Move the box and the thing inside goes with it. Some things fit some things don’t. Toddlers are delighted to put something in and take it out over and over again. That is until they learn it’s more fun to pull CDs off the shelf.

I want my music player to be as simple as a box. A special box that when you put music in it you will hear the music. A CD player is pretty close. You push a button and a tray opens. Put a CD in it, push the tray closed and it plays. A car CD player is even better just stick a CD in the slot and it plays. Push a button to get it out.

But these days CDs are old news and CD players are single purpose (don’t put a Pop Tart brand toaster pastry in your CD player). MP3s are where its at. I want my MP3 player to work like a box. This box doesn’t hold physical things from the real world but virtual things, digital information in the form of music or anything else. In the digital world the closest thing to a box is a file system. They are ubiquitous. Every general purpose computer has one. Everyone that uses a computer has some mental model of how it works as evidenced by verbal exchanges such as “Where did you put that file? Look in the Budget folder”. They can hold any kind of information as long as it fits. When the file system is on removable media the contents can be moved around just like a thing in a box. Currently the best digital box is the USB flash drive (a.k.a thumb drive). They are small, durable, there are no cables to fumble with or misplace and every modern computer has a USB port.

Wouldn’t it be great if when you put music files (in the MP3 format for example) on a flash drive you could listen to them. At first glance the iPod brand Shuffle MP3 player would seem to fit my needs. It plugs directly into a SB port like a flash drive and can hold music as well as other files. But the Shuffle requires iTunes to put music on the device. That isn’t very box like. Imagine the toddler faced with a box that required a separate machine to put things in or get them out. Even worse the machine wouldn’t allow putting the same thing in more than five specific boxes. The child might just smash them both and move on.

I recently purchased a Creative Labs MuVo v100 MP3 player. It is just the box I was looking for. It works like a flash drive. It comes with but doesn’t require additional software. Just plug it into any computer with a USB port and copy MP3 files to it. The user interface is very easy to use. There is a play/pause/on/off button – hold for on/off. There are volume up and volume down buttons and a jog/push button for next/previous/fast forward/fast rewind and menu navigation. The screen is small but very readable. Now the instructions that came with the thing did say to install the software first before plugging in the MuVo. I ignored these instructions because I had high hopes for my new box and it didn’t disappoint. I still haven’t installed the software but I may just to see what it is like or read the manuals. So far I have had no problem figuring out the menus. I takes regular AAA batteries which is nice and has a cool way of snapping into the battery compartment. The only defect in the MuVo is that it plays WMA files with DRM (to play a file with DRM you must use the supplied software). But this is easy to work around by simply not buying music with DRM in it.

I got the MuVo mostly to play in the car. I just got a new car that has an Aux jack to plug into. The Aux jack in a car stereo is another great idea. No more cassette adapter or FM transmitter. The jog button is very easy to use in the car. I can change songs without taking my eyes off the road.

Note: It seems it is possible to get around the iTunes requirement. I have not tried this and it still requires another program. Perhaps someone has figured out how to replace the iPod firmware so another program isn’t needed. I may try this hack because my kids received iPods as gifts and the only computer I was willing to install iTunes on is old and now has power supply problems. Why my aversion to iTunes? There are a few reasons. One is that installing it on a Windows 2000 machine nearly destroyed the system permanently. The computer would not boot – not in safe mode not no how. I finally figured out what file needed to be deleted and removed it by booting from CD. Seems that it was trying to install some kind of file system filter driver. I don’t know what about my particular system configuration was causing the problem but I don’t see why a music program needs to muck with the file system. After this I no longer trusted iTunes.

Lego Marble Machine

I don’t know what it is about this one but I like it. It sits on my desk and every now and then I turn the crank or run the motor and just watch the marbles go round. It’s fun. It’s hypnotizing. It’s pointless.

A few months ago my kids and I were building with Legos and making marble runs for the Geomag marbles. I started thinking about different ways to get the marbles raised up. I remembered seeing a device not too different from the one I built but made out of wood. I saw it in a craft fair years ago and although I never saw it in motion I knew what it was for and how it worked. I thought of making my own out of wood but so far have not. Think of this Lego machine as a prototype for … Well that’s a project for another day.

It is made out of various Lego, Technic, and Mindstorms kits except for the metal Geomag marbles. The yellow and green rails are from one of the Mindstorm add-on kits. There is no programming to this one. The programmable brick simply runs the motor which I turn on with the remote control. Alexandria and Isabella made the minifigs and Yoda’s hut. I added them to the video to liven it up.

I have wanted to try out YouTube for a while now and sharing the marble machine seemed like a good way to do it. I’m no musician but I think it is important for videos to have a sound track. For my home videos I usually use music from my CD collection. But because this one was going public I decided to see what Creative Commons had to offer. From there found “Fault in the air” by DJFer. The video was made with my old Sony digital 8MM camcorder. For editing I use Adobe Premiere.

HTML button is not useful

Sometimes things seem so obvious once you learn them the hard way that you wonder why there aren’t big signs everywhere making it clear from the start. The HTML button element is useless when used with a server side controller. I got my information on the button element from the HTML specification and was happily using it with Firefox as my client. (I have found Firefox with key extensions to be an indispensable tool in developing web applications.) When I tried my app with IE 6 I quickly found that my servlets couldn’t distinguish which button was pressed.

My testing shows that in IE 6 all <button type=”submit”> values are submitted any time the form is submitted. In addition the content is used as the value rather than the value attribute. I searched for more information to see if I was missing something. I wondered how could IE get it so wrong and if it was wrong how could I have not heard about this problem before. Most of the articles I found about button talked about how great it was because it gave so much control over the content and style of the button. The best evidence I found that button was indeed broken in IE came from comments to the article “Push my button”. Standard vs. quirks mode makes no difference. I have not tested IE 7 yet. I did notice that some articles say that the button element is just for use with JavaScript but they don’t say it is because of the IE bug.

The thing that originally attracted me to the button element is that it allowed specifying the value of the button independent of the button label. The input element of type button has the problem that the label can’t easily be used to distinguish which button was pressed when the button label is localized. You could have the controller test the button value using the localized label string but yuck! In general internal tokens and display text should be kept separate.

The general requirements for using buttons are:

  • Multiple submit buttons on a form and it must be possible to distinguish which was pressed.
  • The button text must be localizable so you can’t rely on the button label to distinguish the button.
  • The solution must not require JavaScript. This would break the principal of progressive enhancement.

I can’t use <button name=”submit” type=”submit” value=”v1″>Label</button> because IE returns the content “Label” rather than the value “v1″ and because all buttons of type submit are returned so you can’t tell which button was pressed. I also can’t use <input name=”submit” type=”submit” value=”Label” /> (where multiple buttons use the same name) because the buttons cannot be reliably distinguish. The value is “Label” in English but may be different when localized.

I see two options and both use the input element of type button. One is to use a different name for each submit button. The draw back is slightly messy code on the back end where you have to check for the presence of different parameters. The second option and the one I use is to encode the intended value of the button in the name.

For example: rather than
<button name=”submit” type=”submit” value=”v1″>Label</button>
I would use
<input name=”submit_v1″ type=”submit” value=”Label” />

In the controller servlet I have common code to look at the parameter prefix “submit_” and extract the button value.

The main thing you loose out on is the styling ability of the button element. Progressive enhancement can be used to swap input for button and add the needed JavaScript to submit the correct parameters. This will give correct behavior for clients without JavaScript and provide a nicer look for clients with JavaScript

Both approaches have their problems. To implement the first in a common controller servlet would require that the controller know about all the names that could be used on submit buttons. With the second approach the controller pollutes the namespace of form properties.