わかりやすいテンプレートのために - 省略記法のご紹介

省略記法とは

DocurainではExcelテンプレートに差し込みたいデータの位置をプレースホルダーとして記述し、差し込むデータをJSON形式*1で定義します。省略記法はそのJSONのキーにマルチバイト文字を設定する・したい場合に便利な機能です。

{
    "名前": "山本　太郎",
    "生年月日": "1990-10-10",
    "住所": "東京都台東区XXXXXXXXXXXXXXX",
    "商品リスト": [
        {
            "商品名": "AAA",
            "単価": "1000",
            "数量": "1"
        },
        {
            "商品名": "BBB",
            "単価": "500",
            "数量": "3"
        }
    ],
    "備考": "ＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸＸ"
}

さて、このようなJSONの場合に、Docurainが準拠しているVelocityの文法では、マルチバイトのプロパティ名を使用できません。つまり ${ENTITY.名前}と書けず、以下のように${ENTITY['名前']}と書く必要があり冗長です。

ここで省略記法を用いると以下のように簡潔に%{名前}と記述することができます。

#with([コンテキストオブジェクト])または#WITH([コンテキストオブジェクト])を使用することで、省略記法の起点となるオブジェクトを指定し、そのオブジェクトのプロパティ参照を簡潔に%{名前}のように記述できるようになります。

省略記法の起点となるオブジェクトを指定する

初期状態で$ENTITYは省略記法の起点となるオブジェクト（以降コンテキストオブジェクト）として#WITHで指定済みです。
つまりサンプルの"名前"や"生年月日"のようなプロパティを#WITHの記述無しに%{名前}、%{生年月日}で指定可能です。

コンテキストオブジェクトの指定には、大文字の#WITHと小文字の#withの2種類があります。

#WITH	グローバルな設定でありブロック命令のスコープは考慮されません。
#with	ブロック内のみ有効であり、スコープを抜けると外側の`#with(...)`の指定に戻ります。

使用例

#WITHを使ったテンプレートサンプル

このように#foreachブロック内で商品リストの各エントリを#WITHで指定すると、エントリ内プロパティを%{商品名}や%{単価}のように簡潔に書けます。
#WITHはグローバルな設定のため、この#foreachブロック後の14行目以降でのコンテキストオブジェクトは最後の#WITH()の呼び出し、すなわち商品リストの最後のエントリです。
よって、%{備考}で出力するためには14行目で再度#WITH($ENTITY)と記述する必要があり面倒です。

このような場合に、#withを使うことで上記の様に再度#WITH($ENTITY)をする必要がなくなります。

#withを使ったテンプレートサンプル