Template engines

Templates consist of Groovy code. Let’s explore the first example more thoroughly:

As you can see, regular Groovy code can be used in the template. Here, we are calling each on a list (retrieved from the model), allowing us to render one car tag per entry.

In a similar fashion, rendering HTML code is as simple as this:

The output is straightforward:

In the previous example, the doctype declaration was rendered using the yieldUnescaped method. We have also seen the xmlDeclaration method. The template engine provides several support methods that will help you render contents appropriately:

The MarkupTemplateEngine supports inclusion of contents from another file. Included contents may be:

Including another template can be done using:

Including a file as raw contents, without escaping it, can be done like this:

Eventually, inclusion of text that should be escaped before rendering can be done using:

Alternatively, you can use the following helper methods instead:

Calling those methods instead of the include xxx: syntax can be useful if the name of the file to be included is dynamic (stored in a variable for example). Files to be included (independently of their type, template or text) are found on classpath. This is one of the reasons why the MarkupTemplateEngine takes an optional ClassLoader as constructor argument (the other reason being that you can include code referencing other classes in a template).

If you don’t want your templates to be on classpath, the MarkupTemplateEngine accepts a convenient constructor that lets you define the directory where templates are to be found.

Fragments are nested templates. They can be used to provide improved composition in a single template. A fragment consists of a string, the inner template, and a model, used to render this template. Consider the following template:

The fragment element creates a nested template, and renders it with a model which is specific to this template. Here, we have the li(line) fragment, where line is bound to it. Since it corresponds to the iteration of pages, we will generate a single li element for each page in our model:

Fragments are interesting to factorize template elements. They come at the price of the compilation of a fragment per template, and they cannot be externalized.

Layouts, unlike fragments, refer to other templates. They can be used to compose templates and share common structures. This is often interesting if you have, for example, a common HTML page setup, and that you only want to replace the body. This can be done easily with a layout. First of all, you need to create a layout template:

Then what you need is a template that includes the layout:

As you can see, bodyContents will be rendered inside the layout, thanks to the bodyContents() call in the layout file. As a result, the template will be rendered as this:

The call to the contents method is used to tell the template engine that the block of code is in fact a specification of a template, instead of a helper function to be rendered directly. If you don’t add contents before your specification, then the contents would be rendered, but you would also see a random string generated, corresponding to the result value of the block.

Layouts are a powerful way to share common elements across multiple templates, without having to rewrite everything or use includes.

Layouts use, by default, a model which is independent from the model of the page where they are used. It is however possible to make them inherit from the parent model. Imagine that the model is defined like this:

and the following template:

then it is not necessary to pass the title value to the layout as in the previous example. The result will be:

But it is also possible to override a value from the parent model:

then the output will be:

On the server side, rendering templates require an instance of groovy.text.markup.MarkupTemplateEngine and a groovy.text.markup.TemplateConfiguration:

There are several possible options to parse templates:

The last version should in general be preferred:

The behavior of the engine can be tweaked with several configuration options accessible through the TemplateConfiguration class:

By default, the template engine will render output without any specific formatting. Some configuration options can improve the situation:

In general, it is recommended to set both autoIndent and autoNewLine to true if you want human-readable, pretty printed, output:

Using the following template:

The output will now be:

We can slightly change the template so that the title instruction is found on the same line as the head one:

And the output will reflect that:

New lines are only inserted where curly braces for tags are found, and the insertion corresponds to where the nested content is found. This means that tags in the body of another tag will not trigger new lines unless they use curly braces themselves:

This time, the output will be:

By default, the renderer uses four(4) spaces as indent, but you can change it by setting the TemplateConfiguration#autoIndentString property.

By default, contents which is read from the model is rendered as is. If this contents comes from user input, it can be sensible, and you might want to escape it by default, for example to avoid XSS injection. For that, the template configuration provides an option which will automatically escape objects from the model, as long as they inherit from CharSequence (typically, `String`s).

Let’s imagine the following setup:

and the following template:

Then you wouldn’t want the HTML from unsafeContents to be rendered as is, because of potential security issues:

Automatic escaping will fix this:

And now the output is properly escaped:

Note that using automatic escaping doesn’t prevent you from including unescaped contents from the model. To do this, your template should then explicitly mention that a model variable should not be escaped by prefixing it with unescaped., like in this example:

The template engine has native support for internationalization. For that, when you create the TemplateConfiguration, you can provide a Locale which is the default locale to be used for templates. Each template may have different versions, one for each locale. The name of the template makes the difference:

When a template is rendered or included, then:

For example, imagine the default locale is set to Locale.ENGLISH and that the main template includes:

then the template is rendered using the specific template:

Using an include without specifying a locale will make the template engine look for a template with the configured locale, and if not, fallback to the default, like here:

However, changing the default locale of the template engine to Locale.FRANCE will change the output, because the template engine will now look for a file with the fr_FR locale:

This strategy lets you translate your templates one by one, by relying on default templates, for which no locale is set in the file name.

By default, templates created inherit the groovy.text.markup.BaseTemplate class. It may be interesting for an application to provide a different template class, for example to provide additional helper methods which are aware of the application, or customized rendering primitives (for HTML, for example).

The template engine provides this ability by setting an alternative baseTemplateClass in the TemplateConfiguration:

The custom base class has to extend BaseClass like in this example:

This example shows a class which provides an additional method named hasModule, which can then be used directly in the template:

Even if templates are not type checked, they are statically compiled. This means that once the templates are compiled, performance should be very good. For some applications, it might be good to make sure that templates are valid before they are actually rendered. This means failing template compilation, for example, if a method on a model variable doesn’t exist.

The MarkupTemplateEngine provides such a facility. Templates can be optionally type checked. For that, the developer must provide additional information at template creation time, which is the types of the variables found in the model. Imagine a model exposing a list of pages, where a page is defined as:

Then a list of pages can be exposed in the model, like this:

A template can use it easily:

Without type checking, the compilation of the template succeeds, because the template engine doesn’t know about the model until a page is actually rendered. This means that the problem would only surface at runtime, once the page is rendered:

In some situations, this can be complicated to sort out or even notice. By declaring the type of the pages to the template engine, we’re now capable of failing at compile time:

This time, when the template is compiled at the last line, an error occurs:

This means that you don’t need to wait for the page to be rendered to see an error. The use of createTypeCheckedModelTemplate is mandatory.

Alternatively, if the developer is also the one who writes the templates, it is possible to declare the types of the expected variables directly in the template. In this case, even if you call createTemplate, it will be type checked:

An additional interest of using type checked models is that performance should improve. By telling the type checker what are the expected types, you also let the compiler generate optimized code for that, so if you are looking for the best performance, consider using type checked templates.