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.

If you search about available standard Java extensions, you should look at the JavaDoc

a

The a tag inserts a 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 an hidden form that will be submitted on link click using javascript.

doLayout

Used with template inheritance, this tag insert the content of the evaluated sub-template.

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

extends

Make the template inherit another template.

#{extends 'main.html' /}

form

Insert a form tag. HTTP method is guessed from the route, and defaults to POST.

Optional id attribute sets an id to the form element.
Optional enctype attribute sets the form’s data encoding. it defaults to '‘application/x-www-form-urlencoded’'.

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

Retrieve 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>

i18n

Export 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'));

include

Include another template. All variable of the current template are directly availables in the included template.

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

if

Evaluate the given test, and if true, evaluate 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
#{/if}

else

Of course used with the if tag.

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

However, you can use it also 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.

list

Iterate over an object collection.

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

The tag define implicit variables in his 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>

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}

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}

jsRoute

The #{jsRoute /} tag allow to import a server-side defined route as a Javascript function. It is very useful if you need to call an URL with an AJAX call using free variables.

Let’s see an example:

GET     /users/{id}        Users.show

Now you can import this route client side:

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