Documentation

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

Built-in template tags

These are the standard tags built in the template engine.

There is a separate Java extensions manual page.

a

The a tag inserts an HTML link to a controller action.

#{a @Application.logout()}Disconnect#{/a}

Rendered as:

<a href="/application/logout">Disconnect</a>

If the action you try call does not have any route able to invoke it using a GET method, Play will automatically generate a hidden form that will be submitted on link click using JavaScript.

doLayout

Used with template inheritance, this tag insert the evaluated sub-template’s contents.

<!-- common header here -->
<div id="content">
    #{doLayout /}
</div>
<!-- common footer here -->

else

Of course used with the if tag.

#{if user}
    Connected user is ${user}
#{/if}
#{else}
    Please log in
#{/else}

However, you can also use it with the list tag and it will be executed if the list was empty.

#{list items:task, as:'task'}
    <li>${task}</li>
#{/li}
 
#{else}
    Nothing to do...
#{/else}

elseif

#{if tasks.size() > 1}
    Busy tasklist
#{/if}
 
#{elseif tasks}
    One task on the list
#{/elseif}
 
#{else}
    Nothing to do
#{/else}

As for else, you can use it with the list tag.

errors

Iterates over the current validation errors.

<ul>
#{errors}
    <li>${error}</li>
#{/errors}
</ul>

The tag defines implicit variables in its body.

<table>
<tr><th>#</th><th>Error</th></tr>
#{errors}
    <tr class="${error_parity}"><td>${error_index}</td><td>${error}</td></tr>
#{/errors}
</table>

extends

Makes the template inherit another template.

#{extends 'main.html' /}

field

The field tag is an helper, based on the spirit of the Don’t Repeat Yourself. It works this way:

Instead of writing this:

<p>
  <label>&{'user.name'}</label>
  <input type="text" id="user_name" name="user.name" value="${user?.name}" class="${errors.forKey('user.name') ? 'has_error' : ''}">
  <span class="error">${errors.forKey('user.name')}</span>
</p>

You can just write:

#{field 'user.name'}
<p>
  <label>&{field.name}</label>
  <input type="text" id="${field.id}" name="${field.name}" value="${field.value}" class="${field.errorClass}">
  <span class="error">${field.error}</span>
</p>
#{/}

So you don’t repeat user.name again and again.

form

Inserts a form tag. The HTTP method is guessed from the route, and defaults to POST. If there are both GET and POST routes configured for the URL, the tag will default to using the first route defined in routes.

Charset encoding is always ‘utf-8’.

#{form @Client.create() , id:'creationForm' enctype:'multipart/form-data' }
   ...
#{/form}

Rendered as:

<form action="/client/create" id="frm" method="POST" accept-charset="utf-8" enctype="multipart/form-data">
 ...
</form>

get

Retrieves a value defined with a set tag. You may use the get/set mechanism to exchange values between templates, layouts and sub-templates.

<head>
    <title>#{get 'title' /}
</head>

You can also use the get tag in the following way, which will display “Homepage” if title has not been specified.

<head>
    <title>#{get 'title'}Homepage #{/} 
</head>

i18n

Exports localized messages in JavaScript. Localized messages are available from your JavaScript code using the i18n() function.

Define your translations in the conf/messages file.

hello_world=Hello, World !
hello_someone=Hello %s !

Include the messages in your template (or layout) page:

#{i18n /}

And retrieve keys from JavaScript:

alert(i18n('hello_world'));
alert(i18n('hello_someone', 'John'));

if

Evaluates the given test, and if true, evaluates the tag body.

#{if user.countryCode == 'en"' }
    Connected user is ${user}
#{/if}

Using composite conditions:

#{if ( request.actionMethod == 'administer'  && user.isAdmin() ) }
    You are admin, allowed to administer.
#{/if}

ifnot

Cleaner alternative to #{if !condition}

#{ifnot tasks}
    No tasks today
#{/ifnot}

include

Includes another template. All of the current template’s variables are directly available in the included template.

<div id="tree">
    #{include 'tree.html' /}
</div>

jsAction

The #{jsAction /} tag returns a JavaScript function which constructs a URL based on a server action and free variables. It does not perform an AJAX request; these have to be done by hand using the returned URL.

Let’s see an example:

GET     /users/{id}        Users.show

Now you can import this route client side:

<script type="text/javascript">
    var showUserAction = #{jsAction @Users.show(':id') /}
    
    var displayUserDetail = function(userId) {
        $('userDetail').load( showUserAction({id: userId}) )
    }
</script>

list

Iterates over an object collection.

<ul>
#{list items:products, as:'product'}
    <li>${product}</li>
#{/list}
</ul>

The tag defines implicit variables in its body. The variable names are prefixed with the loop variable name.

<ul>
#{list items:products, as:'product'}
    <span class="${product_parity}">${product_index}. ${product}</span>
    ${product_isLast ? '' : '-'}
#{/list}
</ul>

The items parameter is optional and can be replaced by the default arg argument.

So you can rewrite:

#{list items:users, as:'user'}
    <li>${user}</li>
#{/list}

as:

#{list users, as:'user'}
    <li>${user}</li>
#{/list}

for loops are easy to create using Groovy range object:

#{list items:0..10, as:'i'}
    ${i}
#{/list}

#{list items:'a'..'z', as:'letter'}
    ${letter} ${letter_isLast ? '' : '|' }
#{/list}

The as parameter is optional as well. It uses _ as default variable name:

#{list users}
    <li>${_}</li>
#{/list}

script

Inserts a script tag in the template. By convention, the tag refers to a script in /public/javascripts

The src parameter can be replaced by the default arg argument.

#{script 'jquery-1.4.2.min.js' /}
#{script id:'datepicker' , src:'ui/ui.datepicker.js', charset:'utf-8' /}

set

Define a value which can be retrieve in the same template or any layout with the get tag.

#{set title:'Admin' /}
#{set style:'2columns' /}

You can also use variables:

#{set title:'Profile of ' + user.login /}

You can define variables value in the body:

#{set 'title'}
    Profile of ${user.login}
#{/set}

stylesheet

Inserts a link tag in the template. By convention, the tag refers to a CSS file in /public/javascripts

The src parameter can be replaced by the default arg argument.

#{stylesheet 'default.css' /}
#{stylesheet id:'main', media:'print', src:'print.css', title:'Print stylesheet' /}

verbatim

Disables HTML escaping in template output, like the raw() Java extension, but for the whole tag body.

${'&amp;'}
#{verbatim}${'&amp;'}#{/verbatim}

In this example, the first line outputs &amp; while the second line outputs an ampersand.