Docurain Labo

Docurainサービス開発日記

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

省略記法とは

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

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

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

https://s3.ap-northeast-1.amazonaws.com/site.docurain.jp/blog/2020/08/with_blog_1.png

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

https://s3.ap-northeast-1.amazonaws.com/site.docurain.jp/blog/2020/08/with_blog_2.png

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

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

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

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

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

使用例

#WITHを使ったテンプレートサンプル https://s3.ap-northeast-1.amazonaws.com/site.docurain.jp/blog/2020/08/with_blog_3.png

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

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

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

https://s3.ap-northeast-1.amazonaws.com/site.docurain.jp/blog/2020/08/with_blog_4.png

このように#foreachブロック内で商品リストの各エントリを#with(ブロック内のみ有効)で指定すると #foreachブロック外のコンテキストオブジェクトは初期状態の$ENTITYのままです。

こちらの方がずっとわかりやすいですね。

今回作成したサンプルは、無料トライアルページからも登録不要で試してみることが出来ます。

他にも様々な機能がありますので、ぜひアカウント無料登録してマニュアルを参照しお試しください。

*1:CSV, TSVも可