Docurain Labo

Docurainサービス開発日記

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

新年あけましておめでとうございます。 今年もDocurainは開発者の皆様をラクにする、便利な機能をどんどん開発していきます!

さて、本日は「番号付き省略記法」のご紹介です。

以前、省略記法を紹介しました。

今回はその省略記法で同時に複数のコンテキスト(省略記法の起点となるオブジェクト) を設定できるようにした番号付き省略記法を紹介します。

{
  "先月": {
    "売上": 1234,
    "来客数": 123
  },
  "今月": {
    "売上": 5678,
    "来客数": 456
  }
}

上記のようなJSONがある場合、テンプレート側で

#with(%{先月})

としてJSONの先月#WITH or #withの引数に指定すると、以下のように簡潔な書き方で参照できるようなります。

https://docurain.jp/wp/wp-content/uploads/2020/11/スクリーンショット-2020-11-05-11.14.34.png

これが省略記法です。

ただし、コンテキストを「先月」にすると、「今月」の売上は%{売上}では参照できないため

https://docurain.jp/wp/wp-content/uploads/2020/11/スクリーンショット-2020-11-05-11.15.35.png

のように書くことになります。

このようなケースで使えるのが番号付き省略記法です。

#with(%{先月})
#with2(%{今月})

とすることで

先月の売上は%{売上}、今月の売上は%2{売上}です

のように参照することが可能です。なお、番号は1から9まで使用できます。

https://docurain.jp/wp/wp-content/uploads/2020/11/スクリーンショット-2020-11-05-11.17.15.png

#with2で指定したオブジェクトは%2{XXXX}のように
#with3で指定したオブジェクトは%3{XXXX}のように
記述が可能になります。*1

このようにテンプレートを分かりやすく簡潔にするための機能も随時追加しております。

テンプレートは最大限シンプルにしていきましょう!

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

*1:番号は1から9まで指定可能です。0は無指定と同義です。すなわち#with0(...)と#with(...)は同じです。

令和の時代は帳票も絵文字で圧倒的成長☝😉✨✨✨

注:この記事は本来、昨年前半に公開予定でしたが、管理上の都合で公開が遅れました。(忘れていたとも言う)

要約

  • 令和元号に対応しています
  • サロゲートペアに対応しています

どちらも4月の段階では対応していましたが、諸事情あって(主に筆者の遅筆により)報告が遅れてしまいました…。

新元号

PDF出力の場合、Excelの書式設定で和暦を設定すると、2019年5月1日以降は「令和」の元号で表示されます。Excel出力の場合はクライアント側にインストールされているExcelの環境に依存しますが、アップデートが適用されていればすでに対応済みになっているはずです。

forest.watch.impress.co.jp

サロゲートペア対応

Docurainでは当初、サロゲートペアには対応しておりませんでしたが、今は完全対応しています。サロゲートペアで表現されている日本語文字としては、JIS第3・第4水準の漢字の一部が該当しまが、これらはすべてDocurainから出力可能であることを確認済みです。

www13.plala.or.jp

www13.plala.or.jp

JIS第3・第4水準の漢字は人名や一部住所で用いられておりますが、Docurainであればそれらを含む帳票も文字化けやエラーを発生させることなく出力可能です。

そしてサロゲートペアに対応したということは…。絵文字も表示できるということです!今回は試しに適当な帳票として報告書(日報)を作成して新しい機能を試してみます。

作成したテンプレート

いきなりですが完成した帳票がこれです。

f:id:withpop:20190528140344p:plain

どうってことない帳票です。このくらいの帳票であれば、頑張れば10分かそこらで作成できると思います。右下にはよくあるような承認欄を設けてみました。テキスト(名字など)を入力する想定ですが、Docurainでは画像も差し込むことができるので印影を挿入することも可能です。

使用するデータ

データは以下のような感じです。とりあえず絵文字をふんだんに使ってみました。

{
    "date": "2019-05-27",
    "reporter": "超票 太郎",
    "division": "営業2課",
    "summary": "いっけなーい 🔪殺意殺意 💦私、帳票開発エンジニア😘入り組んだ罫線を見ると正気を保てなくなるの✨\nでもある日、「ここに備考欄追加してよ、すぐできるでしょ?」とか言われてもう大変 😢 \n簡単にできると思ってるならまずは自分でやってみなよ 👆💕 \n\n次回「やっぱり元に戻しておいてくれる?」お楽しみに❤️",
    "detail": [
        {"time": "2019-05-27T09:00", "description": "な、なに?😧"},
        {"time": "2019-05-27T10:00", "description": "「帳票開発は大変」だと?😨"},
        {"time": "2019-05-27T11:30", "description": "ふ、ふざけるな✊😡 💢💢"},
        {"time": "2019-05-27T14:00", "description": "Docurainなら日本人好みの罫線の多い帳票もExcelで簡単に作成できます✋😤🙅"},
        {"time": "2019-05-27T16:00", "description": "「面倒くさい帳票開発をサクっと済ませる」で、“圧倒的成長\"✋😤😤😤"},
        {"time": "2019-05-27T18:00", "description": "だれもやりたくない作業から開放させて楽しいビジネスに集中させてくれるサービスに圧倒的感謝☝😉✨✨✨"}
    ],

    "comment": "太郎ちゃん、お疲れ様✨✨✨❤\nブチョーはお昼ご飯を食べに来てるョ😘😘\n帳票開発は大変😨😨だけど太郎チャンはしっかり仕事してる📃からボクも鼻が高いよ😚😚😚\nこれからもがんばってね☝😉✨✨✨",

    "tanto": "😆",
    "kakaricho": "😉",
    "kacho": "😍",
    "bucho": "😨"
}

日時も令和の日付を指定してみました。

出力結果

f:id:withpop:20190528151506p:plain

ちゃんと出力されていますね。ただし、絵文字は独自のグリフになっております。ここは諦めてください。

セルの結合を簡単に行えるようにしました

リスト・一覧形式の帳票では以下のように分類ごとにセルを結合・マージさせたいことがあります。

https://docurain.jp/wp/wp-content/uploads/2020/11/2160.png

その際にDocurainでは簡単に分類ごとの枠(セル)を結合することが可能です。

#MERGE_CELL([キー])#MC([キー])を使用します。
#MC#MERGE_CELLのエイリアスです)
引数は、結合するセルのグループを指定するための一意のキーです。

早速試してみます

サンプルのテンプレートとデータ(JSON)です。

ダウンロード

https://docurain.jp/wp/wp-content/uploads/2020/11/スクリーンショット-2020-11-04-13.24.23.png

[
  {
    "name": "食料品",
    "items": [
      {
        "name": "肉類",
        "items": [
          { "name": "輸入牛肉", "amount": 1 },
          { "name": "和牛", "amount": 2 }
        ]
      },
      {
        "name": "肉類",
        "items": [
          { "name": "ブロイラー", "amount": 1 },
          { "name": "地鶏", "amount": 2 }
        ]
      },
      ..中略..
    ]
  },
  ..中略..
  {
    "name": "雑貨",
    "items": [
      {
        "name": "電池",
        "items": [
          { "name": "単1", "amount": 1 },
          { "name": "単2", "amount": 2 },
          { "name": "単3", "amount": 3 }
        ]
      }
    ]
  }
]

出力結果は以下の通りです。
同じ分類名の場合に該当のエリア(セル)がマージされていますね。

https://docurain.jp/wp/wp-content/uploads/2020/11/スクリーンショット-2020-11-04-11.44.37.png

また以下のような書き方も可能です。

https://docurain.jp/wp/wp-content/uploads/2020/11/スクリーンショット-2020-11-04-13.33.10.png

このように引数無しの場合、セルの値そのものが引数として扱われます。
セルに出力させたい値とキーが同じ場合はこちらの書き方の方が簡潔で分かりやすいですね。 出力結果は↑と同様じです。

大項目は異なるが中項目は同一の場合

このJSONのように大項目は異なるが中項目は同一の場合もあります。

JSONダウンロード

[
  {
    "name": "",
    "items": [
      {
        "name": "A1",
        ..中略..
      },
    ]
  },
  {
    "name": "",
    "items": [
      {
        "name": "A1",
        ..中略..
      }
    ]
  }
]

先ほどと同じテンプレートで出力するとこのようになります。

https://docurain.jp/wp/wp-content/uploads/2020/11/スクリーンショット-2020-11-04-12.59.01.png

大項目が異なる場合に中項目が同じでも枠を分割させたい場合は、
中項目の#MERGE_CELL or #MCの引数に大項目の値も含めます。
例): #MERGE_CELL(`$catL.name+$catM.name`) $catM.name

修正版テンプレートダウンロード

これにより以下のような出力結果となります。
中項目が同じでも枠が分割されてますね。

https://docurain.jp/wp/wp-content/uploads/2020/11/スクリーンショット-2020-11-04-13.05.58.png

分類ごとに枠をマージさせるような帳票出力が必要な場合は、 今回作成したサンプル帳票を、こちらのページからも登録不要で試してみることが出来ますので、気になったらぜひ試してみて下さい。

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

わかりやすいテンプレートのために - IF / IFS / SWITCHのご紹介

今回は条件分岐がシンプルに書けるようになったIF / IFS / SWITCHをご紹介します。

従来の条件分岐

従来はセル内で条件分岐をさせて値を出力する場合に

#if($cond) $a #end
#if($cond) $a #else $b #end
#if($cond1) $a #elseif($cond2) $b #elseif($cond3) $c #else $d #end

のように書かなければならず、少し面倒でした。

プログラマの美徳は怠惰。というわけで、より簡潔な表現のためにExcelの関数(IF / IFS / SWITCH)とほぼ同等の記述を可能にしました。 それが #IF / #IFS / #SWITCH マクロです。

#IF / #IFS / #SWITCH

上記の通り、Excelの関数(IF / IFS / SWITCH)と類似の記法・動作になっています。

概要は次の通りです。

#IF

従来の書き方(#if) #IF
#if($cond)

#end
#IF($cond, 'A')
#if($cond)

#else

#end
#IF($cond, 'A', 'B')

#IFS

従来の書き方(#if) #IFS
#if($cond1)

#elseif($cond2)

#elseif($cond3)

#end
#IFS([$cond1, 'A', $cond2, 'B', $cond3, 'C'])
#if($cond1)

#elseif($cond2)

#elseif($cond3)

#else

#end
#IFS([$cond1, 'A', $cond2, 'B', $cond3, 'C'], 'D')

#SWITCH

従来の書き方(#if) #SWITCH
#if($val == 1)

#elseif($val == 2)

#elseif($val == 3)

#else

#end
#SWITCH($val, [1, 'A', 2, 'B', 3, 'C'], 'D')

詳細はDocurainのマニュアル 帳票作成マニュアル(条件分岐支援) をご参照ください。

実際に使うとこんな感じです。

https://docurain.jp/wp/wp-content/uploads/2020/09/スクリーンショット-2020-09-09-12.41.02.png

このようにセル内がスッキリして、テンプレートが読みやすくなりました。

帳票はただでさえ複雑な物が多いですし...

テンプレートは最大限単純にしておきたいものです!

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

わかりやすいテンプレートのために - 式リテラルのご紹介

Docurainのテンプレート

DocurainではExcelテンプレートに差し込みたいデータの位置をプレースホルダーとして記述します。

また、出力する帳票の行を動的に増やす、特定の条件のときだけ表示する、などの動的な部分は組み込みのマクロ命令により実現します。 このマクロ命令はVelocityに準拠しています。

式リテラル

今回ご紹介する式リテラルはこのVelocityの制約を突破するために追加されたDocurain独自の機能です。 Velocityの制約とは、いわゆる「式」を使える箇所が限られている点です。

通常、式を指定できるのは

#if($a < 0) ... #end
#set($b = $a + 1)

のような箇所だけです。つまり、

$a 足す 1 は $a + 1 です。
#set($list = [$a, $a + 1, $a + 2])

のような記述ができず、

#set($plus1 = $a + 1)
#set($plus2 = $a + 2)

$a 足す 1 は $plus1 です。
#set($list = [$a, $plus1, $plus2])

のように回りくどい書き方になります。なかなかキツいですねこれは。

https://docurain.jp/wp/wp-content/uploads/2020/08/スクリーンショット-2020-08-31-14.27.10.png

エンジニアは怠惰であるべき。怠けるために全力を出した結果、生み出されたのが「式リテラル」です。

使用例

式リテラルは、バッククオート ` で囲んだ文字列がそのまま値として評価されます。*1

↑のテンプレートを式リテラルを使用することにより簡潔にすることが可能です。

https://docurain.jp/wp/wp-content/uploads/2020/08/スクリーンショット-2020-08-31-14.41.40.png

#set($plus1 = %{num} + 1)
%{num} 足す 1 は $plus1 です。
%{num} 足す 1 は `%{num} + 1` です。
#set($b = %{a} + 1)
#set($c = %{a} + 2)
#set($list = [%{a}, $b, $c])
#set($list = [%{a}, `%{a} + 1`, `%{a} + 2`])

のように記述できるようになりました。

スッキリしてわかりやすくなりましたね! Javascriptのテンプレートリテラルに似せたデザインにしたので、違和感も少ないかと思います。

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

*1:現在のところバッククオートのエスケープはできません。すなわち、バッククオートを含む式リテラルは使用できません。

DocuSign対抗! Docurainも画像、回せます

このようなツイートを目にしました。

そこでDocuSignに対抗??して、Docurainでも画像回転できるようにしました!
(DocuSign... 名前も似てますし、やるしかないですよね...!!)

注: この機能は9/1からご利用頂けるようになる予定です。

通常の画像出力

通常の画像出力です。
シェイプに#IMAGE($e.stamp)のように記載することで渡された画像データを出力します。

画像回転の指定方法

上記の画像出力で#IMAGE($e.stamp, 'rotate=[角度]')のようにすると、画像を指定した角度に回転させることができます。
-360°から360°の範囲で指定可能で、それぞれ以下の意味を持ちます。

正の角度 元画像のサイズのままで回転される。
よって、長方形の場合は見切れることがある。
負の角度 元画像のサイズを超えないように自動縮小される。

https://docurain.jp/wp/wp-content/uploads/2020/08/2120.png (画像はこちらをお借りしております 「たいへんよくできました」のようなハンコのジェネレーターを作ってみた。 - RainbowVortex)

回していきましょう!

まずは正の角度を指定します。
#IMAGE($e.stamp, 'rotate=30')

回ってますね〜
画像サイズはそのままですね。

次は負の角度を指定して出力します。
#IMAGE($e.stamp, 'rotate=-30')

こちらは元画像のサイズを超えないように自動縮小がされてますね。

このようにDocurainでも手軽に画像がまわせます。

はんこお辞儀が必要な場合にも使えます...!

 

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

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

省略記法とは

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

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

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

https://docurain.jp/wp/wp-content/uploads/2020/08/with_blog_1.png

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

https://docurain.jp/wp/wp-content/uploads/2020/08/with_blog_2.png

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

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

注:#with は9月上旬に公開予定の新機能です。2020/8/7現在はまだ利用できません。 #WITH はご利用可能です

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

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

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

使用例

#WITHを使ったテンプレートサンプル https://docurain.jp/wp/wp-content/uploads/2020/08/with_blog_3.png

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

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

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

https://docurain.jp/wp/wp-content/uploads/2020/08/with_blog_4.png

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

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

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

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

*1:CSV, TSVも可