QWeb (XML templating) — UI & report template

Selamat datang di bagian ketiga FAQ OdooCamp: QWeb (XML templating) untuk antarmuka dan template report. Prolog ini menyiapkan kerangka pikir sebelum kita masuk ke daftar pertanyaan teknis yang sering diajukan developer.

Mengapa QWeb Penting?

QWeb adalah mesin templating Odoo berbasis XML. Kita memakainya untuk:

• Report: faktur, sales order, delivery slip, dsb.

• Portal & Website: halaman pelanggan, formulir publik, komponen UI.

• Fragmen UI backend: potongan tampilan tertentu yang dirender via QWeb.

Dengan QWeb, kita bisa memisahkan presentasi dari logika. Python menyiapkan data, QWeb merendernya secara aman dan terstruktur.

Mindset Kerja yang Kita Pakai

Context → Template → Render

• Context: objek dan variabel yang tersedia (mis. o, docs, request, user).

• Template: <template id="..."> berisi elemen HTML + direktif QWeb.

• Render: QWeb memproses direktif menjadi HTML akhir (untuk layar atau PDF).

Direktif QWeb yang paling sering kita gunakan:

• t-esc: menampilkan teks aman (escaped).

• t-raw: menampilkan HTML apa adanya (hanya untuk konten tepercaya).

• t-if / t-elif / t-else: percabangan.

• t-foreach + t-as: perulangan.

• t-set: menyimpan nilai sementara di template.

• t-call: memanggil template lain (layout/partial).

• t-att-* / t-attf-*: binding atribut HTML dinamis.

• t-options: opsi format (uang, tanggal, waktu, angka) terutama pada report.

Di Mana QWeb Berada dalam Proyek

• Report: report/*_templates.xml (definisi template) dan report/*.xml (binding report ke model/aksi).

• Portal/Website: views/*_templates.xml atau website_*_templates.xml.

• Fragmen backend: template kecil yang dipakai komponen/kanban.

Ruang Lingkup yang Akan Kita Bahas di FAQ QWeb

1. Anatomi template: <template id="...">, t-call, slot konten.

2. Keamanan output: kapan pakai t-esc vs t-raw.

3. Format nilai: t-options untuk uang/tanggal/angka.

4. Kontrol alur: t-if, t-foreach, t-set, pola partial.

5. Inheritance template: inherit_id + xpath pada QWeb.

6. Report binding: ir.actions.report, context, dan evaluasi.

7. Portal/website: penggunaan request.*, parameter URL, dan form.

8. Styling: CSS untuk layar vs cetak; penataan tabel report.

9. Diagnostik: membaca error QWeb, melihat HTML hasil render, override antar modul.

Anatomi Dasar Template

<template id="report_my_model_document">
  <t t-call="web.external_layout">
    <div class="page">
      <h2><span t-esc="o.name"/></h2>
      <p>Total: <span t-esc="o.amount_total" t-options='{"widget":"monetary", "display_currency": o.currency_id}'/></p>
    </div>
  </t>
</template>

Poin penting: kita memanggil layout via t-call, lalu mengisi konten halaman di dalamnya. Semua nilai teks/angka default‑nya t-esc untuk keamanan.

Prinsip Utama (Do/Don’t)

Do

• Gunakan t-esc sebagai default; tambah t-options untuk format uang/tanggal/angka.

• Pecah template menjadi partial dan gunakan t-call untuk DRY.

• Gunakan t-if/t-foreach seperlunya; jaga logika tetap tipis di layer presentasi.

• Gunakan t-att-* untuk atribut dinamis (mis. class, title, href) agar markup bersih.

Don’t

• Jangan menaruh logika bisnis berat di template; siapkan data di Python.

• Jangan memakai t-raw untuk input pengguna atau konten yang tidak disanitasi.

• Jangan mengandalkan urutan DOM yang rapuh saat melakukan inheritance; gunakan xpath yang spesifik.

Debugging & Observabilitas

• Aktifkan Developer Mode untuk melihat daftar template dan struktur final.

• Pada report, buka print preview lalu inspeksi HTML akhir (developer tools) untuk memeriksa class/struktur.

• Cek log server jika terjadi error QWeb (nama template/id yang gagal dirender akan disebutkan).

Checklist Sebelum Masuk ke FAQ Detail

• Semua output teks/angka menggunakan t-esc.

• Format uang/tanggal memakai t-options sesuai locale.

• Partial/layout tersusun rapi dan dapat dipakai ulang.

• Inheritance QWeb menggunakan xpath yang unik dan stabil.

• Gaya cetak (CSS) memadai untuk tabel panjang dan total.

Yang Akan Kita Jawab di FAQ QWeb

• Perbedaan dan penggunaan tepat t-esc vs t-raw dengan contoh kasus.

• Widget format via t-options (monetary, float, date, datetime, float_time).

• Cara meng‑inherit template base dan menambahkan blok baru tanpa merusak layout.

• Menghubungkan template ke ir.actions.report dan mengelola context.

• Pola aman membaca parameter (request.params) di portal.

• Tips styling report agar rapih di layar dan PDF.

Dengan prolog ini, kita siap melangkah ke FAQ QWeb (XML templating) — UI & report template dan mengupas kasus nyata yang sering muncul di proyek Odoo 18 CE.