Desain Pencetakan

Kapan Dipakai

• Saat format cetakan perlu disesuaikan, misalnya menambah logo, mengganti judul, mengatur kolom tabel, atau mengubah ukuran kertas.
• Saat implementor ingin membuat variasi template tanpa mengubah aplikasi utama.
• Saat desain lama perlu diduplikasi lebih dulu sebelum diubah, supaya versi awal masih aman.
• Saat template perlu dipindahkan antar server dengan export dan import file JSON.
• Saat template cetak tidak tampil rapi di printer dan perlu dicek dari HTML/EJS serta default page setup.

Konsep Dasar

• Print File adalah file desain cetak yang dipilih dari server. Setelah file dipilih, halaman memuat nama desain, kode desain, template, status aktif, dan pengaturan kertasnya.
• Name adalah nama yang mudah dikenali user. Nama ini membantu membedakan desain ketika daftar template mulai banyak.
• Group Design adalah kode/path desain. Kode ini penting karena form lain biasanya memanggil desain berdasarkan path tersebut. Jangan menggantinya sembarangan kalau template sudah dipakai transaksi.
• Template adalah isi cetakan dalam bentuk HTML/EJS. HTML menentukan tampilan, sedangkan EJS mengambil data dari transaksi, melakukan pengulangan baris, menampilkan total, atau membuat kondisi seperti menampilkan kolom tertentu hanya bila diperlukan.
• Code cocok untuk implementor yang nyaman membaca HTML/EJS langsung. WYSIWYG cocok untuk perubahan visual ringan, seperti teks, tabel, dan susunan dasar.
• EJS chip adalah penanda kode EJS di mode WYSIWYG. Chip ini sengaja dibuat agar kode seperti <%= ... %> tidak rusak saat diedit secara visual. Klik Edit pada chip untuk mengubah kode EJS-nya.
• Default Page Setup menentukan ukuran kertas, orientasi portrait/landscape, lebar-tinggi custom, dan margin. Ini memengaruhi hasil print, terutama printer kasir, printer thermal, dan dokumen dengan tabel lebar.
• Active menandai apakah desain ini masih dipakai. Desain nonaktif sebaiknya tidak dijadikan pilihan pada konfigurasi cetak.

Alur Penggunaan

1. Buka menu Pengaturan / Designer & Menu / Desain Pencetakan.
2. Pilih Print File yang akan diedit. Setelah dipilih, halaman membaca file JSON-nya dan mengisi Name, Group Design, Template, status Active, serta Default Page Setup.
3. Untuk perubahan aman, klik Duplicate lebih dulu. Sistem membuat nama file lanjutan secara otomatis, lalu menyimpan salinan sebagai desain baru.
4. Edit Name bila perlu, tetapi hati-hati dengan Group Design. Group Design berhubungan dengan pemanggilan template dari form lain.
5. Edit template dari tab Code atau WYSIWYG. Untuk perubahan struktur yang memakai pengulangan data, kondisi, atau perhitungan, gunakan tab Code agar kode EJS tetap jelas.
6. Atur Default Page Setup: paper size, custom width/height, margin kiri-kanan-atas-bawah, dan orientasi cetak.
7. Klik Save untuk menyimpan desain ke server. Klik Save as JSON bila perlu backup lokal sebelum perubahan besar.
8. Gunakan Import bila ada file JSON desain dari server lain. Setelah import, periksa lagi nama file dan Group Design sebelum disimpan ke server.
9. Gunakan Delete hanya untuk desain yang sudah tidak dipakai. Jangan menghapus template yang masih dipakai transaksi aktif.

Cara Membaca Template

• Bagian teks biasa di template akan tercetak apa adanya. Contoh: judul nota, nama kolom, catatan, atau footer.
• Kode EJS dengan bentuk <%= ... %> berarti menampilkan nilai, misalnya nomor transaksi, tanggal, nama customer, atau total.
• Kode EJS dengan bentuk <% ... %> biasanya dipakai untuk logika, seperti if, for, menghitung subtotal, atau menyiapkan variabel sebelum tabel dicetak.
• Tabel biasanya berisi baris header dan baris detail. Kalau jumlah baris detail mengikuti isi transaksi, berarti ada EJS loop di bagian tersebut.
• Di mode WYSIWYG, kode EJS ditampilkan sebagai chip agar user tidak perlu melihat seluruh kode. Namun untuk perubahan yang rumit, tetap lebih aman membuka tab Code.
• Template dirender sebagai fungsi async. Pemanggilan yang menghasilkan Promise, seperti getDataFromTable, wajib memakai await; tanpa itu nilainya undefined dan EJS mencetak sel kosong tanpa pesan error.

Mengambil Data Tabel Lain (getDataFromTable)

Sebagian kolom cetakan tidak tersedia di data transaksi dan harus diambil dari tabel lain, misalnya nama, alamat, atau nomor HP pelanggan dari tabel customer. Untuk itu template memakai getDataFromTable. Fungsi ini membaca satu baris berdasarkan satu kolom kunci, lalu mengembalikan seluruh kolom baris tersebut.

Bentuk pemanggilannya:

const baris = await getDataFromTable(namaTabel, namaKolom, nilaiKunci)

Hasilnya satu baris data, atau objek kosong bila tidak ada baris yang cocok. Contoh pada desain Faktur Penjualan untuk melengkapi nama dan alamat pelanggan dari data.customerid:

<%
  const customer = await getDataFromTable('customer', 'id', data.customerid)
%>
<td><%= customer.name || '' %></td>
<td><%= customer.address || '' %></td>

Bila hanya satu kolom yang dipakai, pemanggilannya boleh ditulis langsung:

<%= (await getDataFromTable('customer', 'id', data.customerid)).mobilephone || '' %>

Yang Perlu Diingat

• getDataFromTable bersifat async, jadi wajib memakai await. Tanpa await, yang dipakai adalah Promise, bukan baris datanya.
• Kutip tunggal dan backslash di nilaiKunci di-escape otomatis. Jangan menambahkan replace(/'/g, "''") sendiri: hasilnya escape ganda dan id yang mengandung apostrof justru tidak ditemukan.
• Bila nilaiKunci kosong, null, atau undefined, fungsi tidak menjalankan kueri dan langsung mengembalikan objek kosong.
• Baris tidak ditemukan, permintaan ditolak server, dan sesi yang sudah habis sama-sama menghasilkan objek kosong tanpa pesan. Bila semua panggilan kosong sementara kolom data lain tercetak normal, periksa dulu nama tabel/kolom dan status login.
• Hanya untuk membaca data (SELECT). Perubahan data tidak bisa dilakukan dari template dan akan ditolak server.
• Satu pemanggilan berarti satu permintaan ke server. Jangan memanggilnya di dalam loop yang panjang; data yang sudah tersedia di data (misalnya data.customername) sebaiknya dipakai langsung.
• Pada desain daftar, data berisi array baris, jadi panggilan diletakkan di dalam loop dan memakai field tiap baris, misalnya item.customerid. Pada desain form, data adalah satu transaksi, misalnya data.customerid.
• Fungsi ini tidak tersedia pada tiket kiosk antrean (dicetak tanpa sesi pengguna) dan tidak dijalankan di pratinjau Print Designer. Uji hasilnya lewat Preview transaksi yang sebenarnya.

Kesalahan Umum

Tombol di Bagian Atas

• Refresh mengambil ulang daftar print file dari server.
• Import membuka file JSON dari komputer dan memasukkannya ke halaman designer.
• Duplicate membuat salinan dari desain yang sedang dipilih. Ini cara paling aman sebelum mengubah template standar.
• Save menyimpan desain ke server dengan nama file yang sedang dipilih.
• Save as JSON mengunduh desain sebagai file JSON untuk backup atau dipindahkan ke server lain.
• Delete menghapus file desain dari server setelah konfirmasi.

Modifikasi Desain dengan AI

Panel Modifikasi desain dengan AI membantu mengubah desain tanpa menulis kode sendiri. Panel ini tersedia bagi pengguna yang role-nya memiliki Izin Memakai AI dan memakai saldo kredit yang sama dengan Asisten AI.

1. Pilih desain yang ingin diubah, lalu tulis kebutuhan pada kolom Perubahan yang diinginkan. Contoh: sesuaikan nota untuk kertas 80 mm, perbesar nama perusahaan, dan tambahkan ruang tanda tangan.
2. Klik Buat usulan perubahan. AI menampilkan ringkasan dan perbandingan Sebelum dengan Usulan AI; kredit yang terpakai dan sisa saldo ikut tampil.
3. Klik Terapkan ke editor bila usulan cocok, atau Tutup usulan bila tidak. Menerapkan atau membatalkan usulan tidak memakai kredit lagi.
4. Periksa hasil di editor, lalu simpan dengan tombol simpan designer seperti biasa. Batalkan perubahan AI mengembalikan desain ke kondisi sebelum diterapkan selama belum ada pengeditan lain.

Hal yang Perlu Diperhatikan

• Sebelum mengubah template yang sudah dipakai operasional, export JSON atau duplicate dulu. Perubahan kecil pada EJS bisa membuat cetakan gagal render.
• Jangan menghapus atau mengganti Group Design bila belum tahu form mana yang memakai template tersebut.
• Jika hasil cetak melebar atau terpotong, cek Default Page Setup lebih dulu: paper size, orientasi, dan margin.
• Jika data transaksi tidak muncul, masalahnya biasanya bukan di layout tabel, tetapi pada kode EJS yang mengambil field data. Bila yang kosong hanya hasil getDataFromTable, periksa dulu await dan nilai kuncinya.
• Mode WYSIWYG membantu untuk perubahan visual, tetapi bisa kurang cocok untuk template yang berisi banyak kondisi dan loop. Untuk template seperti itu, gunakan tab Code.
• File desain disimpan sebagai JSON. Gunakan Save untuk menyimpan ke server, Save as JSON untuk backup, dan Import untuk memindahkan desain dari file lain.

Lokasi Menu

• Pengaturan / Designer & Menu / Desain Pencetakan
  /printdesigner