Integrasi dalam 10 menit

Panduan memasang DdDesignReport sebagai fitur di aplikasi Anda: pelanggan mengubah sendiri tata letak faktur, struk, atau slip gajinya, dan aplikasi mencetaknya dengan data dari database Anda.

Contoh lengkapnya, yang bisa langsung dijalankan, ada di examples/app: satu server Node.js (±120 baris, tanpa framework) dan satu halaman.

cd examples/app
npm install
node server.js          # buka http://localhost:3000

Gambaran

Ada empat bagian, dan hanya dua yang perlu Anda tulis sendiri:

 browser                               server Anda                          ddreport
┌─────────────────────┐  simpan     ┌──────────────────────────┐
│ designer            │ ──────────► │ tabel template:          │
│ (ddreport-designer) │  JSON       │ (pelanggan, laporan) →   │
│                     │             │ JSON template            │
│ tombol Preview      │ ──────────► │                          │  template + data   ┌──────────┐
│ tombol Cetak / PDF  │ ──────────► │ query data laporan  ─────┼──────────────────► │ render   │
└─────────────────────┘ ◄────────── │                          │ ◄──────────────────│ PDF, ... │
                         dokumen    └──────────────────────────┘     dokumen        └──────────┘

1. Designer di halaman: satu createDesigner(...).
2. Penyimpanan template: satu baris per pelanggan dan laporan. Ini milik Anda.
3. Data laporan: query yang sudah Anda punya, dibentuk seperti yang dibaca template. Ini juga milik Anda.
4. Render: satu panggilan, dari Node.js, Java, Kotlin, Go, atau HTTP untuk PHP, Python, dan .NET.

Template disimpan di server Anda dan dikirim ke ddreport bersama datanya setiap kali dicetak; render sendiri tidak menyimpan apa pun.

1. Designer di halaman

npm install ddreport-designer

import { createDesigner } from 'ddreport-designer'

const designer = createDesigner(document.getElementById('designer'), {
  lang: 'id',
  simple: true,                       // untuk admin dan staf: alat yang perlu saja, setiap tombol bernama
  preview: async template =>          // tombol Preview: server Anda mencetaknya sebagai HTML
    (await fetch('/api/preview/invoice', { method: 'POST', body: JSON.stringify(template) })).text(),
})

const { template, data } = await (await fetch('/api/templates/invoice')).json()
designer.setTemplate(template)
designer.setData(data)               // contoh data: chart di kanvas, menu Field, dan peringatan field yang salah ketik

Tanpa bundler, sajikan node_modules/ddreport-designer/designer.js sebagai file statis lalu import { createDesigner } from '/designer.js', seperti di contoh. Untuk React dan Vue: README paket designer.

Di Laravel atau framework lain tanpa npm: unduh https://cdn.jsdelivr.net/npm/ddreport-designer@0.4.3/designer.js ke folder public/, lalu import { createDesigner } from '/designer.js'. Satu file, tanpa dependency.

2. Menyimpan template per pelanggan

Satu tabel cukup:

CREATE TABLE report_templates (
  customer_id BIGINT       NOT NULL,
  report      VARCHAR(50)  NOT NULL,   -- 'invoice', 'receipt', ...
  template    JSON         NOT NULL,
  updated_at  TIMESTAMP    NOT NULL,
  PRIMARY KEY (customer_id, report)
);

Selama pelanggan belum menyimpan tata letaknya sendiri, pakai template siap pakai (ddreport-designer/templates/invoice.json, atau buatan Anda). Saat menyimpan, coba render dulu dengan datanya, agar template yang tidak bisa dicetak ditolak dengan pesan yang jelas:

await renderer.render(template, data, 'html') // melempar error dengan penjelasan bila template rusak
db.save(customerId, 'invoice', template)

customerId selalu diambil dari sesi login di server, bukan dari permintaan browser, agar pelanggan tidak bisa membuka template pelanggan lain.

3. Bentuk data

Template membaca satu objek: field biasa untuk kop dan total, ditambah daftar rows yang diulang di band detail.

{
  "number": "INV-0042",
  "customer": { "name": "Toko Maju", "city": "Sleman" },
  "items": [ { "name": "Kopi", "qty": 2, "price": 18000 } ],
  "rows":  [ { "name": "Kopi", "qty": 2, "price": 18000 } ]
}

Faktur biasanya dua query: kepala faktur menjadi field, baris barangnya menjadi rows. Angka yang dikirim database sebagai teks ("18000.00") tetap dihitung sebagai angka.

Field yang salah ketik

Placeholder yang field-nya tidak ada di data tercetak kosong, tanpa error. Ada tiga cara menangkapnya:

• Preview di designer menyebutnya: "Tidak ada di data contoh, tercetak kosong: nmae", selama designer diberi contoh data (data) atau daftar field (fields).
• DDREPORT_STRICT=1 di lingkungan binary atau server membuat render gagal dengan nama field-nya, alih-alih mencetak kosong. Cocok untuk test dan staging.
• Dari Go: ddreport.Missing(template, data) mengembalikan daftarnya.

4. Render

Node.js (npm install ddreport, binary untuk sistemnya ikut terpasang):

const { createRenderer } = require('ddreport')
const renderer = createRenderer()   // satu proses yang terus berjalan

app.get('/reports/invoice/:id.pdf', async (req, res) => {
  const template = await db.template(req.user.customerId, 'invoice')
  const data = await invoiceData(req.params.id)          // query Anda
  res.type('pdf').send(await renderer.render(template, data, 'pdf'))
})

Format lain: 'xlsx', 'xls', 'csv', 'html', 'escpos' (printer struk), 'txt'.

Laravel, lewat server ddreport (Docker) di mesin yang sama atau lain:

docker run -d -p 8080:8080 -e DDREPORT_TOKEN=rahasia-panjang ghcr.io/gvjavx/ddreport

// routes/web.php
Route::get('/reports/invoice/{invoice}.pdf', function (Invoice $invoice) {
    $template = ReportTemplate::for(auth()->user()->customer_id, 'invoice');   // JSON tersimpan
    $data = [
        'number'   => $invoice->number,
        'customer' => ['name' => $invoice->customer->name],
        'rows'     => $invoice->items->map->only(['name', 'qty', 'price']),
    ];
    $pdf = Http::withToken(env('DDREPORT_TOKEN'))
        ->post('http://localhost:8080/render?format=pdf', ['template' => json_decode($template), 'data' => $data])
        ->throw()->body();
    return response($pdf)->header('Content-Type', 'application/pdf');
});

// Preview dari designer: template yang sedang diubah, dengan data sungguhan
Route::post('/api/preview/invoice', fn (Request $r) => Http::withToken(env('DDREPORT_TOKEN'))
    ->post('http://localhost:8080/render?format=html', ['template' => $r->json()->all(), 'data' => /* data contoh */ []])
    ->throw()->body());

Java dan Kotlin: DdReport.render(templateJson, dataJson, "pdf"), atau new DdReport.Renderer() di server. Go: ddreport.Render(template, data, "pdf"). Selengkapnya di README.

5. Cetak ke printer struk

escpos menghasilkan perintah printer, bukan gambar. Browser tidak bisa mengirimnya ke printer begitu saja; pilih jalur yang cocok dengan printernya:

Lebar baris mengikuti lebar kertas di template (Struk 58 mm = 32 karakter, 80 mm = 48); ubah dengan Karakter per baris bila printer Anda berbeda.

Masalah yang sering muncul

Butuh dibantu memasangnya? Lihat jasa.