Community contributed extensions

Integration Guide

This section is PlayRythm specific content, pure Rythm user should skip this section

Migrate your current project from Groovy template engine to Rythm

PlayRythm is designed to support smooth migrating from Groovy template engine.

PlayRythm hijack the template rendering process if it found the corresponding template exists in the app/rythm folder. Otherwise it quit silently and leave groovy engine to handle it. So what you need to do is just create an new template file using Rythm syntax and put it into the app/rythm folder. Before your new rythm template available your existing groovy template works like a charm, and after the rythm template created, Rythm will take over

Tip: enclose all your rythm template with #{verbatim} and #{/verbatim} can help you avoid groovy compile exception and does not impact your rythm template. This is not true. The groovy template engine will still parse the expressions. See Resolve groovy compilation error for workarounds.

Resolve groovy compilation error

Because groovy template engine does not provide a way to skip parsing any part of the template file, the rythm template file might cause compilation error during precompile process, where rythm has no way to identify some files been a rythm template or groovy template, e.g. some json generation template.

Start from version 0.9.5 it’s suggest to move all rythm templates or at least those compilation error causing templates to app/rythm folder from app/views folder.

Start from version 1.0.0 app/views folder as template root as no longer supported, please move all rythm view files into app/rythm folder. And there will be no groovy compilation error any more caused by rythm template

More about tags

So far you can keep rythm tags file under app/views/tags/rythm folder. However it is recommened not to use tags folder at all since every rythm template is a tag and can be called from any other rythm templates.

Start from v1.0.0, app/views/tags/rythm folder as tag root are no longer supported. Please just use app/rythm folder as template root and also the tag root.

E.g. suppose you have a template file app/views/Order/list.html, while you can use it as an ordinary template file, you also free to call it as a tag from other rythm template like: @Order.list(myOrders)

Invoking controller actions

PlayRythm 0.9.7 version released with this new feature which is first introduced in Japid template engine and people seems like it a lot. Basically you can invoke a controller action method directly from within the template and fill the place with the render result content. As with any function/tag/template invocation, action method invoke is very straghtforward. Excamples:

@controllers.Applicaiton.index().cache("1h");
@controllers.MyPortal.newsPanel(user);

Things you need to take care of:

  1. You must use full qualified method name (including package name, class name) when you invoke controller action method No longer required since v1.0.0
  2. You must pass exactly the parameters that matches what is defined in the controller action method signature. The parameter must be passed in by position
  3. The invocation is directly and will not go through the whole stack of Play’s action invocation process. Meaning the @Before, @After and @Final logic will NOT be executed, the same thing happens to all plugin’s beforeActionInvocation(), onActionInvocationResult() and afterActionInvocation() hooks.
  4. Start form v1.0 controller invocation is eligible to the following tag invocation extensions:
    1. Cache: @controllers.Application.index().cache(“1h”)
    2. Invoke with relative path/import path: @import controllers.*; @Application.index()
    3. Assign action result to a variable: @controllers.Application.index().cache(“1h”).assign(“indexPage”). And you can use it as a normal template variable later on: @indexPage.raw()
    4. Escape/un-escape render result: @controllers.Application.index().raw()

New Cache4 annotation for caching action invocation

Though not so relevant to a template engine, Rythm still provides an new annotation com.greenlaw110.rythm.play.Cache4 for controller action (GET and HEAD) result caching. It improves the Play’s built-in play.cache.CacheFor in the following way:

Sample:

@Cache4("cron.top10.cache")
public static void displayTop10() {
...
}

In your conf/application.conf:

cron.top10.cache=5mn

You can set useSessionData attribute to true to create a per-user-cache mechanism:

@Cache4(useSessionData = true, value="1h")
public static void showMyInterests() {
...
}

Cache4 side effects

Cache4 logic is implemented in RythmPlugin.beforeActionInvocation() and RythmPlugin.onActionInvocationResult() hooks. This indicates the following side effects of Cache4:

So you should NOT use Cache4 annotation in the following cases:

For module or application defined filters that will throw out non-permanent Redirect result, for example, secure module will cause redirect if user has not logged in, in which case you are still safe to use Cache4 with useSessionData enabled. See above example.

@Cache4 does not require you to use Rythm template, it works with any controller action methods

See Also

  1. Rythm Template User guide
  2. Reference manual