A new release of Stringtree is now available at Sourceforge

This release contains the following changes:

• added smarter string parameter parsing to DriverManagerDataSource for use from spec files
• made Spliterator constructor parameters more sensible for common usage
• alternate XML parser to support an output object tree compatible with JSON
• added DataReader interface and both XML and JSON implementations
• added AgnosticDataReader which detects and correctly parses both XML and JSON.
• added EasyTemplater to wrap up commmon usage cases

Recently, several people have been asking for more (ok, any at all) documentation on Stringtree, so here is the first of an occasional series of usage tips.

Get into Templating using EasyTemplater

One of the most popular bits of the Stringtree codebase is the Stringtree Templater. The basic aim of this is to help separate output formatting from data structures and behaviour. Stringtree Templater is a general-purpose templating system roughly equivalent to something such as Velocity, Smarty and many others. The main differences between Stringtree Templater and most others are that it allows refactoring and reuse of templates at a very fine-grained level, it has a concise syntax, and it is fast in use.

Up until now, the main issue in the way of adoption of Stringtree Templater was that its flexibility of configuration got in the way of simple use. The ability to load templates and substitution values from a wide range of different sources led to some confusion about exactly how to set it up for common cases.

With this in mind, Stringtree 2.0.8 now includes EasyTemplater, a wrapper which provides most of the power of Stringtree Templater without the head-scratching.

To use Stringtree Templater, you really only need to tell it where to find its templates. In the simplest case, this might be from a location on the file system. For example:

import org.stringtree.template.EasyTemplater;
…
EasyTemplater templater = new EasyTemplater("/some/directory/somewhere/");
…

Note the "/" at the end of the directory name. If you use this constructor, which takes a single String, it’s important that you include this. Under the covers, this constructor treats the location as a URL, defaulting to a "file:" URL if no scheme is supplied; you can just as easily load templates from a web server using an http: URL, or from the classpath using a classpath: URL, for example.

If you wish to be more precise about your template location, there are also constructors which take a File or a URL.

When you have created an EasyTemplater, using it is as simple as placing some values in its internal "context" and calling one of two methods String toString(String templateName), or byte[] toBytes(String templateName). These methods will look up the named template, expand it by substituting values from the internal context as required, and return either a String or an array of bytes.

As a more fully worked example, imagine that we have a directory in the current classpath named "templates". In this directory we have two files: person.tpl containing

Name: ${this.name}, Telephone: ${this.phone}

and list.tpl containing

Please contact the following people
${people*person/}
and tell them about ${product}!

Here’s a complete example using these templates:

// Somebody.java
// a "bean" to hold a person's contact details
// no dependencies on any Stringtree classes
public class Somebody {
  private String name;
  private String phone;

  public Somebody(String name, String phone) {
    this.name = name;
    this.phone = phone;
  }

  public String getName() { return name; }
  public String getPhone() { return phone; }
}

// Example.java
import org.stringtree.template.EasyTemplater;

public class Example {
  public static void main(String[] args) {
    EasyTemplater templater = new EasyTemplater("classpath:templates/");
    Somebody[] folks = new Somebody[] {
      new Somebody("Gordon Brown", "07112345678"),
      new Somebody("George Bush", "1-555-123-4567")
    };

    templater.put("people", folks);
    templater.put("product", "EasyTemplater");

    System.out.println(templater.toString("list"));
  }
}

If all goes well, you should see something like:

Please contact the following people
Name: Gordon Brown, Telephone: 07112345678
Name: George Bush, Telephone: 1-555-123-4567
and tell them about EasyTemplater!

That’s about it for today. Happy templating

Posted by Stringtree in Projects, Templater