Pembuatan dokumen dengan mail merge adalah proses membaca nilai dari sumber data dan menaruh setiap nilai ke placeholder yang cocok di sebuah templat. Anda menyimpan dua hal: sebuah templat yang berisi bidang gabungan (variabel yang menunggu diisi) dan sebuah sumber data yang menyediakan nilai-nilai serta segala hal yang tetap sama di setiap salinan. Mesin pelaporan PDF4me mengambil kedua berkas itu dan mengembalikan dokumen yang sudah jadi.
PDF4me menerima templat Word, HTML, dan PDF, dan yang terkaya di antara ketiganya adalah Word. Dengan sintaks yang ringkas dan mudah dibaca, Anda dapat merancang satu templat Word yang mencakup faktur, tanda terima, kontrak, penawaran, atau dokumen personalisasi apa pun, lalu menghasilkan ribuan dari data. Panduan ini menelusuri seluruh sintaks — bidang gabungan, kondisi, pemformatan, tabel, gambar, dan HTML sebaris — dengan contoh siap salin dan templat contoh yang bisa Anda unduh dan jalankan. Setiap tautan sintaks mengarah ke halaman yang tepat di dokumentasi sintaks templat Word.
Tulis placeholder sebagai <<[FieldName]>> di dokumen Word. Tambahkan kondisi, pemformatan, perulangan, gambar, dan HTML dengan beberapa token tambahan. Kirim templat itu bersama berkas data JSON (atau XML) ke aksi Generate Document PDF4me, dan Anda menerima dokumen personalisasi yang sudah jadi — sekali, atau ribuan kali.
Bagaimana cara merancang templat Word?
Semuanya dimulai dari satu placeholder. Di mana pun Anda ingin sebuah nilai disisipkan, ketik nama bidang yang dibungkus tanda kurung sudut ganda dan tanda kurung siku:
<<[FieldName]>>
Nama di dalam kurung harus cocok dengan properti di sumber data Anda. Jaga nama tetap deskriptif, patuhi satu konvensi (camelCase atau PascalCase), dan hindari karakter khusus. Berikut templat minimal dan data yang mengisinya:
Dear <<[CustomerName]>>,
Thank you for your order #<<[OrderNumber]>>.
{
"CustomerName": "John Smith",
"OrderNumber": "12345"
}
Mesin mengembalikan:
Dear John Smith,
Thank you for your order #12345.
Itulah keseluruhan idenya. Semua yang di bawah ini adalah variasi dari prinsip yang sama — kondisi, perulangan, dan pemformatan selalu membungkus bidang gabungan biasa. Detail lengkap ada di Ikhtisar Sintaks.
Bagaimana cara menambahkan kondisi ke templat?
Aksi Generate Document dapat bercabang berdasarkan data Anda. Bergantung apakah suatu kondisi benar, ia menyisipkan satu blok konten atau blok lain. Struktur dasar if / elseif / else terbaca seperti ini:
<<if [condition1]>> Add the first block
<<elseif [condition2]>> Add the second block
<<else>> Add the fallback block
<</if>>
Kondisi dapat menguji sebuah nilai secara langsung atau bersandar pada metode enumerasi (lihat di bawah), misalnya <<if [employees.Any(p => p.Age > 50)]>>. Kumpulan lengkap operator perbandingan dan logika ada di Logika Kondisional.
Bagaimana cara memformat nilai di templat?
Sering kali nilai mentah perlu dirapikan sebelum disisipkan — tanggal dengan gaya tertentu, angka yang dibulatkan, teks huruf besar. Tambahkan spesifikasi format setelah nama bidang, dipisahkan titik dua dan diapit tanda kutip:
<<[token]:"format">>
Tanggal memakai pola gaya .NET:
Invoice Date: <<[invoiceDate]:"dd.MM.yyyy">>
Due Date: <<[dueDate]:"MMMM dd, yyyy">>
Huruf besar/kecil punya sakelar pendek sendiri — :upper, :caps (mengapitalkan setiap kata), dan :firstCap:
Customer: <<[customerName]:upper>>
Product: <<[productName]:caps>>
Angka memakai format numerik standar, sehingga <<[price]:"F2">> menetapkan nilai ke dua desimal. Daftar lengkap pola tanggal, teks, dan angka ada di Pemformatan di Templat.
Bagaimana cara membangun tabel dari sebuah daftar?
Di tabel-lah pembuatan dokumen menunjukkan nilainya — satu baris templat mengembang menjadi sebanyak baris yang dimiliki data Anda. Buat tabel Word biasa, buka perulangan <<foreach>> di sel pertama, tambahkan bidang gabungan di setiap sel berikutnya, dan tutup perulangan di sel terakhir:
Column 1: <<foreach [product in products]>><<[product.productName]>>
Column 2: <<[product.manufactured]:"yyyy.MM.dd">>
Column 3: <<[product.price]>><</foreach>>
Setiap objek dalam array products menjadi satu baris, dan Anda bisa memformat sel secara sebaris seperti di tempat lain. Pola tabel lainnya, termasuk baris yang difilter dan diagregasi, dibahas di Tabel di Templat.
Bagaimana cara mengulang paragraf dan bagian?
Perulangan <<foreach>> yang sama juga bekerja di luar tabel. Bungkus blok konten apa pun — sebuah paragraf, judul beserta isinya, satu bagian utuh — dan ia akan berulang sekali per item dalam koleksi:
<<foreach [item in collection]>>
Content with <<[item.property]>>
<</foreach>>
Perulangan bisa bersarang (satu bagian per departemen, satu baris per karyawan di dalamnya) dan bisa memfilter atau mengurutkan koleksi sambil berjalan. Lihat Mengulang Paragraf & Bagian untuk contoh bersarang dan kondisional.
Bagaimana cara menambahkan gambar ke templat?
PDF4me dapat menarik gambar ke dokumen yang dihasilkan dari URL publik atau string Base64. Satu aturan penting: bidang gambar harus berada di dalam Kotak Teks Word. Buat kotak teks di tempat yang Anda inginkan untuk gambar, lalu tambahkan bidangnya.
Dari URL publik:
<<image [imageUrl]>>
Dari string berenkode Base64:
<<image [imageBase64]>>
Anda mengontrol ukuran dengan sakelar seperti -keepRatio, -fitHeight, -fitWidth, dan -fitSize, mis. <<image [companyLogo] -keepRatio>>. Referensi ukuran lengkap dan contoh gambar per baris ada di Menyisipkan Gambar.
Bagaimana cara menyisipkan HTML ke templat?
Jika data Anda sudah berisi HTML terformat, render di tempat dengan sakelar -html alih-alih meng-escape-nya sebagai teks biasa:
<<[token] -html>>
Mesin mem-parse nilai bidang sebagai HTML dan menerapkan pemformatannya — tebal, miring, daftar, judul, span berwarna, dan lainnya — di dalam dokumen yang dihasilkan. Tag dan gaya yang didukung tercantum di Menyisipkan HTML.
Olah data Anda dengan metode enumerasi
Selain bidang sederhana, mesin menyediakan metode bergaya IEnumerable yang bisa Anda panggil langsung di dalam sebuah token — memfilter, mengurutkan, menghitung, merata-ratakan, dan lainnya. Beberapa contoh:
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>>
Metode-metode ini berpadu alami dengan kondisi dan perulangan. Daftar metode lengkap — Where, OrderBy, GroupBy, Sum, Any, First, dan lainnya — ada di Enumerasi di Templat.
Data contoh terlihat seperti ini — seorang vendor, seorang pelanggan, dan daftar produk yang diiterasi oleh templat:
{
"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."
}
Perhatikan comments membawa HTML — pasangkan dengan sakelar <<[comments] -html>> dan tag <b> akan dirender tebal pada keluaran.
Tautan cepat untuk merancang templat Anda
Pertanyaan umum
Bagaimana cara membuat bidang gabungan di templat Word?
Ketik nama bidang di dalam tanda kurung sudut ganda dan kurung siku, seperti <<[CustomerName]>>, di mana pun Anda ingin menyisipkan nilai. Nama harus cocok dengan properti di sumber data JSON atau XML Anda. Anda bisa menambahkan bidang secara manual di mana saja — judul, paragraf, sel tabel, atau kotak teks.
Format templat apa saja yang didukung PDF4me?
Word (.docx, .doc), HTML, dan PDF. Ketiganya memakai sintaks bidang gabungan yang sama, jadi apa yang Anda pelajari untuk templat Word bisa dipindahkan. Word memberi kontrol paling lengkap atas tata letak, kondisi, tabel, dan gambar.
Bisakah saya menambahkan kondisi if/else ke templat Word?
Bisa. Bungkus konten dengan <<if [condition]>> ... <<elseif [condition]>> ... <<else>> ... <</if>>. Sebuah kondisi dapat membandingkan bidang secara langsung atau memanggil metode enumerasi seperti Any() atau Count(). Dengan begitu satu templat menangani setiap variasi data Anda alih-alih memelihara satu berkas per kasus.
Bagaimana cara memformat tanggal dan angka di templat?
Letakkan format setelah nama bidang dalam tanda kutip: <<[invoiceDate]:"dd.MM.yyyy">> untuk tanggal, <<[price]:"F2">> untuk angka dengan dua desimal. Huruf besar/kecil punya sakelar pendek — :upper, :caps, dan :firstCap.
Bagaimana cara menghasilkan tabel yang bertambah seiring data saya?
Buat tabel Word, buka <<foreach [item in collection]>> di sel pertama, taruh bidang gabungan di setiap sel sisanya, dan tutup dengan <</foreach>> di sel terakhir. Setiap item dalam koleksi otomatis menjadi satu baris.
Pemecahan masalah
Langkah berikutnya
Rancang templat sekali, hubungkan ke data Anda, dan PDF4me menghasilkan faktur, kontrak, serta laporan personalisasi sesuai permintaan — dari satu panggilan API atau automasi yang memproses ribuan sekaligus.