Jun 30, 2012

Rythm now has SIM (String Interpolation Mode)

In the latest release of Rythm Template Engine you can use String Interpolation Mode (short to SIM later) for simple template, where simple template means something you can do with String.format().
String result = Rythm.render("Hello @who!", "Rythm");
As a comparison, previously you need the following code:
String result = Rythm.render("@args String who;Hello @who!", "Rythm");
It's really annoy to declare render argument types for such a simple template because we could treat the argument used in the expression as an Object. Yes, this is exactly what SIM did for you, automatically declare the argument reference to java.lang.Object type, and save your typing. Looks not a big deal, but it literally make Rythm.render() an replacement of String.format() for most cases. You get two benefit from Rythm SIM over String format:
  1. performance: Rythm.render is 2 times faster than String.format except the first call
  2. You can pass in arguments not only by position, but also by name
    Map<String, Object> args = new HashMap<String, Object>();
    args.put("who", "world");
    String result = Rythm.render("Hello @who!", args);

SIM Limitation

So as mentioned above SIM only applies to simple templates. The question is what defines a simple template?
  • First you can only have single variables in an expression, reference to class fields or method or any combination of two or more variables is not allowed. If you want to use these advanced expression, you must declare the type of the render arguments explicitly

    Rythm.render("the name is @user.username", user); // bad
    Rythm.render("the name is @name", user.username); // good
    Rythm.render("@args User user;the name is @user.username", user); // good
    Rythm.render("the sum is @(left + right)", left, right); // bad
    Rythm.render("the sum is @sum", left + right); // good
    Rythm.render("@args int left, int right;the sum is @(left + right)", left, right); // good
  • You cannot use some keywords. In other words, some Rythm template features are not available to SIM. Here is a list of Rythm keywords you should avoid to use in SIM:

    1. @args, declare template argument variables
    2. @extends, extends a layout template
    3. @section, define a template part to be inserted in the layout template
    4. @render, used in layout template to render a template section defined in sub template
    5. @doLayout, same as @render
    6. @doBody, call back tag body
    7. @include, include another template content in place
    8. @set, set template variable to be fetched by layout template
    9. @get, get the template variable set in the sub template
    10. @expand, execute/expand an macro
    11. @exec, same as expand
    12. @macro, define an macro
    13. @def, define an inline tag
    14. @tag, same as @def
    15. All extended keywords including the following defined in PlayRythm plugin
      1. @url, reverse url lookup
      2. @fullUrl, absolute reverse url lookup
      3. @msg, message lookup

How to render with SIM

Now the question is how to specify Rythm to render with SIM instead of ordinary rendering mode. The answer is simple, if your template does not contains the keywords listed above, Rythm will render the template in SIM.

Foot notes: Rythm Template Engine is a static typed Java template engine using Razor like syntax. There is a full feature set demo hosted on GAE. The source code is hosted on github

No comments: