文書生成用の高度なテンプレートを作成する

メールマージによる文書生成は、データソースから値を読み取り、それぞれの値をテンプレート内の対応するプレースホルダーに挿入するテクニックです。保持するものは 2 つです。 テンプレート マージフィールド（入力待ちの変数）と データソース これにより、値に加えて、すべてのコピーで共通するすべての情報が得られます。PDF4meのレポートエンジンは、これら2つのファイルを受け取り、完成したドキュメントを返します。

PDF4meは受け入れます Word、HTML、PDF テンプレートは3種類あり、その中でもWordが最も機能が充実しています。簡潔で読みやすい構文で、請求書、領収書、契約書、見積書、またはあらゆるパーソナライズされた文書に対応するWordテンプレートを1つ作成し、データから何千ものテンプレートを生成できます。このガイドでは、差し込みフィールド、条件、書式設定、表、画像、インラインHTMLなど、構文全体を、コピー＆ペーストの例とダウンロードして実行できるサンプルテンプレートとともに解説します。すべての構文リンクは、Wordの該当ページを指しています。 Wordテンプレート構文ドキュメント。

Wordテンプレートはどのようにデザインするのですか？​

すべては1つのプレースホルダーから始まります。値を挿入したい場所に、フィールド名を二重山括弧と角括弧で囲んで入力します。

<<[FieldName]>>

括弧内の名前は、データソース内のプロパティと一致する必要があります。名前は分かりやすく、キャメルケースまたはパスカルケースのいずれかの表記規則に従い、特殊文字は使用しないでください。以下に、最小限のテンプレートと、それを埋めるデータを示します。

Dear <<[CustomerName]>>,

Thank you for your order #<<[OrderNumber]>>.

{
  "CustomerName": "John Smith",
  "OrderNumber": "12345"
}

エンジンが戻ります:

Dear John Smith,

Thank you for your order #12345.

それが全体のアイデアです。以下はすべて同じテーマのバリエーションです。条件、ループ、書式設定はすべて通常の差し込みフィールドを囲んでいます。詳細については、 構文の概要。

テンプレートに条件を追加するにはどうすればよいですか？​

「ドキュメント生成」アクションは、データに基づいて分岐させることができます。条件が真か偽かによって、コンテンツブロックが切り替わります。基本的なif / elseif / elseの構造は次のようになります。

<<if [condition1]>> Add the first block
<<elseif [condition2]>> Add the second block
<<else>> Add the fallback block
<</if>>

条件は値を直接テストすることも、列挙法を利用することもできます（詳細は後述）。例： <<if [employees.Any(p => p.Age > 50)]>>比較演算子と論理演算子の全セットについては、以下を参照してください。 条件付き論理。

テンプレート内の値の書式設定はどのように行いますか？​

多くの場合、生の値は、特定の形式の日付、丸められた数値、強制的に大文字にされたテキストなど、取得前に整形する必要があります。フィールド名の後に、コロンで区切って引用符で囲んだ書式指定を追加します。

<<[token]:"format">>

日付は.NETスタイルのパターンに従います。

Invoice Date: <<[invoiceDate]:"dd.MM.yyyy">>
Due Date:     <<[dueDate]:"MMMM dd, yyyy">>

テキストケースには独自の短いスイッチがあります — :upper、 :caps （各単語の頭文字を大文字にする）、 :firstCap:

Customer: <<[customerName]:upper>>
Product:  <<[productName]:caps>>

数値は標準的な数値形式を使用するため <<[price]:"F2">> 値を小数点以下2桁に固定します。日付、テキスト、数値のパターンの完全なリストは テンプレートの書式設定。

リストからテーブルを作成するにはどうすればよいですか？​

テーブルはドキュメント生成の真価を発揮する部分です。テンプレートの1行が、データがある行数だけ展開されます。通常のWordテーブルを作成し、 <<foreach>> 最初のセルでループ処理を行い、後続の各セルにマージフィールドを追加し、最後のセルでループ処理を閉じます。

Column 1: <<foreach [product in products]>><<[product.productName]>>
Column 2: <<[product.manufactured]:"yyyy.MM.dd">>
Column 3: <<[product.price]>><</foreach>>

各オブジェクト products 配列は 1 行になり、他の場所と同様にセルをインラインでフォーマットできます。フィルタリングされた行や集計された行など、その他のテーブルパターンについては、 テンプレート内のテーブル。

段落やセクションを繰り返すにはどうすればよいですか？​

同じ <<foreach>> ループはテーブル以外でも機能します。段落、見出しと本文、セクション全体など、あらゆるコンテンツブロックをループで囲むと、コレクション内の各項目ごとにループが繰り返されます。

<<foreach [item in collection]>>
Content with <<[item.property]>>
<</foreach>>

ループはネストすることができ（部門ごとにセクション、従業員ごとに行をその中に）、処理を進めながらコレクションをフィルタリングまたはソートできます。参照 段落とセクションを繰り返す ネストされた例や条件付きの例については、以下を参照してください。

テンプレートに画像を追加するにはどうすればよいですか？​

PDF4meは、公開URLまたはBase64文字列から生成されたドキュメントに画像を取り込むことができます。ただし、重要なルールが1つあります。 画像フィールドはWordテキストボックス内に配置する必要があります。画像を挿入したい場所にテキストボックスを作成し、次にフィールドを追加します。

公開URLから:

<<image [imageUrl]>>

Base64エンコードされた文字列から：

<<image [imageBase64]>>

スイッチでサイズを制御できます。 -keepRatio、 -fitHeight、 -fitWidth、 そして -fitSize例えば <<image [companyLogo] -keepRatio>>完全なサイズリファレンスと行ごとの画像例は、 画像を挿入。

テンプレートにHTMLを挿入するにはどうすればよいですか？​

データに既にフォーマット済みの HTML が含まれている場合は、それをその場でレンダリングします。 -html プレーンテキストとしてエスケープする代わりに、スイッチを使用します。

<<[token] -html>>

エンジンはフィールド値を HTML として解析し、生成されたドキュメント内に書式設定 (太字、斜体、リスト、見出し、色付きスパンなど) を適用します。サポートされているタグとスタイルは、以下に記載されています。 HTMLを挿入。

列挙法を使用してデータを操作します​

単純なフィールドに加えて、このエンジンはトークン内で直接呼び出せるIEnumerableスタイルのメソッド（フィルター、ソート、カウント、平均など）を提供します。いくつかの例を以下に示します。

Total products: <<[products.Count()]>>
Average price:  $<<[products.Average(p => p.price)]:"F2">>
Top items:      <<foreach [p in products.OrderByDescending(x => x.price).Take(5)]>><<[p.name]>><</foreach>>

これらは条件分岐やループと自然に組み合わせることができます。完全なメソッド一覧 — Where、 OrderBy、 GroupBy、 Sum、 Any、 First残りは テンプレートにおける列挙。

サンプルデータは次のようになります。ベンダー、顧客、およびテンプレートがループ処理する製品リストです。

{
  "VendorName": "PDF4me",
  "VendorCity": "Zurich",
  "VendorCountry": "Switzerland",
  "VendorZip": "8630",
  "VendorContact": "123456",
  "InvoiceDate": "22-08-2022",
  "CustomerName": "John Doe",
  "CustomerCity": "Start City",
  "CustomerCountry": "US",
  "CustomerZip": "3214",
  "products": [
    { "productName": "PDF Converter", "value": 2000, "expires": "01/08/2025" },
    { "productName": "PDF API", "value": 1250, "expires": "18/02/2029" },
    { "productName": "PDF Editor", "value": 1999, "expires": "12/12/2027" }
  ],
  "comments": "This document is <b>computer generated</b> and does not require a signature."
}

知らせ comments HTML を運ぶ — と組み合わせる <<[comments] -html>> スイッチと <b> 出力では、タグが太字で表示されます。

テンプレートをデザインするためのクイックリンク​

よくある質問​

Wordテンプレートに差し込み印刷フィールドを作成するにはどうすればよいですか？​

二重山括弧と角括弧の中にフィールド名を入力します。例: <<[CustomerName]>>値を挿入したい場所に、フィールドを追加できます。フィールド名は、JSON または XML データソースのプロパティと一致する必要があります。フィールドは、見出し、段落、表のセル、テキストボックスなど、ドキュメント内の任意の場所に手動で追加できます。

PDF4meはどのようなテンプレート形式をサポートしていますか？​

言葉 （.docx、 .docHTML、PDF など、3 つの形式すべてで同じ差し込み印刷構文が使用されるため、Word テンプレートで学んだことがそのまま適用されます。Word では、レイアウト、条件、表、画像などを完全に制御できます。

Wordテンプレートにif/else条件を追加できますか？​

はい。コンテンツをラップします <<if [condition]>> ... <<elseif [condition]>> ... <<else>> ... <</if>>条件では、フィールドを直接比較したり、列挙メソッドを呼び出したりすることができます。 Any() または Count()これにより、ケースごとにファイルを管理するのではなく、単一のテンプレートでデータのあらゆるバリエーションに対応できるようになります。

テンプレート内で日付や数値の書式を設定するにはどうすればよいですか？​

フィールド名の後に引用符で囲んでフォーマットを指定してください。 <<[invoiceDate]:"dd.MM.yyyy">> デートのために、 <<[price]:"F2">> 小数点以下2桁の数値の場合。テキストケースにはショートカットスイッチがあります — :upper、 :caps、 そして :firstCap。

データ量に応じて拡張するテーブルを生成するにはどうすればよいですか？​

Word テーブルを作成し、開く <<foreach [item in collection]>> 最初のセルにマージフィールドを挿入し、残りの各セルにマージフィールドを挿入して閉じます。 <</foreach>> 最後のセルに入力します。コレクション内の各項目は自動的に1行になります。

トラブルシューティング​

次のステップ​

テンプレートを一度設計し、データと連携させるだけで、PDF4meは単一のAPI呼び出しから、一度に数千件を処理する自動化まで、オンデマンドでパーソナライズされた請求書、契約書、レポートを作成します。

参考文献​

• Wordテンプレート構文 — 概要
• テンプレートの書式設定
• テンプレート内のテーブル
• 画像を挿入
• HTMLを挿入
• 条件論理と列挙
• ドキュメント生成API