Skip to main content

​
English Documentation

​
Guide to Creating a DOCX Invoice Template for docx:generate

This guide provides a step-by-step walkthrough for creating a powerful and flexible .docx invoice template. This template is specifically designed to work with the docx:generate command, utilizing its features for simple text replacement, conditional blocks, table looping, and mode-aware image handling.

​
Prerequisites

  • A word processing application (e.g., Microsoft Word, Google Docs, LibreOffice Writer).
  • The docx:generate command from the previous guide, including the updated logic for image handling.

​
Visual Template Layout & Step-by-Step Guide

Create a new .docx document and lay it out as described below. All text in ${...} format are placeholders that the command will replace. 1. Header Section Place your logo placeholder at the top. Below it, add the placeholders for your company’s information.
2. Invoice Details Section For right-aligned content, it’s often easiest to use a borderless table. 3. Conditional “Bill To” Section This entire block will only appear if the bill_present key in your JSON is true.
4. Items Table Create a table with a header row and only one data row. This single data row will serve as the template for the loop. Apply any desired formatting (borders, background colors, text alignment) to this row, and it will be duplicated for every item. 5. Summary Section Again, a right-aligned, borderless table is perfect for the totals. Apply formatting like bold or larger font sizes directly to the placeholders.

​
Detailed Placeholder Tag Explanation

1. Simple Variable Placeholder
  • Syntax: ${variable_name}
  • Usage: Replaces the placeholder with a value from the JSON data. Supports dot notation for nested objects (e.g., ${bill_to.name}).
  • Example: ${company_name} is replaced by the value of the company_name key in the JSON.
2. Image Placeholder (${logo} - Special Handling)
  • Syntax: ${logo}
  • Behavior: The command handles this placeholder differently based on the --mode option:
  • --mode=merge or --mode=pdf: The image from the URL in your JSON is downloaded and embedded directly into the document. The resulting file is self-contained.
  • --mode=html or --mode=blade: The placeholder is replaced with a standard HTML <img> tag. The src attribute will point to the URL from your JSON. This is ideal for web pages.
3. Conditional Block
  • Syntax: ${block_name} ... ${/block_name}
  • Usage: Encloses a section of the document that should only appear if a corresponding boolean key in the JSON is true.
  • Example: The content between ${if_bill} and ${/if_bill} will only be included in the final document if "bill_present": true exists in the JSON file.
4. Table Row Loop
  • Syntax: Place placeholders like ${item.key} in the cells of a single table row.
  • Usage: The cloneRow function in the command identifies this row and duplicates it for every object in the specified array (e.g., item_list in the JSON).
  • Example: The row containing ${item.no} will be repeated for each item in the item_list array. The ${item.name} placeholder will be replaced with the name key from the corresponding array object.

​
Dokumentasi Bahasa Indonesia

​
Panduan Membuat Templat Faktur DOCX untuk docx:generate

Panduan ini menyediakan langkah-langkah untuk membuat templat faktur .docx yang andal dan fleksibel. Templat ini dirancang khusus untuk bekerja dengan perintah docx:generate, memanfaatkan fiturnya untuk penggantian teks sederhana, blok kondisional, perulangan baris tabel, dan penanganan gambar yang cerdas sesuai mode.

​
Prasyarat

  • Aplikasi pengolah kata (misalnya, Microsoft Word, Google Docs, LibreOffice Writer).
  • Perintah docx:generate dari panduan sebelumnya, termasuk pembaruan logika untuk penanganan gambar.

​
Tata Letak Visual Templat & Panduan Langkah-demi-Langkah

Buat dokumen .docx baru dan atur tata letaknya seperti yang dijelaskan di bawah. Semua teks dalam format ${...} adalah placeholder yang akan diganti oleh perintah. 1. Bagian Header Letakkan placeholder logo Anda di bagian paling atas. Di bawahnya, tambahkan placeholder untuk informasi perusahaan Anda.
2. Bagian Detail Faktur Untuk konten yang rata kanan, cara termudah adalah menggunakan tabel tanpa garis batas. 3. Bagian Kondisional “Tagihan Untuk” Seluruh blok ini hanya akan muncul jika kunci bill_present di JSON Anda bernilai true.
4. Tabel Item Buat tabel dengan satu baris header dan hanya satu baris data. Baris data tunggal ini akan berfungsi sebagai templat untuk perulangan. Terapkan format apa pun yang diinginkan (garis batas, warna latar, perataan teks) pada baris ini, dan format tersebut akan diduplikasi untuk setiap item. 5. Bagian Ringkasan Sekali lagi, tabel tanpa batas yang rata kanan sangat cocok untuk bagian total. Terapkan format seperti teks tebal atau ukuran font yang lebih besar langsung pada placeholder.

​
Penjelasan Detail Tag Placeholder

1. Placeholder Variabel Sederhana
  • Sintaks: ${nama_variabel}
  • Penggunaan: Mengganti placeholder dengan nilai dari data JSON. Mendukung notasi titik untuk objek bersarang (misalnya, ${bill_to.name}).
  • Contoh: ${company_name} diganti dengan nilai dari kunci company_name di JSON.
2. Placeholder Gambar (${logo} - Penanganan Khusus)
  • Sintaks: ${logo}
  • Perilaku: Perintah menangani placeholder ini secara berbeda berdasarkan opsi --mode:
  • --mode=merge atau --mode=pdf: Gambar dari URL di JSON Anda akan diunduh dan disematkan (embedded) langsung ke dalam dokumen. File yang dihasilkan mandiri dan tidak memerlukan koneksi internet untuk menampilkan gambar.
  • --mode=html atau --mode=blade: Placeholder diganti dengan tag HTML standar <img>. Atribut src akan menunjuk ke URL dari JSON Anda. Ini adalah perilaku yang ideal untuk halaman web.
3. Blok Kondisional
  • Sintaks: ${nama_blok} ... ${/nama_blok}
  • Penggunaan: Melingkupi bagian dokumen yang hanya boleh muncul jika kunci boolean yang sesuai di JSON bernilai true.
  • Contoh: Konten di antara ${if_bill} dan ${/if_bill} hanya akan disertakan dalam dokumen akhir jika terdapat "bill_present": true di file JSON.
4. Perulangan Baris Tabel
  • Sintaks: Letakkan placeholder seperti ${item.key} di dalam sel-sel dari satu baris tabel tunggal.
  • Penggunaan: Fungsi cloneRow dalam perintah akan mengidentifikasi baris ini dan menduplikasinya untuk setiap objek dalam array yang ditentukan (misalnya, item_list di JSON).
  • Contoh: Baris yang berisi ${item.no} akan diulang untuk setiap item dalam array item_list. Placeholder ${item.name} akan diganti dengan kunci name dari objek array yang bersangkutan.