Ratpack Templates

Rendering html templates in Ratpack is very straightforward. We'll use the built-in templating features of Ratpack's Groovy module to render very simple templates, to complex templates with sub-templates; and templates with dynamic data.

Rendering A Simple Template

As mentioned in our previous post, Ratpack applications have a base dir that contains all the files accessible at runtime. When using the Gradle plugin, this is the src/ratpack directory during development. The default location for template files is the templates directory inside the base directory. If we place our html templates under the templates folder, then we can easily render them. For example, if we have a template called hello.html, we can easily render it as follows:

Rendering Templates With Dynamic Data

In most cases we will want to render some data that we retrieved from a database or some other location. We won't be covering how to interact with a database in this post, so we'll just use arbitrary data for the sake of keeping it simple. Let's say we want to print the message "Hello Jon, meet the amazing Ratpack". groovyTemplate can also take a Map and a String as parameters. It's signature looks like this: loading

This is how we would use this method to render some data in our template:

We are using Groovy's named parameter syntax here.

Template files are just text files with embedded Groovy expressions.

The content of the file is effectively evaluated as one big Groovy GString. Code can be evaluated via the standard $«variable» or ${«code»} GString constructs.

The API available for a template file is the TemplateScript type. Note how it provides a getModel() method that provides the map of data that we passed to the groovyTemplate() method. It also provides the html() method that can be used for escaping HTML meta characters. A better way to write our template would be:

This way, if someone is unfortunate enough to contain <strong> in their name we will correctly encode this as <strong> in the output HTML.

In addition to the $«variable» and ${«code»} constructs, <% «code» %> and <%= «code %> can also be used for larger (i.e. multiline) blocks of code. The difference is that the latter outputs the string value of the last expression while the former does not.

If you need to output a literal $ character, you can simply escape it with \$.

Composing Templates

Templates can also be composed. This allows us to reuse templates in a very elegant & convenient manner. A common use case is if we want all our pages to have the same header and footer. The render() method of TemplateScript can be used to render nested templates.

There is nothing special about these templates. They reside under the templates directory and they don't really need the underscore in front of their name, but it is the recommended convention to use. Here is a simple example where we have our header and footer in their own template:

header.html

_footer.html:

hello.html:

The sub-templates will also have access to the same model as the main template. So we can access the same data if we need to.

Coming feature: code based templates

The next release of Ratpack, version 0.9.7, will also support another style of template based on Groovy's markup templates.

Instead of template files being text mixed with Groovy snippets they are Groovy code mixed with text snippets. Our template would become:

Summary

Rendering templates with Ratpack is not complicated. We can render simple templates, and templates with dynamic data that is set by the handlers. We can also reuse our templates and compose them.

Ratpack Templates