配列データ内の任意の項目(キー)が別の値になった場合に改ページしたいことがよくあります。例えば、請求明細の取引先が変わったら改ページ、のような感じです。
Docurainもこの要望を頂くことが多かったため、正式に「キーブレイク機能」として実装し、簡単に扱えるようにしました。
従来は任意の項目(キー)が別の値になったらページを分けたいという場合、該当項目の値ごとに分けた配列データとしてJSONを生成してください、というご案内をしていましたが、
キーブレイク機能により、単純な一次元配列のまま簡潔に記述することが出来ます。
早速試してみる
キーブレイク機能のサンプルのテンプレートとデータ(JSON)です。
ダウンロード
[
{ "顧客名": "山田商店", "顧客ID": 100001, "商品": "みかん", "個数": 10, "単価": 100, "請求額": 1000 }
, { "顧客名": "山田商店", "顧客ID": 100001, "商品": "ぶどう", "個数": 15, "単価": 120, "請求額": 1800 }
, { "顧客名": "山田商店", "顧客ID": 100001, "商品": "バナナ", "個数": 5, "単価": 200, "請求額": 1000 }
,
, { "顧客名": "田中青果店", "顧客ID": 200001, "商品": "バナナ", "個数": 10, "単価": 100, "請求額": 1000 }
, { "顧客名": "田中青果店", "顧客ID": 200001, "商品": "レモン", "個数": 15, "単価": 120, "請求額": 1800 }
, { "顧客名": "田中青果店", "顧客ID": 200001, "商品": "メロン", "個数": 5, "単価": 1200, "請求額": 6000 }
,
]
以下は↑のテンプレートとデータ(JSON)を使用してDocurainで出力したPDFです。
配列の各要素内の顧客名が別の値になったら改ページされていることがわかります。
データがどう変形されるか確認する
上記のサンプルデータのように一つの配列下に明細が並んでいるデータは、
$ENTITIES.chunk('顧客名') と記述することで 顧客名 をキーブレイクとして次のような二次元配列へと変換されます。
[
[
{ "顧客名": "山田商店", "顧客ID": 100001, "商品": "みかん", "個数": 10, "単価": 100, "請求額": 1000 }
, { "顧客名": "山田商店", "顧客ID": 100001, "商品": "ぶどう", "個数": 15, "単価": 120, "請求額": 1800 }
, { "顧客名": "山田商店", "顧客ID": 100001, "商品": "バナナ", "個数": 5, "単価": 200, "請求額": 1000 }
, /* 山田商店の明細がここに12個続く */
],
[
, { "顧客名": "田中青果店", "顧客ID": 200001, "商品": "いちご", "個数": 10, "単価": 100, "請求額": 1000 }
, { "顧客名": "田中青果店", "顧客ID": 200001, "商品": "すいか", "個数": 15, "単価": 120, "請求額": 1800 }
, { "顧客名": "田中青果店", "顧客ID": 200001, "商品": "メロン", "個数": 5, "単価": 200, "請求額": 1000 }
, /* 田中青果店の明細がここに7個続く */
]
]
サンプルのテンプレートではこのトップレベルの配列を #foreach($dataGroup in $ENTITIES.chunk('顧客名')) のように繰り返しており、
上記のサンプルデータでは 顧客名 が "山田商店" の配列で1ページ目、"田中青果店"の配列で２ページ目が出力されることになります。
明細部の出力行数を制限
更に「１ページあたり10明細まで」のような制約を課したい場合は、以下のようにキーブレイクした配列を更に chunk(10) で分割します。
以下が上のテンプレートを使用してDocurainで出力したPDFです。（データは同じです）
顧客名が"山田商店"のデータは15個有りますが、1ページ目は10明細まで出力され、残りは2ページ目となっています。
#foreach($dataGroup in $ENTITIES.chunk('顧客名'))
#foreach($dataOfPage in $dataGroup.chunk(10))
...
#end
#end
と記述することで 顧客名 をキーブレイクとして顧客名ごとの二次元配列へ変形後、chunkで指定した10エントリごとの次のような配列に変形します。
（下記はイメージです。サンプル内ではforeachで繰り返すなかでchunk(10)により顧客ごとの配列をで10エントリごとの配列にしています）
[
[
[
{ "顧客名": "山田商店", "顧客ID": 100001, "商品": "みかん", "個数": 10, "単価": 100, "請求額": 1000 }
, { "顧客名": "山田商店", "顧客ID": 100001, "商品": "ぶどう", "個数": 15, "単価": 120, "請求額": 1800 }
, { "顧客名": "山田商店", "顧客ID": 100001, "商品": "バナナ", "個数": 5, "単価": 200, "請求額": 1000 }
, ",...(山田商店の明細がここに7個続く)"
],
[
{ "顧客名": "山田商店", "顧客ID": 100001, "商品": "みかん", "個数": 10, "単価": 100, "請求額": 1000 }
, { "顧客名": "山田商店", "顧客ID": 100001, "商品": "ぶどう", "個数": 15, "単価": 120, "請求額": 1800 }
, { "顧客名": "山田商店", "顧客ID": 100001, "商品": "バナナ", "個数": 5, "単価": 200, "請求額": 1000 }
, ",...(山田商店の明細がここに2個続く)"
]
],
[
[
{ "顧客名": "田中青果店", "顧客ID": 200001, "商品": "いちご", "個数": 10, "単価": 100, "請求額": 1000 }
, { "顧客名": "田中青果店", "顧客ID": 200001, "商品": "すいか", "個数": 15, "単価": 120, "請求額": 1800 }
, { "顧客名": "田中青果店", "顧客ID": 200001, "商品": "メロン", "個数": 5, "単価": 200, "請求額": 1000 }
, "...(田中青果店の明細がここに7個続く)"
]
]
]
今回使用したサンプルのテンプレートとデータ(JSON)はこちらのページからも登録不要で試してみることが出来ます！
他にも様々な機能がありますので、ぜひアカウント無料登録してマニュアルを参照しお試しください。
(U+3C08)という漢字の異体字である 
(MJ文字図形名 MJ001865)は、この文字を埋め込むセルのフォントをIPAmj明朝にした上で、JSONで以下のようにユニコードエスケープで表現可能です。
(齊の異体字、MJ文字図形名 MJ030058) をJSONに設定しています。
