埋め込み変数やFTLタグには以下の値を記載することができる。
なお、FTLタグの種類によっては設定できる型が決まっている。
（たとえば<#if hoge>においてhogeはboolean型の必要がある)
" または ' で囲む("Foo", ’Foo')
クォーテーションで囲まれた文字列内でその記号を使いたい場合は \ でエスケープする（”It's \"quote\""）
エスケープの一覧については以下の表を確認。
エスケープしないで出力したい場合、 ｒ”文字列” または r'文字列' と記載する。
文字列の中に、組み込み変数を設定することも可能(”Hello ${message}")
文字列を文字の配列と見なして値を取得することも可能
数値リテラルはそのまま記載することができる(0.08, -5.013, 8, 008, 11, +11)
小数部しかない場合でも0は省略できない（OK：0.5, NG：.5)
+記号、整数部の前0、小数部の後0は省略される(${+8}, ${008}, ${8.00} は ${8} と同じ)
true または false
クォーテーションで囲まない。小文字。
[ と ] で囲んだ中に配列の要素を記載し、要素間は, で区切る([ "spring", "summer", "autumn", "winter" ])
配列内の各要素の型は同じである必要はない。多重配列も可能([2 + 2, [1, 2, 3, 4], "whatnot"])
配列の要素を指定する場合は添え字で指定する(添え字は0から始まる）
start..end のような表記も可能。start は省略できないが、 end を省略した場合は無限にカウント(2..5, 5..2, 5..)
※ノート※
end が省略できるのは、FreeMarker2.3.3以降
{ と } で囲んだ中に配列の要素を key:value 様式で記載し、各要素間は , で区切る({ "name":"hoge", "age":15 })
key は文字列の必要があるが、value は任意の型が使用可能。
以下にFTLの記載例と表示結果を示す。
<h1>${"Hello World!"}</h1><p>2+3=${2 + 3}</p>${r"C:¥user\tools\"}とか表示できます。<br><#list [ "spring", "summer", "autumn", "winter" ] as season> ${season}<br> <#if season == "winter"> いまは冬です<br> </#if></#list><#assgin books = [{"name":"book1", "price":1500}, {"name":"book2", "price":2000}]>${books[1]["name"]}の値段は${books[1]["price"]}円です。<br>FTL
<h1>Hello World!</h1><p>2+3=5</p>C:\user\tools\とか表示できます。<br> spring summer autumn winter いまは冬です<br>book2の値段は2000円です<br>表示結果
以下のようなオブジェクトをFTLで入力パラメータとして使う場合について記載する。
(root) | +- book | | | +- title = "Breeding green mouses" | | | +- author | | | +- name = "Julia Smith" | | | +- info = "Biologist, 1923-1985, Canada" | +- test = "title"
オブジェクトの構造
FreeMarkerではオブジェクトはラップされるため、元のJavaオブジェクトの構造を気にせずに値を取得することができる。
上記で title の内容を出力したい場合、book.title と表記することも可能だし、連想配列とみなしてbook["title"] と表記することもできる。
また、test の内容が "title" なので、 book[test] と記載しても目的の値を取得できる。
さらに配列とみなして book[0] でもOK。
いろいろな取り方ができるので、プロジェクトでは記載方法を統一しないとあとでわけがわからなくなる可能性も・・・
※注意※
組み込み変数は最終的に文字列型に変換される。
したがって埋め込み変数が使用可能な箇所は文字列で表示されるところに限られる。
たとえば、<h1>Hello ${name}!</h1>や、<#include "/footer/${company}.html>といった使い方はできるが
<#if ${isBig}>Wow!</#if>といった使い方はできない。
(isBigが文字列として判定されてしまうため<#if "${isBig}">Wow!</#if>と同じ意味になる)
FTLタグ内で変数として使用する場合は${ } で囲わずに<#if isBig>Wow!</#if>のように記載すること。
文字列の連結は + 演算子で可能。
文字列リテラルに埋め込むこともできる。
以下はすべて同じ結果になる(userには"Hoge Fuga"が設定されていると仮定) 。
Hello ${user}!${"Hello" + ${user} + "!"}${"Hello ${user}!"}FTL
Hello Hoge Fuga!Hello Hoge Fuga!Hello Hoge Fuga!表示結果
FreeMarkerでは、文字列は文字(char)の配列とみなすこともできる。
そのため、部分文字列を配列と同じように取得することも可能(userには"Hoge Fuga"が設定されていると仮定) 。
${user[0]}${user[5]}${user[1..3]}${user[6..]}FTL
HFogeuga表示結果
上記で説明したように、文字列型以外のオブジェクトは最終的に文字列型に変換される。
変換される文字列の内容は、内部的にはObject#toString()。
日付型など、フォーマットを指定して文字列型に置換したい場合には、string ビルドインを使用する(ビルドインについてはこちらで説明)
配列の連結は + 演算子で可能。
連結自体は高速だが、連結結果の配列に関してはリードが少し遅くなる。
何度も結合すると個々にループするよりもかなり遅くなるので使用には注意すること。
部分配列は文字列と同じように [start..end] (or [start..] ) で取得する。
ハッシュの連結は文字列と同じように + 演算子で可能。
連結したハッシュに同じキーが設定されている場合は、+ 演算子の右側のハッシュの値が優先される。
以下の例を参照。
<#assign ages = {"Joe":23, "Fred":25} + {"Joe":30, "Julia":18}> - Joe is ${ages.Joe}- Fred is ${ages.Fred}- Julia is ${ages.Julia}FTL
- Joe is 30- Fred is 25- Julia is 18表示結果
数値型のオブジェクトに関しては、以下の演算が可能。
四則演算の優先順位により、加減算よりも乗除残のほうが先に計算される。
${100 - x * x}${x / 2}${12 % 10}FTL
x が5だった場合は、以下のような結果になる。
752.52計算結果
数値型オブジェクトと文字列型オブジェクトを算術演算させることはできない。
${2 * "5"} <#-- WRONING! -->FTL
FreeMarkerでは文字列型⇒数値型への変換は自動的に行われないが、
数値型⇒文字列型への変換は暗黙的に行われる。
たとえば、+ 演算子を使用した場合、数値型オブジェクトが文字列に変換され、文字列連結される。
${2 + "5"} FTL
25計算結果
実数を整数に変換したい場合などは、int ビルドインを利用する(ビルドインについてはこちらで説明)
FTL内で条件を比較して出力内容を変更したい場合は、if タグを利用して以下のように記載する(FTLタグの詳細はこちらで説明)。
<#if expression>...</#if> （ここで expression は条件式を表す）
条件式の結果はboolean型になる必要がある（それ以外の場合はエラーになる）。
条件式がtureの場合のみ、開始タグと終了タグの間の内容が判定される（タグ間に任意のFTL構文を表記可能）。
比較演算子の一覧は下記の表を確認。
FreeMarkerでは、オブジェクトがnullの場合に簡単にチェックできたり、デフォルト値に変換したりする仕組みがある。
※ノート※
以下のシノニムが使用できるのはFreeMarker2.3.7以降
オブジェクトの後ろに!default_exprを記載することで、値がnullの場合のデフォルト値を指定できる。
codeがnullの場合、デフォルトコード("default code")を表示するには
${code!"default code"}FTL
default code計算結果