Docurain Labo

Docurainサービス開発日記

Docurainを理解するために知って欲しいApache Velocityの構文

Docurainでは帳票を生成する際にApache Velocity(以下単にVelocity)というライブラリを利用しています。VelocityはJavaで開発されたテンプレートエンジンになります。テンプレートエンジンというのはテンプレートファイルと、データを組み合わせて別なファイルを生成する仕組みになります。つまりDocurainの場合は次のようになります。

f:id:moongift:20220125133910p:plain

今回はこのVelocityについて、Docurainで利用されている機能について解説します。Velocityを知ることで、Docurainの動作原理を知り、よりテンプレート作成がはかどることでしょう。

DocurainでのApache Velocityの利用法

DocurainではA列を必ず空ける必要があります。このA列はVelocityに即したロジックを記述する列になります。Docurainのシステムでは、テンプレートファイルのA列を参照してロジックを実行します。

変数の定義

以下はVelocityの公式サイトにあるHTMLテンプレートの例です。

<html>
  <body>
  #set( $foo = "Velocity" )
  Hello $foo World!
  </body>
</html>

この時の #set() 構文が変数の定義になります。変数名は必ず $ をつける必要があります。

#set($変数名 = "値")

Docurainはデフォルトで $ROOT という変数が定義されています。この変数にはテンプレートに渡されたJSON(またはCSV)データが入ります。 $ROOT だと長いので、以下のようにA1セルに記述して $e でアクセスできるようにすると便利です。

#set($e = $ROOT)

値のデフォルト値を設定する

#set を使ったときに、値が存在しない場合もあるでしょう。そうした時にはデフォルト値を指定できます。以下の場合、 名前 の値があればそれを $x に、なければ デフォルト値 という値が入ります。

#set($x = %{名前|'デフォルト値'})

出力

セルの中に社名や金額など、データを出力する際にはいくつかの書き方が利用できます。

  • $ROOT.get('名前')
  • $ROOT['名前']
  • %{名前} (この書き方はDocurain独自です)

キーが英語であれば $ROOT.name のようなドットを使ったアクセスも可能です。

Docurainで扱われる変数の型は次の通りです。各型ごとにメソッドも用意されています。メソッドの詳細は公式ドキュメント(各リンク先)を参照してください。

Javaクラス
数値 java.lang.Integer / java.lang.Long / java.math.BigDecimal
真偽値 java.lang.Boolean
文字列 java.lang.String
オブジェクト java.util.Map
配列 java.util.List
日付 Date
null/undefined null

型を判別する場合には $Type.of(%{名前}) を使ってください。 stringnumber といった文字列が返ってきます。

コメント

ロジックの説明など、出力には関係ないコメント文を記述するときには ## を利用します。

#set($e = $ROOT) ## 変数へアクセスしやすくする

if文

条件を指定してマッチしている場合とマッチしていない場合とで出力する内容を変えたい時には #if#else#end が使えます。

#if(条件)
  (処理内容)   ## 条件にマッチする場合
#else
  (処理内容)   ## 条件にマッチしない場合
#end

ループ

繰り返し処理は #foreach#end を使います。たとえば100回処理を繰り返す場合には次のように書きます。

#foreach($i in [1..100])
  (処理内容)
#end

同様にJSONデータのitemsキーが配列になっているならば、次のように書きます。

#foreach($line in $ROOT.items)
  (処理内容)
#end

foreachの中では、$foreach という変数が利用できます。これはループの回数や、初回または最後などを判定するのに利用されます。

プロパティ 意味
$foreach.first ループの先頭ならtrue
$foreach.last ループの最後ならtrue
$foreach.count ループの回数
$foreach.index ループのインデックス(最初が0)

マクロ

マクロは式の定義になります。Docurainでのマクロは必ず1つのセル内で定義してください。

#macro(foo $x)
  x = $x
#end

このように定義されたマクロは任意のセルにて #foo(123) のように利用できます。同じ計算処理を行う場合などに利用してください。

Docurain独自の拡張/命令もあります

Velocityはごく基本的な命令、メソッドを用意したテンプレートエンジンになります。帳票向け、また開発効率をあげるためにDocurainでは多数の拡張を行っています。詳細はExcelテンプレート リファレンス | Docurainを参照してください。

まとめ

Velocityを知ることで、Docurainがどういった動作を行っているのかが理解しやすくなるでしょう。変数の定義や繰り返し、出力はとてもよく使いますので、ぜひ覚えてください。帳票は様々な要望が盛り込まれますが、Docurainの機能を使いこなすことで、高度で複雑な帳票も素早く作成できます。ぜひお試しください。

Apache Velocity Engine VTL Reference