May 24, 2012

Step by step migrate your Groovy template to Rythm template - Part Two

In the Step by step migrate your Groovy template to Rythm - Part One I have introduced how to import Rythm module and the overview steps to do the migrate. I have also inspect the Rythm template essentials including expression, flow control, scripting and comment. Now let's take a look at page layout management.

Groovy use #{extends} tag to specify the layout template you want to apply to the current template. On the layout template side, you can use #{doLayout} tag to load the content from sub template. Here is the typical scenario you met on Groovy template:

1. views/Application/index.html:
#{extends "main.html"/}

Home

...

2. views/main.html:
<!DOCTYPE html>
<html>
<head>
...
</head>
<body>
...
#{doLayout/}
... </body> </html>

Rythm use pretty much the same thing (@extends and @doLayout tag). Here is what they look like in Rythm:

1. rythm/Application/index.html:
@extends(main)

Home

...

2. rythm/main.html:
<!DOCTYPE html>
<html>
<head>
...
</head>
<body>
...
@doLayout()
... </body> </html>

Pretty simple, isn't it? One place worth attention. I use @extends(main) instead of @extends("main.html"). Actually I could use the latter notation, but it is redundant:
  • template inheritance is static, which happen at parsing time, so the quotation mark is redundant
  • template file extension is deduct using the current template format, thus ".html" is redundant
In addition, suppose your layout template are not put into the view root, e.g. you have a layout template file app/views/themes/blueSky/main.html, to reference it in extends tag you do it this way in groovy:
#{extends "themes/blueSky/main.html"/}
In Rythm you can copy the groovy notation:
@extends("themes/blueSky/main.html")
But I recommend you to use the simple Java package notation:
@extends(themes.blueSky.main)
Note, you are free to use relative path and import path shortcuts when you reference the layout template in extends tag, click here to understand relative and import path shortcut.

In addition, @render() is an alias of @doLayout(). They are two identical tags, and it's up to you to decide which one fit your taste.

Now let's see something interesting.

Passing parameter to layout template


So you can pass parameter from content template to layout template via the #set and #get. Let's say you have a layout template main.html:
...
#{doLayout/}
And in your content template, say index.html:
#{extends "main.html"/}
...
#{set theme:"blueSky"/}
...
You can basically follow the same pattern in Rythm. Here is the main.html:
...
@doLayout()
And the content template:
@extends(main)
...
@set(theme:"blueSky")
...
Every thing looks good. However you have more than one way to achieve it in Rythm. Now let's define main.html like the follows:
@args String theme
...
@doLayout()
And the content template changed accordingly:
@extends(main, "blueSky")
...
It's more clean and simple than the clumsy @set and @get, isn't it?

Render sections


So what if you want the content template provides section contents to be inject into different places in the layout template? Groovy templates comes to get/set again. Let's see the main.html in Groovy:
...

#{doLayout/}
...
And the content template:
#{extends "main.html/}
...
#{set "sidebar"}
  • menu-1
  • ...
#{/set} ... #{set "footer"} copyright ... #{/set}
Now let's see how Rythm handle it. First, main.html:
...

@render()
@// as we said before @render() is an alias of @doLayout() ...
And the content template in rythm version:
@extends(main)
...
@section("sidebar") {
  
  • menu-1
  • ...
} ... @section("footer") { copyright ... } ...
So which style do you prefer? No double it's Rythm to me because it's simpler, cleaner, more consistent, and did I mention that Rythm has one feature that's not found in Groovy at all? Let's take a look at the new version of main.html with default content for "footer" section:
...

@render()
@// as we said before @render() is an alias of @doLayout() ...
Now you can omit the footer section from your content template, Rythm will pick up default content automatically!

In this article we introduced the differences and similarity between Groovy and Rythm on template layout management. We see how Rythm use @extends and @doLayout or @render tag to support layout reuse in template authoring. In the next post I am going to introduce you to another powerful feature of Rythm template engine: tags. See you soon!

See also: Step by step migrate your Groovy template to Rythm template - Part One

1 comment:

Unknown said...

rythm looks great and we've decided to start migrating from groovy, but there are a couple of things we can't find documentation for...

The PlayRythm Demo App has a link for "Fast tags" but the link is broken.

And is there a replacement for the #{form} tag in Groovy that handles CSRF ?



I know you mentioned the next post is about tags, but we can't wait :)

We use them quite a bit.