Community contributed extensions

String Interpolation Mode

This is NOT a Play specific feature.

Rythm (starts from v1.0.0-20120630) provides an new feature called SIM, the “String interpolation mode”. With this feature one can use Rythm in a most lightweight way.

String result = Rythm.render("Hello @who!", "Rythm");
// the result is "Hello Rythm!"

The above code is passing render arguments by position, you can also pass arguments by name:

Map<String, Object> args = new HashMap<String, Object>();
args.put("who", "Rythm");
String result = Rythm.render("Hello @who!", args);
// the result is "Hello Rythm!"

As a comparison, previously you need a much more verbose way to do the same thing:

String result = Rythm.render("@args String who;Hello @who!", "Rythm");

As you can see with String interpolation mode, you can omit the argument declaration. Might not looks a big deal at first glance, but it literally make calling to Rythm method costs nothing more than a String.format() call, while you get more than String.format() in that first you have a faster version (except the first call), and second, you can pass in render arguments by name.

Reference to an array in SIM

Start from v1.0.0-20120703, it’s possible to reference to an array in SIM:

Long[] la = {1L, 0L};
String result = Rythm.render("first item is @la[0], second item is @la[1]", la);

As you might noticed that I am using Long[] instead of long[] to declare the array type. This is because Rythm cannot infer the type and thus put everything to type Object, so you must NOT use the primary type to make it work with SIM. Also note complex expression like follows will not work with SIM:

Long[] la = {1L, 0L};
String result = Rythm.render("@(la[0] * la[1])", la); // Won't work
String result = Rythm.render("@args Long[]la;@(la[0] * la[1])", la); // this works

What you don’t have in SIM (String interpolation mode)?

SIM is not aimed to be used in all cases. Rather it is suggest to use SIM only in very simple templates, in short where you can use String.format(). For comprehensive templates you still need to declare render arguments using @args keyword. There are the following limitations with SIM:

Complex expression cannot be used in SIM. Since all variables are treated as Object type, you cannot invoke any specific class fields or methods other than Object.

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

Keywords you cannot use in SIM mode:

  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 specify Rythm to enter SIM to render the template?

You don’t specify Rythm to enter SIM, Rythm is intelligent enough to enter SIM automatically if it found there is no keywords specified above in your template.

How to specify Rythm NOT to enter SIM?

As states above whenever you used any of the keywords listed above, Rythm will use normal mode to render the template. However in certain case you might want to explicitly ask Rythm not to use SIM by adding a @nosim() into the template at anywhere.

See also

  1. To string mode
  2. Rythm Manual Home Page