【無料デモ】Docurainを今すぐ始める

サンプル帳票の実行

Docurainでは、Excelで作成された帳票テンプレートにJSONデータを差し込み、帳票を作成するサービスです。

1. サンプルをダウンロード

まずはサンプルの帳票とJSONファイルをダウンロードしましょう。

2. 実行

以下のフォームで帳票を生成できます。

解凍したサンプルデータの「自動車検査証.xls」を「テンプレートファイル」に、「自動車検査証.json」を「JSONファイル」に設定して実行ボタンを押してみて下さい。

PDFファイルが出力され、ダウンロードされます。


出力タイプ

テンプレートファイル:

JSONファイル:


補足 Docurainでは帳票を出力するために公開されているREST APIを使用します。テンプレートファイルとJSONファイルをセットにしたHTTPリクエストをAPIに送信すると、実行結果のバイナリデータが返却される仕組みです。テンプレートは事前にDocurainサービス上に保存しておき、JSONデータだけを送信して帳票を生成することもできます。こちらのフォームはお試し用として構築していますので、生成した帳票には透かしが入ります。ご登録(無料)して頂くと、透かしの入っていない帳票を生成することが出来ます

3. 仕組み - データの挿入

どのような仕組みになっているのでしょうか?「自動車検査証.xls」を開いてみてください。

セルにはデータを差し込むためのプレースホルダ %{} が埋め込まれています。これは、「トップレベルオブジェクトの指定したメンバを参照する」という意味になります。たとえば、%{登録番号} はトップレベルオブジェクトの "登録番号" を参照しているという意味になります。

「自動車検査証.json」を開いてみて下さい。

対応する帳票はこちらです。

「登録番号」に対応する文字列が正しく帳票テンプレートに差し込まれていることがわかりますね。
でも、フラットな構造のJSONでは表しにくい、もう少し複雑なデータを扱うときはどうすればいいでしょう?

Docurainでは、任意のスキーマのJSONを読み込むことができます。プレースホルダ %{} は「省略記法」と呼ばれる機能で、これは任意のオブジェクト(デフォルトはトップレベルオブジェクト)を起点として 、その中のメンバを参照する単純な記法です。任意のレベルにあるデータを参照するときは、通常の記法 ${} を使用します。

たとえば、

というJSONデータの"string data"を参照する場合は、 ${ENTITY.a.b} と記述します。${ENTITY.a["b"]} と記述することもできます。トップレベルオブジェクトは常に"ENTITY"という名前で参照します。したがって、%{登録番号} は ${ENTITY["登録番号"]} と同じです。

4. 仕組み - 制御構文

ではリスト(配列)データはどのように扱うのでしょうか?

という配列 a の要素それぞれは ${ENTITY.a[0]} ${ENTITY.a[1]} ${ENTITY.a[2]} と、添字で指定することで参照することが可能です。しかし、実際の帳票開発では、特定の添字の要素を参照するよりも、要素数分だけ繰り返してなにかを行いたいという状況のほうが多いでしょう。

Docurain内の帳票では、数々の制御構文や独自のマクロを使用することができます。配列データを扱うときも、これらを使用して通常のプログラミングを行うのと同じように直感的に扱うことができます。

「自動車検査証.xls」の下の方、「備考」の欄にリストデータを扱うコードがあります。

Docurainテンプレートでは、A列を制御構文やマクロを記述する特別な列として扱っています。ここに、リスト構造を扱うための

という構文が書かれています。「自動車検査証.json」の該当する「備考」を確認してみましょう。

「備考」は配列として記述されています。 #foreach($e in %{備考}) は、「備考のそれぞれの配列要素 $e に対する繰り返し」を行います。
もう少し具体的に言うと、#foreach ... #endの間の行を、要素数分生成して挿入します。このとき、$eには配列要素が先頭から順に代入されます。 最終的に、制御構文が書かれた行は出力時に削除されます。

続いて、foreach文の中を見ていきましょう。次のような構文が書かれています。

ここで、 $WITH($e) は1.で説明した省略記法の起点となるオブジェクトを変更するためのマクロです。ここで指定したオブジェクトが省略記法の起点となります。

補足 #WITHは省略記法を使用しない場合は指定しなくても構いません。#WITHを指定しない場合は、続く #if の中で指定している %{右寄せ} を、${e["右寄せ"]}と記述します。

#if(...)は条件分岐です。丸括弧の内容の真偽値によって、異なる行を表示します。ここでは、「右寄せ」フラグがtrueならば33行目を表示し、falseならば35行目を表示するロジックになっています。

これによって、「与えるデータによってExcelのスタイルを切り替える」という動作を実現しています。

補足 Docurainには、if文を使用せずにデータに応じて罫線を表示させたり、背景色を変えたりするマクロも用意されています。これにより、複雑なスタイルの切り替えを行う際でも無秩序にif-else構文がネストするような構造を避けたシンプルな記述が可能です。

以上をまとめると、ここでは「備考」の配列の要素それぞれに対して、「右寄せ」がtrueであるならば右寄せスタイルが適用された行(33行目)を表示、そうでないならば左寄せスタイルが適用された行(35行目)を表示する動作を行っています。

つまり、以下の「備考」の配列は

最終的に以下のように出力されます。

5. 仕組み - Excelの機能

Excelの書式設定や数式は、そのほぼすべてを利用することができます。グラフやシェイプ、画像もそのまま表示できます。挿入したデータをもとにグラフを描画し、それを出力することももちろん可能です。

ここでは、日付に対するフォーマットが適用されていることを確認しましょう。

$NOW は現在日時を参照する特殊なオブジェクトです。Excel上には日付値として挿入されますので、Excelの「表示形式」に従ってフォーマットすることができます。

出力結果は以下です。指定したとおり正しく書式が設定されていることがわかります。

6. より高度な機能 - テンプレート言語

では、続いてもう少し複雑な帳票のサンプルを確認していきましょう。

「見積書.xlsx」と「見積書.json」をまた冒頭のフォームに指定して実行ボタンを押してみてください。

このような帳票が出力されます。

[Copyright © VELC Inc.]

(謝辞: このテンプレートはヴェルク株式会社様のご厚意により体裁をお借りしております)

「見積書.xlsx」を開いてみてください。

「3. 仕組み - データの挿入」にて、トップレベルオブジェクトは ENTITY という名前で参照できると説明しました。この帳票では、 ${e.companyName} のようにトップレベルのオブジェクトを e として指定しています。なぜこのようなことができるのでしょうか?

その答えはA2セルにあります。ここには、 #set($e = $ENTITY) というマクロが書かれています。#set()マクロを使用することで、ENTITYを変数eに代入することができます。

この構文や、すでに説明した #foreach などのマクロはすべて Apache Velocity に準拠した文法になっています。

たとえば、以下のように四則演算をテンプレート中で行うこともできます。

7. より高度な機能 - Excel数式

続いて「見積書.xlsx」と「見積書.json」をフォームに指定し、今度は出力タイプを「PDF」から「XLS」に変更して「実行」ボタンを押してみましょう。テンプレートの生成結果がExcelファイルとしてダウンロードできます。

このテンプレートでは「金額」「消費税」「合計」をExcelの数式を利用して計算しています。どのように構築されているか「金額」列から確認しましょう。

出力結果を確認すると、「金額」列はI列(数量)とK列(単価)の乗算になっていることがわかります。これは、どのようなテンプレートを指定すればよいのでしょうか。

テンプレートでは、この「金額」を

として記述しています。すこし特殊な記述になっているのは、この行がデータ数に応じて動的に増加していくからです。 例えば、ここで

と指定してもエラーにはなりませんが、すべての行でI20とK20セルが参照され、正しい結果にはなりません。これを防ぐために、マクロ #ROW() を使用しています。マクロ #ROW() はExcelのROW()関数のように、そのセルが属する行番号を返却します。これによって、行が動的に増えても正しい行番号を数式に指定することができます。

では、先頭の % にはどんな意味があるのでしょうか?Excelでは、下記のような数式

は正しくないためエラーとなり入力できません。このために、先頭に%をつけて文字列データとしてセル中に記述します。実行時、先頭の%は削除され、数式として扱われます。

#ROWなどのマクロを評価した結果、Excelが受け付けられる正しい数式にならなかった場合はエラーとなります。

続いて、「消費税」「合計」を見ていきましょう。これら2つのセルにはそれぞれ以下のような式が設定されています。

ここで、「amount」はExcelの標準機能である名前付き範囲です。もう一度、「金額」セルをクリックして確認してみましょう。

このセルに「amount」という名前が指定されていることがわかります。

このセルは、#foreachを展開したあとは、名前付きセル範囲として参照できます。

したがって、 SUM(amount) は「金額」の合計値を算出します。

Docurainでは、その他にもセル位置を相対参照するためのマクロがいくつか備わっており、名前付きセル・範囲も利用できるため、動的にセル数が変化する帳票でも柔軟に数式の参照位置を指定できます。

8. より高度な機能 - 画像

Docurainでは画像をJSONデータから挿入することができます。

「見積書.xlsx」を開くと、#IMAGE マクロがテキストとして書かれたシェイプが2つあります。

出力結果をみるとわかるように、これは画像に置換されます。

#IMAGE() マクロは指定したデータを画像として展開します。このとき与えるJSONは、バイナリデータを扱うためにBASE64エンコードした文字列を指定します。「見積書.json」を開いてみてください。

画像データはBASE64エンコードした文字列として指定する他、任意の画像ファイルを指す、認証なしでアクセス可能なURLを指定することもできます(ただし、お試し版では使用できません)。

補足 Docurainでは、データとして入力するJSONファイルの形式として、通常のJSONファイルの他、 { foo: 1 } のようなJavaScriptのオブジェクト書式で記述することもできます。「見積書.json」はこちらの形式で記述されています。また、入力データとしてCSV/TSV/Excelを使用することもできます。

その他の機能

以上で簡単なDocurainのチュートリアルは終わりです。ぜひ、サンプルのExcelやJSONデータを変更して、どのように出力結果が変わるか確認してみてください。Docurainは、他にもここでは説明しきれないほどの多様な機能を備えています。また、日々機能拡張がなされています。

などなど、色々疑問が出てくると思いますが、ご興味を持っていただけたならばぜひDocurainにご登録いただき、試用を開始してみてください!試用を開始すると、より詳しい帳票作成マニュアルと、REST APIの詳細仕様を閲覧することができます。

Docurainは無料でスタートでき、月間の無料試用枠が毎月付与されます。登録後に出力した帳票には透かしも入りません。

ぜひこの機会に快適なDocurainでの帳票開発を体験してみてください!

クラウド帳票エンジン「Docurain」を
無料でトライ!

Docurainの圧倒的な使いやすさを是非
体験してください!