Documentation

Browse versions

Browse APIs

Language

Browse

Contents

Books

You are viewing the documentation for Play 1. The documentation for Play 2 is here.

The template engine

Play has an efficient templating system which allows to dynamically generate HTML, XML, JSON or any text-based formatted document. The template engine uses Groovy as an expression language. A tag system allows you to create reusable functions.

A template file is a text file, some parts of which have placeholders for dynamically generated content. The template’s dynamic elements are written using the Groovy language. Groovy’s syntax is very close to Java’s.

Dynamic elements are resolved during template execution. The rendered result is then sent as part of the HTTP response.

Expressions: ${…}

The simplest way to make a dynamic element is to declare an expression. The syntax used here is ${…}. The result of evaluating the expression is inserted in place of the expression.

For example:

<h1>Client ${client.name}</h1>

If you can’t be sure of client being null, there is a Groovy shortcut:

<h1>Client ${client?.name}</h1>

Which will only display the client name if the client is not null.

Template decorators : #{extends /} and #{doLayout /}

Decorators provide a clean solution to share a page layout (or design) across several templates.

Use #{get} and #{set} tags to share variables between the template and the decorator.

You can easily create specific tags for your application. A tag is a simple template file, stored in the app/views/tags directory. The template’s file name is used as the tag name.

To create a hello tag, just create the app/views/tags/hello.html file.

Hello from tag!

No need to configure anything. You can use the tag directly:

#{hello /}

Retrieve tag parameters

Tag parameters are exposed as template variables. The variable names are constructed with the ‘_’ character prepended to the parameter name.

For example:

Hello ${_name} !

And you can pass the name parameter to the tag:

#{hello name:'Bob' /}

If your tag has only one parameter, you can use the fact than the default parameter name is arg and that its name is implicit.

Example:

Hello ${_arg}!

And you can call it easily using:

#{hello 'Bob' /}

Invoke tag body

If your tag supports a body, you can include it at any point in the tag code, using the doBody tag.

For example:

Hello #{doBody /}!

And you can then pass the name as tag body:

#{hello}
Bob
#{/hello}

Format-specific tags

You can have different versions of a tag for different content types and Play will select the appropriate tag. For example, Play will use the app/views/tags/hello.html tag when request.format is html, and app/views/tags/hello.xml when the format is xml.

Whatever the content type, Play will fall back to the .tag extension if a format-specific tag is not available, e.g. app/views/tags/hello.tag.

You can also define custom tags in Java code. Similarly to how JavaExtensions work by extending the play.templates.JavaExtensions class, to create a FastTag you need to create a method in a class that extends play.templates.FastTags. Each method that you want to execute as a tag must have the following method signature.

This code works by outputting an HTML option tag, and sets the selected value by checking which value is selected from the parent tag. The first three lines set variables for use in the output output. Then, the final three lines output the result of the tag.

There are many more examples in the source code for the built in tags, with varying degrees of complexity. See FastTags.java in github.

Tag namespaces

To ensure that your tags do not conflict between projects, or with the core Play tags, you can set up namespaces, using the class level annotation @FastTags.Namespace.

So, for a hello tag, in a my.tags namespace, you would do the following