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

Java extensions

Java extensions add convenience methods to objects for use in view templates, making expressions more expressive.

The code examples show an example template expression, with its result on the next line.

Collection extensions

join(separator)

Concatenates the collection’s entries, with the given separator between each entry. Returns: String.

${['red', 'green', 'blue'].join('/')}
red/green/blue

last()

Returns the last item in the list. Returns: Object.

${['red', 'green', 'blue'].last()}
blue

pluralize()

Returns an ‘s’ when the collection’s size is not 1. Returns: String.

colour${['red', 'green', 'blue'].pluralize()} 
colours

pluralize(plural)

Returns the given plural when the collection’s size is not 1. Returns: String.

box${['red', 'green', 'blue'].pluralize('es')}
boxes

pluralize(singular, plural)

Returns the given plural form when the collection’s size is not 1; returns the given singular form when it is 1. Returns: String.

journ${['red'].pluralize('al', 'aux')}
journal
 
journ${['red', 'green', 'blue'].pluralize('al', 'aux')}
journaux

Date extensions

format(format)

Formats the date using the given date format pattern. Returns: String.

${new Date(1275910970000).format('dd MMMM yyyy hh:mm:ss')}
07 June 2010 01:42:50

format(format, language)

Formats the date using the given date format pattern, in the given language. Returns: String.

${new Date(1275910970000).format('dd MMMM yyyy hh:mm:ss', 'fr')}
07 juin 2010 01:42:50

since()

Formats the date as a relative time, compared to now, e.g. 3 minutes ago. Returns: String.

${new Date(new Date().getTime() - 1000000).since()}
16 minutes ago

You can customise the output using the following messages: since.seconds, since.minutes, since.hours, since.days, since.months and since.years.

since(condition)

Formats the date as a relative time, compared to now. If the condition is true, dates more than one month ago are formatted as a date. Returns: String.

You can customise the output using the same messages as for since(), as well as since.format for dates more than one month ago.

${new Date(1262350000000).since(false)}
5 months ago
 
${new Date(1262350000000).since(true)}
Jan 1, 2010

Long extensions

asdate(format)

Formats a time stamp as a date. Returns: String - a formatted date.

${1275910970000.asdate('dd MMMM yyyy hh:mm:ss')}
07 June 2010 01:42:50

asdate(format, language)

Formats a time stamp as a date, in the given language. Returns: String - a formatted date.

${1275910970000.asdate('dd MMMM yyyy hh:mm:ss', 'fr')}
07 juin 2010 01:42:50

formatSize()

Formats a number of bytes as a file size, with units.

${726016L.formatSize()}
709KB

Map extensions

asAttr()

Formats the map’s keys and values as HTML attributes. Returns: play.templates.Template.ExecutableTemplate.RawData.

${[id:'42', color:'red'].asAttr()}
id="42" color="red"

asAttr(condition)

Formats the map’s keys and values as HTML attributes, if the condition is true. Returns: play.templates.Template.ExecutableTemplate.RawData.

${[id:'42', color:'red'].asAttr(true)}
id="42" color="red"

Number extensions

divisibleBy(divisor)

Returns true if the number is divisible by the given number – the divisor. Returns: boolean.

${42.divisibleBy(7)}
true

format(format)

Formats the number using the given number format pattern. Returns: String.

${42.format('000.00')}
042.00

formatCurrency(currencyCode)

Formats the number as a currency for the given currency code, e.g. EUR. Returns: String.

${42.formatCurrency('EUR').raw()}
&euro; 42.00

page(pageSize)

Returns the page number, for the given page size, from interpreting the number as an index. Returns: Integer.

${42.page(10)}
5

pluralize()

Returns an ‘s’ when the number is not 1. Returns: String.

colour${['red', 'green', 'blue'].pluralize()} - colour${3.pluralize()} 
colours - colours

pluralize(plural)

Returns the given plural when the number is not 1. Returns: String.

box${3.pluralize('es')}
boxes

pluralize(singular, plural)

Returns the given plural form when the number is not 1; returns the given singular form when it is 1. Returns: String.

journ${1.pluralize('al', 'aux')}
journal
 
journ${3.pluralize('al', 'aux')}
journaux

Object extensions

addSlashes()

Backslash-escapes Java-escaped single and double quotes in the object’s String representation. Returns: String.

${"single quote (')".addSlashes().raw()} ${'double quote (")'.addSlashes().raw()}
single quote (\') double quote (\")

capAll()

Capitalises every word in the object’s String representation. Returns: String.

${"lorum ipsum dolor".capAll()}
Lorum Ipsum Dolor

capFirst()

Capitalises the first word in the object’s String representation. Returns: String.

${"lorum ipsum dolor".capFirst()}
Lorum ipsum dolor

cut(substring)

Removes occurrences of the given sub-string. Returns: String.

${"lorum ipsum dolor".cut('um')}
lor ips dolor

escape()

Escapes reserved HTML characters in the object’s String representation. Returns: String.

${"The <blink>tag</blink> is evil".escape().raw()}
The &lt;blink&gt;tag&lt;/blink&gt; is evil

nl2br()

Replaces new-line characters with HTML br tags. Returns: String.

${"one\ntwo".nl2br()}
one<br/>two

Note that the output is not HTML-escaped, so that the br tag is not escaped in the output. This means that you probably want to use escape() for user input:

${userInput.escape().nl2br()}

raw()

Returns the object without template escaping. Returns: play.templates.Template.ExecutableTemplate.RawData.

${'<'}
&lt;
 
${'<'.raw()}
<

raw(condition)

Returns the object without template escaping, if the condition is true. Returns: play.templates.Template.ExecutableTemplate.RawData.

${'<'.raw(true)}
<

yesNo(‘yes’, ‘no’)

Returns the first parameter (‘yes’) if the object evaluates to true, or the second parameter (‘no’) otherwise. Returns: String.

${"".yesno('yes', 'no')}
no
 
${"not empty".yesno('yes', 'no')}
yes

${"lorum ipsum dolor".camelCase()}
LorumIpsumDolor

capitalizeWords()

Capitalises every word in the string. Returns: String.

${"lorum ipsum dolor".capitalizeWords()}
Lorum Ipsum Dolor

escapeHtml()

Escapes reserved HTML characters. Returns: String.

${"The <blink>tag</blink> is evil".escapeHtml().raw()}
The &lt;blink&gt;tag&lt;/blink&gt; is evil

escapeJavaScript()

Escapes reserved JavaScript characters. Returns: String.

${"single quote (') double quote (\")".escapeJavaScript().raw()}
single quote (\') double quote (\")

escapeXml()

Escapes reserved XML characters. Returns: String.

${"<>\"&".escapeXml().raw()}
&lt;&gt;&quot;&amp;

noAccents()

Removes accents from the letters in the string. Returns: String.

${"Stéphane Épardaud".noAccents()}
Stephane Epardaud

pad(length)

Pads the string with   up to the given length. Returns: String.

${"x".pad(4).raw()}
x&nbsp;&nbsp;&nbsp;

slugify()

Formats the string as a ‘slug’ for use in URLs, that avoids reserved URL path characters. Returns: String.

${"The Play! framework’s manual".slugify()}
the-play-framework-s-manual

urlEncode()

Escapes reserved URL query string characters. Returns: String.

${"!@#\$%^&()".urlEncode()}
%21%40%23%24%25%5E%26%28%29

String array extensions

add(value)

Adds value to the end of the array. Returns: String[].

${(["red", "green", "blue"] as String[]).add('pink').join(' ')}
red green blue pink

contains(string)

Returns true if the array contains the given string. Returns: boolean.

${(['red', 'green', 'blue'] as String[]).contains('green')}
true

remove(string)

Returns the array, with the given string removed. Returns: String[].

${(['red', 'green', 'blue'] as String[]).remove('green').join(' ')}
red blue