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

組込みテンプレートタグ

以下は、中心となるテンプレートエンジン構文に従うことで利用できる、組み込みのタグです。

こことは別に Java エクステンションマニュアルページがあります。

a

a タグはコントローラのアクションへの HTML リンクを挿入します。

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

以下のようにレンダリングされます:

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

もし呼び出そうとしているアクションが GET メソッドを使用して起動するどんなルートも持たない場合、Play は自動的に、リンクをクリックしたときに JavaScript を使ってサブミットする隠しフォームを生成します。

authenticityToken

どのフォームでも使用できる、生成されたトークンを含む hidden input フィールドをレンダリングします。クロスサイトリクエストフォージェリの段落を参照してください。

#{authenticityToken /}

以下のようにレンダリングされます:

<input type="hidden" name="authenticityToken" value="1c6d92fed96200347f06b7c5e1a3a28fa258ef7c">

cache

タグパラメータにキャッシュのキーを指定し、 play.cache.Cache API を使ってタグの内容をキャッシュします。

#{cache 'startTime'}
   ${new java.util.Date()}
#{/cache}

デフォルトでは、タグの内容は永久にキャッシュされますが、 for パラメータで有効期間を指定することができます。

#{cache 'currentTime', for:'3s'}
   ${new java.util.Date()}
#{/cache}

doLayout

このタグは、テンプレート継承と共に使用し、評価された子テンプレートの内容を挿入します。

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

else

当然、 if タグと共に使用されます。

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

一方で、 list タグと共に使用することも可能であり、list が空の場合に実行されます。

#{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}

else と同様に、 listタグと共に使用することも可能です。

error

入力エラーが存在する場合に、タグパラメータでフィールドを指定して、エラーメッセージを出力します。

#{error 'user.name'/}

オプションの field パラメータを使って、違うフィールドのエラーメッセージを使用することができます。これは、複数のフィールドで共通のエラーメッセージを共有する場合に便利です。

#{error 'contact.street',  field:'contact.address'/}
#{error 'contact.city',    field:'contact.address'/}
#{error 'contact.country', field:'contact.address'/}

errorClass

タグパラメータで指定したフィールドに入力エラーがある場合に hasError という文字列を出力します。これは、エラーがある入力フィールドに対する CSS クラスを設定する場合に便利です。

<input name="name" class="#{errorClass 'name'/}">

これは、以下と等価です:

<input name="name" class="${errors.forKey('name') ? 'hasError' : ''}">

errors

現在のバリデーションエラーをくり返します。

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

このタグはボディに暗黙的な変数を定義します。

error, エラーです
error_index, エラーの index で、1 から始まります
error_isLast, 最後の要素の場合に true になります
error_isFirst, 最初の要素の場合に true になります
error_parity, odd と even が交互に値になります

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

extends

そのテンプレートに、他のテンプレートを継承させます。

#{extends 'main.html' /}

field

field タグは Don’t Repeat Yourself の精神に基づいたヘルパです。このタグは次のようにして動作します:

以下のように書く代わりに:

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

以下のように書くことができます:

#{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>
#{/}

何度も何度も user.name をくり返してはいけません。

form

form タグを挿入します。HTTP メソッドはルートから推測され、デフォルトは POST です。指定した URL に対して GET と POST の両方が設定されている場合、このタグはデフォルトでは最初に routes に定義されているものを使用します。

オプションの id 属性は、form 要素に id を設定します。
オプションの enctype 属性は、フォームのデータエンコーディングを設定します。デフォルトは ‘application/x-www-form-urlencoded’ です。

文字セットエンコーディングは常に ‘utf-8’ です。

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

以下のようにレンダリングされます:

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

get

set タグで定義された値を検索します。get/set メカニズムを使うことで、テンプレート間、すなわちレイアウトと子テンプレート間で値をやり取りすることができます。

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

以下のように、title が指定されていない場合には “Homepage” を表示するような方法で、このタグを使用することもできます。

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

i18n

ローカライズされた Javascript メッセージを外部化します。ローカライズされたメッセージは i18n() 関数を使うことで JavaScript から利用することができます。

conf/messages ファイルに訳語を定義してください。

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

テンプレート (またはレイアウト) ページにメッセージを取り込んでください:

#{i18n /}

そして JavaScript からキーを使って検索してください:

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

if

指定された条件を評価し、true の場合はタグボディを評価します。

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

条件を組み合わせて使用する場合は、以下のようにします:

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

ifError

対応する入力項目がエラーである場合、タグの内容がレンダリングされます。

#{ifError 'user.name'}
  <p>
    User name is invalid: 
    #{error 'user.name' /}
  <p>
#{/ifError}

ifErrors

バリデーションエラーが発生している場合、タグの内容がレンダリングされます。

#{ifErrors}
  <p>Error(s) found!</p>
#{/ifErrors}

ifnot

きれいに #{if !condition} を書き換えます。

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

include

別のテンプレートを取り込みます。取り込み側のテンプレート上の全ての変数は、取り込んだ側のテンプレートにて直接利用することができます。

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

jsAction

この #{jsAction /} タグは、サーバアクションに基づいた URL と自由な変数から成る JavaScript 関数を返却します。この関数では AJAX リクエストを行わないので、返却された URL を使って手作業で Ajax リクエストを実行する必要があります。

例を見てみましょう:

GET     /users/{id}        Users.show

クライアント側でこのルートをインポートすることができます:

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

list

オブジェクトのコレクションをくり返します。

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

このタグは、ボディに暗黙的な変数を定義します。変数名には、接頭辞としてループ変数名が付きます。

name_index, アイテムの index で、1 から始まります
name_isLast, 最後の要素の場合に true になります
name_isFirst, 最初の要素の場合に true になります
name_parity, odd と even が交互に値になります

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

items パラメータはオプションであり、デフォルトの arg 引数で置き換えることが可能です。

このため:

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

を、以下のように書き換えることができます:

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

Groovy の range オブジェクトを使うことで、容易に for ループを作ることができます:

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

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

as パラメータもまたオプションです。デフォルト変数名として _ を使用します:

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

option

テンプレートに option タグを挿入します。

value - option の値

#{option user.id} ${user.name} #{/option}

これは、以下のように出力されるでしょう:

<option value="42">jto</option>h2. <a name="script">script</a>

テンプレートに script タグを挿入します。利便性のため、このタグは /public/javascripts 内のスクリプトを参照します。

src (必須) - /public/javascripts パスを含まないスクリプトファイル名
id (オプション) - 生成された script タグの id 属性の値
charset (オプション) - ソースのエンコーディングを設定します - デフォルトは UTF-8 です

src パラメータはデフォルトの arg 引数に置き換えることもできます。

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

render

タグパラメータでパスを指定してテンプレートをレンダリングします。パスは絶対パスか、または /app/views に対する相対パスです。

#{render 'Application/other.html'/}

select

テンプレートに select タグを挿入します。

name (必須) - select 要素に name 属性を設定する

不明な属性はすべて HTML 要素として取り扱われ、“そのまま” レンダリングされます。

#{select 'booking.beds', value:2, id:'select1'}
	#{option 1}One king-size bed#{/option}
	#{option 2}Two double beds#{/option}
	#{option 3}Three beds#{/option}
#{/select}

これは、以下のように出力されるでしょう:

<select name="booking.beds" size="1" id="select1" >
  <option value="1">One king-size bed</option>
  <option value="2" selected="selected">Two double beds</option>
  <option value="3">Three beds</option>
</select>

このタグは items 属性を使って options を生成することもできます。

items (オプション) - options を作成するために使われるオブジェクトのリスト
value (オプション) - items の中の選択された要素
labelProperty (オプション) - それぞれのアイテムについて option のラベルとして使用される属性
valueProperty (オプション) - それぞれのアイテムについて option の値として使用される属性。デフォルトは id

例えば、いずれも name 属性を持つ User のリストが与えられているとして:

#{select 'users', items:users, valueProperty:'id', labelProperty:'name', value:'User-5', class:"test", id:'select2' /}

これは、以下のように出力されるでしょう:

<select name="users" size="1" class="test" id="select2" >
  <option value="0" >User-0</option>
  <option value="1" >User-1</option>            
  <option value="2" >User-2</option>            
  <option value="3" >User-3</option>
  <option value="4" >User-4</option>
  <option value="5" selected="selected">User-5</option>
</select>

set

同じテンプレートかレイアウトにおいて get タグを使って検索できる値を定義します。

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

変数を使用することも可能です:

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

変数の値をボディ内で定義することも可能です:

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

stylesheet

テンプレートに link タグを挿入します。利便性のため、このタグは /public/stylesheets 内の CSS ファイルを参照します。

src (必須) - /public/stylesheets パスを含まないファイル名
id (オプション) - 生成された link タグの id 属性の値
media (オプション) - media 属性の値: screen, print, aural, projection…
title (オプション) - title 属性の値 (または説明)

src パラメータはデフォルトの arg 引数に置き換えることもできます。

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

verbatim

Java 拡張の raw() のように、しかしタグボティ全体のテンプレート出力における HTML エスケープを無効にします。

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

この例の場合、最初の行は & を出力しますが、二番目の行はアンパサンドを出力します。