Freemarkerのリファレンスの使い方でよく使用するものを日本語でまとめ

Freemarkerのリファレンスの中でよく使用するものを日本語で解説。非エンジニアでも下記に書かれている一覧を覚えれば一通りのことはできるはず。

<#-- コメント -->

「<#--」で始め「-->」で閉じるとコメントになりHTMLコードに表示されない。

<#-- コメントが入ります。 -->

<#include>

ファイルを読み込んで表示する

<#include "hoge.ftl">

<#global>

グローバル変数を定義

<#global x = "hoge">

<#assign>

名前空間で有効な変数を定義

<#assign x = "hoge">

<#local>

ローカル変数を定義

<#local x = "hoge">

デフォルト値の設定

変数がundefinedのときに表示する値を指定

${title!"無題"}

?number

数値に型変換

<#assign num = "123"?number>

lt, gt, lte, gte (<, >, <=, >=)

lt は <, gt は >, lte は <=, gte は >= と同じ。記号で不等式を使用するとHTMLタグなどの影響を受けてエラーになることがあるので英字で記述した方が安心。

<#if num lte 123>

function関数を使用（引数の個数が決まっている場合）

<#function kuku num1 num2>
    <#local result = num1 * num2>
    <#return result>
</#function>
${kuku(8, 9)}

【結果】
72

function関数を使用（引数の個数が決まってない場合） 引数に...を付けるのがポイント。

<#function kakezan nums...>
    <#local result = 1>
    <#list nums as num>
        <#local result = result * num>
    </#list>
    <#return result>
</#function>
${kakezan(8, 9, 10)}

【結果】
720

<#macro>

マクロを使用。function関数と違い値を返さない。

<#assign x = "hoge">
<#macro m>
${x} + " " + ${x}
</#macro>
<@m/>

【結果】
hoge hoge

<#list>

配列などの繰り返し処理を行う

<#assign s = ["s1", "s2", "s3", "s4"]>
<#list s as ss>
${ss}<br>
</#list>

【結果】
s1<br>
s2<br>
s3<br>
s4<br>

要素数を指定して2つ目(s2)を表示したい場合

<#assign s = ["s1", "s2", "s3", "s4"]>
${s[1]}

【結果】
s2

?sizeで配列の数を表示

<#assign s = ["s1", "s2", "s3", "s4"]>
${s?size}

【結果】
4

_index

${ss_index}のように変数のうしろに_indexを つけるとインデックスを表示する

<#assign s = ["s1", "s2", "s3", "s4"]>
<#list s as ss>
${ss_index}<br>
</#list>

【結果】
0<br>
1<br>
2<br>
3<br>

<#if>と組み合わせれば3つまでしか表示したくないときにも使える。 ※条件に一致したら<#break>で<#list>から抜け出す。

<#assign s = ["s1", "s2", "s3", "s4"]>
<#list s as ss>
<#if ss_index gt 2><#break></#if>
${ss}<br>
</#list>

【結果】
s1<br>
s2<br>
s3<br>

<if# ss_has_next>で次の配列が存在するか調べて条件分岐が可能。 最後に<br>を付けたく無い場合はこれを利用。

<#assign s = ["s1", "s2", "s3", "s4"]>
<#list s as ss>
${ss}<#if ss_has_next><br></#if>
</#list>

【結果】
s1<br>
s2<br>
s3<br>
s4

逆に最後だけに<br>を付けたい場合は<#if !ss_has_next>になる。 最後にclass="last"を付けたい場合などに有用。

<#assign s = ["s1", "s2", "s3", "s4"]>
<#list s as ss>
${ss}<#if !ss_has_next><br></#if>
</#list>

【結果】
s1
s2
s3
s4<br>

has_content

変数が入っているか調べる

<#assign test = "">
<#if test?has_content>
変数の値あり
<#else>
変数の値なし
</#if>

【結果】
変数の値なし

.now

${.now}で現在の時刻を取得 ifと組み合わせて時間設定を行うときに使用。

<#--【使用例】-->
<#assign timeEnd = "2012-12-03 12:30:00"?datetime("yyyy-MM-dd HH:mm:ss")>
<#if .now gt timeEnd>
設定時間を過ぎています
</#if>

【結果】
設定時間を過ぎています

?lengthで文字数を表示

<#assign s = "テキストが入ります。">
${s?length}

【結果】
10

HTMLをエスケープ

<#-- sの中身は<半角山括弧> -->
${s?html}

【結果】
&lt;半角山括弧&gt;

文字列を置換

<#assign s = 'foo bAr bar bar'>
${s?replace('ba', 'XY')}

【結果】
foo bAr XYr XYr

範囲を指定した文字列を抜き出し

<#assign s = "テキストが入ります。">
${s?substring(0, 5)}

【結果】
テキストが

指定した文字が何文字目か表示

<#assign s = "テキストが入ります。">
${s?index_of("が")

【結果】
4

特定の文字列が含まれているか判定

<#assign s = "テキストが入りますが。">
<#if s?contains("が")>
「が」が入っています。
</#if>

【結果】
「が」が入っています。

指定した配列の値が含まれているか調べる

<#assign s = ["s1", "s2", "s3", "s4"]>
${s?seq_contains("s3")?string("s3を含んでいる", "s3を含んでいない")}

【結果】
s3を含んでいる

最後にある指定した文字が何文字目か調べる

<#assign s = "テキストが入りますが。">
${s?last_index_of("が")}

【結果】
9

Freemarkerのバージョンを調べる

${.version}

【結果】
2.3.18

数字をカンマで区切る

<#assign n = "1234567">
${n?string(",##0.00")}

【結果】
1,234,567

四捨五入、切り下げ、切り上げ

<#assign s = 2.45>
${s?round}<br>
${s?floor}<br>
${s?ceiling}<br>

【結果】
2
2
3

小数点第一位を表示する四捨五入の場合は下記のように一度10倍して四捨五入した後に10で割る関数を作成して使用する。

<#function round num>
    <#local result = (((num * 10)?round) / 10)?string("0.#")>
    <#return result>
</#function>
${round(2.45)}

【結果】
2.5

floor（切り捨て）の場合は下記の書き方でも同様のことが可能

<#assign s = 2.456>
${s?string("0")}<br>
${s?string("0.#")}<br>
${s?string("0.##")}

【結果】
2
2.4
2.45

左右のホワイトスペース削除

(${"    foo bar  "?trim})

【結果】
(foo bar)

<#compress>

タブや半角スペースを削除する。

<#compress>
<ul>
    <li>hoge</li>
    <li>hoge</li> 
    <li>hoge</li>
</ul>
</#compress>

【結果】

<ul>
<li>hoge</li>
<li>hoge</li>
<li>hoge</li>
</ul>

<@compress single_line=true>

タブや半角スペース、改行を削除する。 ※ただし、これを使用すると改行削除後、 代わりに半角スペースが残ってしまう。

<@compress single_line=true>
<ul>
    <li>hoge</li>
    <li>hoge</li>
    <li>hoge</li>
</ul>
</@compress>

【結果】

<ul> <li>hoge</li> <li>hoge</li> <li>hoge</li> </ul>

1行分のホワイトスペースを削除する <#t>を併用すれば半角スペースは完全に除去されるが コードの見栄えが悪くなるので非推奨。

<@compress single_line=true>
<ul><#t>
    <li>hoge</li><#t>
    <li>hoge</li><#t>
    <li>hoge</li><#t>
</ul>
</@compress>

【結果】

<ul><li>hoge</li><li>hoge</li><li>hoge</li></ul>

半角スペース、タブ、改行を正しく削除して表示するには 下記のような関数を作成して使用する必要がある。

<#macro compress_all>
<#local html><#nested></#local>
${html?replace("^\\s+|\\s+$|\\n|\\r", "", "rm")}
</#macro>

<@compress_all>
<ul>
    <li>hoge</li>
    <li>hoge</li>
    <li>hoge</li>
</ul>
</@compress_all>

【結果】

<ul><li>hoge</li><li>hoge</li><li>hoge</li></ul>

備考

• 画像の幅や高さの取得はできない
• 変数にNULLを入れるとエラーになる
• <#if hoge??>はhogeが空文字の時でもtrueになってしまう
• <#if hoge > 5>は>が2重になりエラー。<#if hoge gt 5>を使用する。