キーブレイクによる改ページが簡単にできるようになりました

配列データ内の任意の項目(キー)が別の値になった場合に改ページしたいことがよくあります。例えば、請求明細の取引先が変わったら改ページ、のような感じです。 Docurainもこの要望を頂くことが多かったため、正式に「キーブレイク機能」として実装し、簡単に扱えるようにしました。

従来は任意の項目(キー)が別の値になったらページを分けたいという場合、該当項目の値ごとに分けた配列データとしてJSONを生成してください、というご案内をしていましたが、キーブレイク機能により、単純な一次元配列のまま簡潔に記述することが出来ます。

早速試してみる

キーブレイク機能のサンプルのテンプレートとデータ(JSON)です。

ダウンロード f:id:yutay:20200602155129p:plain

[
  { "顧客名": "山田商店", "顧客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,  "単価": 1200,  "請求額": 6000 }
  , /* 田中青果店の明細がここに7個続く) */
]

以下は↑のテンプレートとデータ(JSON)を使用してDocurainで出力したPDFです。
配列の各要素内の顧客名が別の値になったら改ページされていることがわかります。 f:id:yutay:20200602155152p:plain

データがどう変形されるか確認する

上記のサンプルデータのように一つの配列下に明細が並んでいるデータは、 $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) で分割します。 f:id:yutay:20200602155528p:plain

以下が上のテンプレートを使用してDocurainで出力したPDFです。（データは同じです）
顧客名が"山田商店"のデータは15個有りますが、1ページ目は10明細まで出力され、残りは2ページ目となっています。

f:id:yutay:20200602155414p:plain

#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個続く)"
    ]
  ]
]