テンプレート

テンプレートは PDF の見た目を定義する HTML ドキュメントです。 LiquidJS テンプレートエンジンを使用して動的なデータを埋め込めます。

テンプレートの作成

ヘッダーの「テンプレート」をクリックし、テンプレート一覧を開きます。
「テンプレート新規作成」ボタンをクリックします。
エディタの中央にあるテンプレート名をクリックして名前を付け、HTML を記述したら「保存」ボタンをクリックします。

画面を追いながら試したい場合はチュートリアルを参照してください。

テンプレート ID

テンプレート ID は API からテンプレートを指定するための識別子で、保存時に自動で採番されます。テンプレート一覧の「テンプレート ID」列に表示され、左のアイコンでコピーできます。API リクエストの templateId パラメータにこの値を指定します。

LiquidJS によるデータ埋め込み

Printgraph は LiquidJS テンプレートエンジンをサポートしています。 API リクエストの params に渡した値をテンプレート内で参照できます。

主な構文

{{ variable }} — 変数の出力
{% if condition %} ... {% endif %} — 条件分岐
{% for item in list %} ... {% endfor %} — 繰り返し

QR コードの埋め込み

値を QR コードに変換するフィルターを 2 つ用意しています。生成される QR コードは SVG のベクター画像なので、拡大しても印刷してもぼやけません。

{{ 値 | qr }} — img タグごとその場に展開します。
{{ 値 | qr_data_uri }} — 画像の data URI だけを返します。img の src 属性に埋め込んで、クラスやスタイルを自由に指定したい場合に使います。

<!-- その場で img タグごと展開する -->
{{ invoiceUrl | qr }}

<!-- サイズ(px)と誤り訂正レベルを指定する -->
{{ invoiceUrl | qr: 160, 'H' }}

<!-- data URI だけを展開して img の src に埋め込む -->
<img src="{{ invoiceUrl | qr_data_uri }}" class="qr" width="120">

引数

サイズ（{{ 値 | qr: 160 }}）— img の一辺のピクセル数。1〜2000 の整数で、既定値は 128 です。qr_data_uri では受け付けません（img 側で指定してください）。
誤り訂正レベル（{{ 値 | qr: 160, 'H' }}）— L / M / Q / H のいずれか。既定値は M です。レベルを上げるほど汚れやかすれに強くなりますが、QR コードは細かくなり、格納できるデータ量も減ります。qr_data_uri では {{ 値 | qr_data_uri: 'H' }} のように第 1 引数で指定します。

制限

QR コードにできる値の長さ（UTF-8 のバイト数）は誤り訂正レベルによって変わります: L 2,953 / M 2,331 / Q 1,663 / H 1,273 バイトまで
QR コードにできるのは文字列と数値のみ（配列やオブジェクトは不可）
値が空のときは QR コードを出力しません（エラーにはなりません）。読み取っても何も出てこない QR コードが印刷されるのを避けるためです。{{ 値 | qr }} は img タグごと出力しないので {% if %} で囲む必要はありません。{{ 値 | qr_data_uri }} の場合は img タグを自分で書くため、空の img タグが残ります（画像は表示されません）。タグごと消したい場合は {% if %} で囲んでください。

テンプレート例（請求書）

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8" />
  <style>
    body { font-family: sans-serif; padding: 40px; }
    h1 { color: #333; }
    .amount { font-size: 2rem; font-weight: bold; }
  </style>
</head>
<body>
  <h1>請求書 #{{ invoiceNumber }}</h1>
  <p>宛先: {{ customerName }} 様</p>

  <table>
    <thead>
      <tr><th>商品名</th><th>単価</th><th>数量</th></tr>
    </thead>
    <tbody>
      {% for item in items %}
      <tr>
        <td>{{ item.name }}</td>
        <td>¥{{ item.price }}</td>
        <td>{{ item.quantity }}</td>
      </tr>
      {% endfor %}
    </tbody>
  </table>

  <p class="amount">合計: ¥{{ amount }}</p>

  <p>スマートフォンで読み取ると請求書の詳細を確認できます。</p>
  {{ invoiceUrl | qr: 100 }}
</body>
</html>

配列・オブジェクトを渡す

params には文字列だけでなく、配列やオブジェクトを含む任意の JSON を渡せます。上の請求書テンプレートの items のように、明細行を {% for %} で繰り返し出力する場合に使います。

{
  "templateId": "YOUR_TEMPLATE_ID",
  "params": {
    "invoiceNumber": "INV-001",
    "customerName": "山田太郎",
    "items": [
      { "name": "商品A", "price": 1000, "quantity": 2 },
      { "name": "商品B", "price": 500, "quantity": 1 }
    ],
    "amount": 2500,
    "invoiceUrl": "https://example.com/invoices/INV-001"
  }
}

エディタの「変数」タブで変数の種別を JSON にすると、初期値を JSON で設定できます。この初期値はプレビューと生成画面で使われるため、明細行のあるテンプレートもエディタ上で表示を確認できます。

制限

ネストの深さ: 10 段まで
配列の要素数: 100 個まで
オブジェクトのキー数: 200 個まで
文字列の長さ: 10,000 文字まで
params 全体の値の個数: 10,000 個まで

全テンプレートで共有する変数

会社名やロゴ URL のように、どのテンプレートでも同じ値になるものは「共有変数」として 1 箇所で管理できます。管理画面の 共有変数 ページで設定すると、すべてのテンプレートから {{ global.変数名 }} で参照できます。

<footer>
  <p>{{ global.companyName }}</p>
  <p>{{ global.companyAddress }}</p>
  <img src="{{ global.logoUrl }}" alt="{{ global.companyName }}" />
</footer>

変数の種別（文字列 / JSON）や編集の操作は、テンプレートごとの変数と同じです。

テンプレートごとの変数との違い

値はサーバー側で適用されるため、API リクエストの params では上書きできません。params に global キーを含めたリクエストは 400 エラーになります。
テンプレートのバージョンには保存されません。共有変数を変更すると、過去のバージョンを含むすべてのテンプレートに即座に反映されます。
テンプレートが参照している共有変数を削除すると、そのテンプレートの PDF 生成は失敗します。
登録できる個数: 30 個まで

バージョン管理

テンプレートを保存するたびに新しいバージョンが作成されます。「メインバージョン」として設定したバージョンが API から呼び出されます。過去のバージョンに戻したい場合は、バージョン一覧から「メインに設定」をクリックしてください。