Belge oluşturma için gelişmiş şablonlar oluşturun

Adres mektup birleştirme ile belge oluşturma, bir veri kaynağından değerleri okuyup her birini bir şablondaki eşleşen yer tutucuya yerleştirme işidir. İki şey saklarsınız: birleştirme alanlarını (doldurulmayı bekleyen değişkenleri) içeren bir şablon ve değerleri ile her kopyada aynı kalan her şeyi sağlayan bir veri kaynağı. PDF4me'nin raporlama motoru bu iki dosyayı alır ve size bitmiş bir belge döndürür.

PDF4me Word, HTML ve PDF şablonlarını kabul eder ve üçü içinde en zengini Word'dür. Kısa, okunabilir bir söz dizimiyle faturaları, makbuzları, sözleşmeleri, teklifleri veya herhangi bir kişiye özel belgeyi kapsayan tek bir Word şablonu tasarlayabilir, ardından verilerden binlercesini oluşturabilirsiniz. Bu kılavuz tüm söz dizimini — birleştirme alanları, koşullar, biçimlendirme, tablolar, görseller ve satır içi HTML — kopyalamaya hazır örneklerle ve indirip çalıştırabileceğiniz bir örnek şablonla adım adım anlatır. Her söz dizimi bağlantısı Word şablon söz dizimi belgelerindeki tam sayfaya yönlendirir.

Bir Word şablonunu nasıl tasarlarsınız?​

Her şey tek bir yer tutucuyla başlar. Bir değerin yerleştirilmesini istediğiniz her yere alan adını çift açılı ayraç ve köşeli ayraç içinde yazın:

<<[FieldName]>>

Ayraçların içindeki adın veri kaynağınızdaki bir özellikle eşleşmesi gerekir. Adları açıklayıcı tutun, tek bir kurala bağlı kalın (camelCase veya PascalCase) ve özel karakterlerden kaçının. İşte en sade bir şablon ve onu dolduran veri:

Dear <<[CustomerName]>>,

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

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

Motor şunu döndürür:

Dear John Smith,

Thank you for your order #12345.

Bütün fikir bu kadar. Aşağıdaki her şey aynı ilkenin bir çeşitlemesidir — koşullar, döngüler ve biçimlendirme daima sıradan birleştirme alanlarını sarar. Tüm ayrıntılar Söz Dizimi Genel Bakışında yer alır.

Bir şablona koşulları nasıl eklersiniz?​

Generate Document eylemi verinize göre dallanabilir. Bir koşulun doğru olup olmamasına göre şu ya da bu içerik bloğunu yerleştirir. Temel if / elseif / else yapısı şöyle okunur:

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

Koşullar bir değeri doğrudan sınayabilir veya numaralandırma yöntemlerine dayanabilir (aşağıda daha fazlası), örneğin <<if [employees.Any(p => p.Age > 50)]>>. Karşılaştırma ve mantık operatörlerinin tam kümesini Koşullu Mantık sayfasında bulabilirsiniz.

Bir şablonda değerleri nasıl biçimlendirirsiniz?​

Çoğu zaman ham bir değerin yerleşmeden önce biçimlendirilmesi gerekir — belirli bir biçimde bir tarih, yuvarlanmış bir sayı, büyük harfe çevrilmiş metin. Alan adından sonra iki nokta üst üste ile ayrılmış ve tırnak içinde bir biçim belirtimi ekleyin:

<<[token]:"format">>

Tarihler .NET tarzı bir desen kullanır:

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

Büyük/küçük harfin kendi kısa anahtarları vardır — :upper, :caps (her kelimeyi büyük harfle) ve :firstCap:

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

Sayılar standart sayı biçimlerini kullanır; böylece <<[price]:"F2">> bir değeri iki ondalık basamağa sabitler. Tarih, metin ve sayı desenlerinin tam listesi Şablonlarda Biçimlendirme sayfasındadır.

Bir listeden nasıl tablo oluşturursunuz?​

Belge oluşturmanın gerçek gücü tablolarda ortaya çıkar — bir şablon satırı, verilerinizin sahip olduğu kadar satıra genişler. Normal bir Word tablosu oluşturun, ilk hücrede bir <<foreach>> döngüsü açın, izleyen her hücreye bir birleştirme alanı ekleyin ve döngüyü son hücrede kapatın:

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

products dizisindeki her nesne bir satır olur ve hücreleri başka her yerde olduğu gibi satır içi biçimlendirebilirsiniz. Filtrelenmiş ve toplulaştırılmış satırlar dahil daha fazla tablo deseni Şablonlarda Tablolar sayfasında ele alınır.

Paragrafları ve bölümleri nasıl tekrarlarsınız?​

Aynı <<foreach>> döngüsü tabloların dışında da çalışır. Herhangi bir içerik bloğunu — bir paragrafı, gövdesiyle bir başlığı, tüm bir bölümü — sarın; koleksiyondaki her öğe için bir kez tekrarlanır:

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

Döngüler iç içe geçebilir (departman başına bir bölüm, içinde çalışan başına bir satır) ve koleksiyonu yol boyunca filtreleyebilir veya sıralayabilir. İç içe ve koşullu örnekler için Paragrafları ve Bölümleri Tekrarlama sayfasına bakın.

Bir şablona nasıl görsel eklersiniz?​

PDF4me, oluşturulan bir belgeye görselleri herkese açık bir URL'den veya bir Base64 dizesinden ekleyebilir. Bir kural önemlidir: görsel alanı bir Word Metin Kutusunun içinde olmalıdır. Görseli istediğiniz yerde metin kutusunu oluşturun, ardından alanı ekleyin.

Herkese açık bir URL'den:

<<image [imageUrl]>>

Base64 kodlu bir dizeden:

<<image [imageBase64]>>

Boyutu -keepRatio, -fitHeight, -fitWidth ve -fitSize gibi anahtarlarla denetlersiniz, örn. <<image [companyLogo] -keepRatio>>. Tam boyut başvurusu ve satır başına görsel örnekleri Görsel Ekleme sayfasındadır.

Bir şablona HTML'yi nasıl eklersiniz?​

Verileriniz zaten biçimlendirilmiş HTML içeriyorsa, onu düz metin olarak kaçırmak yerine -html anahtarıyla yerinde işleyin:

<<[token] -html>>

Motor alan değerini HTML olarak ayrıştırır ve oluşturulan belgenin içinde biçimlendirmeyi uygular — kalın, italik, listeler, başlıklar, renkli span'ler ve daha fazlası. Desteklenen etiketler ve stiller HTML Ekleme sayfasında listelenir.

Verilerinizi numaralandırma yöntemleriyle işleyin​

Basit alanların ötesinde, motor bir token içinde doğrudan çağırabileceğiniz IEnumerable tarzı yöntemler sunar — filtreleme, sıralama, sayma, ortalama alma ve daha fazlası. Birkaç örnek:

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>>

Bunlar koşullar ve döngülerle doğal biçimde birleşir. Yöntemlerin tam listesi — Where, OrderBy, GroupBy, Sum, Any, First ve gerisi — Şablonlarda Numaralandırma sayfasındadır.

Örnek veri şöyle görünür — bir satıcı, bir müşteri ve şablonun üzerinde döngü kurduğu bir ürün listesi:

{
  "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 alanının HTML taşıdığına dikkat edin — bunu <<[comments] -html>> anahtarıyla eşleştirin; <b> etiketi çıktıda kalın olarak işlenir.

Şablonunuzu tasarlamak için hızlı bağlantılar​

Sık sorulan sorular​

Bir Word şablonunda birleştirme alanlarını nasıl oluştururum?​

Bir değer eklemek istediğiniz her yere alan adını çift açılı ve köşeli ayraç içinde yazın, örneğin <<[CustomerName]>>. Adın JSON veya XML veri kaynağınızdaki bir özellikle eşleşmesi gerekir. Alanları her yere elle ekleyebilirsiniz — başlıklar, paragraflar, tablo hücreleri veya metin kutuları.

PDF4me hangi şablon biçimlerini destekler?​

Word (.docx, .doc), HTML ve PDF. Üçü de aynı birleştirme alanı söz dizimini kullanır; bu yüzden bir Word şablonu için öğrendikleriniz taşınabilir. Word; düzen, koşullar, tablolar ve görseller üzerinde en kapsamlı denetimi sunar.

Bir Word şablonuna if/else koşulları ekleyebilir miyim?​

Evet. İçeriği <<if [condition]>> ... <<elseif [condition]>> ... <<else>> ... <</if>> ile sarın. Bir koşul bir alanı doğrudan karşılaştırabilir veya Any() ya da Count() gibi bir numaralandırma yöntemini çağırabilir. Böylece tek bir şablon, her durum için bir dosya tutmak yerine verilerinizin her çeşidini yönetir.

Bir şablonda tarihleri ve sayıları nasıl biçimlendiririm?​

Biçimi alan adından sonra tırnak içinde koyun: bir tarih için <<[invoiceDate]:"dd.MM.yyyy">>, iki ondalıklı bir sayı için <<[price]:"F2">>. Büyük/küçük harfin kısa anahtarları vardır — :upper, :caps ve :firstCap.

Verilerimle büyüyen bir tabloyu nasıl oluştururum?​

Bir Word tablosu oluşturun, ilk hücrede <<foreach [item in collection]>> açın, kalan her hücreye bir birleştirme alanı koyun ve son hücrede <</foreach>> ile kapatın. Koleksiyondaki her öğe otomatik olarak bir satır olur.

Sorun giderme​

Sonraki adımlar​

Şablonu bir kez tasarlayın, verilerinize bağlayın; PDF4me talep üzerine kişiye özel faturalar, sözleşmeler ve raporlar üretir — tek bir API çağrısından veya aynı anda binlercesini işleyen bir otomasyondan.

Kaynaklar​

• Word Şablon Söz Dizimi — Genel Bakış
• Şablonlarda Biçimlendirme
• Şablonlarda Tablolar
• Görsel Ekleme
• HTML Ekleme
• Koşullu Mantık ve Numaralandırma
• Document Generation API