h1. 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.



h2. <a name="collection">Collection extensions</a>


h3. <a name="join">join(separator)</a>

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

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


h3. <a name="last">last()</a>

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

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


h3. <a name="pluralize">pluralize()</a>

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

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


h3. <a name="pluralize-plural">pluralize(plural)</a>

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

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


h3. <a name="pluralize-singular-plural">pluralize(singular, plural)</a>

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

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



h2. <a name="date">Date extensions</a>


h3. <a name="format">format(format)</a>

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

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


h3. <a name="format-language">format(format, language)</a>

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

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


h3. <a name="since">since()</a>

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

bc. ${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@.  


h3. <a name="since-condition">since(condition)</a>

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.  

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



h2. <a name="long">Long extensions</a>


h3. <a name="asdate">asdate()</a>

Formats a time stamp as a date according to pattern from the I18N Configuration. Returns: @String@ - a formatted date.

bc. ${1275910970000.asdate()}
07 June 2010 01:42:50

h3. <a name="asdate">asdate(format)</a>

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

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


h3. <a name="asdate-language">asdate(format, language)</a>

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

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


h3. <a name="formatSize">formatSize()</a>

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

bc. ${726016L.formatSize()}
709KB




h2. <a name="map">Map extensions</a>


h3. <a name="asAttr">asAttr()</a>

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

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


h3. <a name="asAttr-condition">asAttr(condition)</a>

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

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



h2. <a name="number">Number extensions</a>


h3. <a name="number-divisibleBy">divisibleBy(divisor)</a>

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

bc. ${42.divisibleBy(7)}
true


h3. <a name="number-format">format(format)</a>

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

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


h3. <a name="number-formatCurrency">formatCurrency(currencyCode)</a>

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

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


h3. <a name="number-page">page(pageSize)</a>

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

bc. ${42.page(10)}
5


h3. <a name="number-pluralize">pluralize()</a>

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

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


h3. <a name="number-pluralize-plural">pluralize(plural)</a>

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

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


h3. <a name="number-pluralize-singular-plural">pluralize(singular, plural)</a>

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

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



h2. <a name="object">Object extensions</a>


h3. <a name="addSlashes">addSlashes()</a>

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

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


h3. <a name="capAll">capAll()</a>

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

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


h3. <a name="capFirst">capFirst()</a>

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

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


h3. <a name="cut">cut(substring)</a>

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

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


h3. <a name="escape">escape()</a>

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

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


h3. <a name="nl2br">nl2br()</a>

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

bc. ${"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()":#escape for user input:

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


h3. <a name="raw">raw()</a>

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

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


h3. <a name="raw-condition">raw(condition)</a>

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

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


h3. <a name="yesNo">yesNo('yes', 'no')</a>

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

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


h2. <a name="string">String extensions</a>


h3. <a name="asXml">asXml()</a>

Parses the given XML string. Returns: @groovy.util.slurpersupport.GPathResult@.

h3. <a name="camelCase">camelCase()</a>

Formats the string in camel case, as if for a Java class name. Returns: @String@.

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


h3. <a name="capitalizeWords">capitalizeWords()</a>

Capitalises every word in the string. Returns: @String@.

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


h3. <a name="escapeHtml">escapeHtml()</a>

Escapes reserved HTML characters. Returns: @String@.

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


h3. <a name="escapeJavaScript">escapeJavaScript()</a>

Escapes reserved JavaScript characters. Returns: @String@.

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


h3. <a name="escapeXml">escapeXml()</a>

Escapes reserved XML characters. Returns: @String@.

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


h3. <a name="noAccents">noAccents()</a>

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

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


h3. <a name="pad">pad(length)</a>

Pads the string with @&nbsp;@ up to the given length. Returns: @String@.

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


h3. <a name="slugify">slugify()</a>

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

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


h3. <a name="urlEncode">urlEncode()</a>

Escapes reserved URL query string characters. Returns: @String@.

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


h2. <a name="string-array">String array extensions</a>


h3. <a name="add">add(value)</a>

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

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


h3. <a name="contains">contains(string)</a>

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

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


h3. <a name="remove">remove(string)</a>

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

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


