SCSS / CSS — styling & theming

Selamat datang di bagian kelima FAQ OdooCamp: SCSS / CSS — styling & theming. Prolog ini menyiapkan fondasi agar kita memiliki peta yang sama sebelum memasuki pertanyaan‑pertanyaan teknis yang sering diajukan developer saat memoles tampilan Odoo 18 CE (backend, portal/website, dan report/PDF).

Mengapa SCSS/CSS Penting di Odoo?

Lapisan visual Odoo dipisahkan dari logika Python dan struktur view XML. Dengan SCSS/CSS kita:

• Menjaga branding konsisten (warna, tipografi, komponen UI).

• Menyesuaikan UX tanpa menyentuh business logic.

• Mengoptimalkan print/report agar tampil rapi di PDF.

SCSS memberi kemampuan variabel, nesting, mixin, dan utilitas lain yang memudahkan pengelolaan style berskala besar.

Mindset Kerja

Assets Manifest → SCSS Source → Bundle → View/Template

• Daftarkan berkas kita ke bundle assets yang tepat.

• Tulis SCSS modular dengan variabel & mixin.

• Render melalui view/template; hindari inline style.

Ruang Lingkup yang Akan Kita Bahas di FAQ SCSS/CSS

1. Bundle & Assets: web.assets_backend, web.assets_frontend, dan bundle report.

2. Variabel & Theming: override variabel SCSS global; kapan memakai CSS variables.

3. Struktur & Konvensi: penamaan class, modularisasi, utilitas.

4. Backend vs Frontend: perbedaan konteks dan class inti Odoo.

5. Report Styling (PDF): ukuran, tabel, page breaks.

6. Diagnostik: cache assets, prioritas CSS, konflik spesifisitas.

Bundling Aset di __manifest__.py

Tambahkan file SCSS/JS ke bundle yang sesuai.

# __manifest__.py (contoh ringkas)
{
    "name": "my_module",
    "version": "1.0",
    "depends": ["web"],
    "assets": {
        # Backend (kanban, form, tree, dsb.)
        "web.assets_backend": [
            "my_module/static/src/scss/backend.scss",
        ],
        # Portal/Website (termasuk halaman portal bawaan)
        "web.assets_frontend": [
            "my_module/static/src/scss/frontend.scss",
        ],
        # Variabel SCSS tingkat awal (override sebelum bootstrap/tema diproses)
        "web._assets_primary_variables": [
            "my_module/static/src/scss/variables.scss",
        ],
        # Report/PDF
        "web.report_assets_common": [
            "my_module/static/src/scss/report_common.scss",
        ],
        "web.report_assets_pdf": [
            "my_module/static/src/scss/report_pdf.scss",
        ],
    },
}

Catatan:

• web._assets_primary_variables dipakai untuk override variabel SCSS lebih awal (mis. warna brand) agar konsisten di semua bundle.

• Untuk modul Website, kita tetap dapat menambahkan ke web.assets_frontend. Editor Website memiliki bundel tambahannya sendiri, namun untuk styling tampilan pengunjung, web.assets_frontend biasanya cukup.

Anatomi Minimal SCSS

// static/src/scss/variables.scss
$brand-primary: #6f42c1; // contoh override warna brand
$body-color: #2b2b2b;
$font-size-base: 0.95rem;

// static/src/scss/backend.scss
.o_form_sheet {
  // jaga padding & lebar agar konsisten
  padding: 16px 24px;
}
.oe_button_box .oe_stat_button {
  min-width: 120px;
}

// static/src/scss/frontend.scss
.o_portal_my_doc {
  margin-top: 1.5rem;
  .o_portal_my_doc_header {
    display: flex;
    align-items: center;
    gap: .5rem;
  }
}

// static/src/scss/report_pdf.scss
.page {
  // margin dalam mm untuk PDF
  margin: 12mm 10mm;
}
.table-report th,
.table-report td {
  padding: 2mm 3mm;
  border-bottom: 0.2mm solid #ccc;
}

Konvensi & Struktur

• Modular: pisahkan variables.scss, backend.scss, frontend.scss, report_*.scss.

• Penamaan class: gunakan prefix komponen modul, contoh .mmx-card, .mmx-card__header, .mmx-card--highlight (gaya BEM disarankan untuk keterbacaan).

• Hindari override liar: jangan menimpa selector global tanpa konteks; targetkan kontainer atau komponen tertentu.

• Jaga kompatibilitas: beberapa class inti Odoo penting untuk layout (mis. .o_form_sheet, .o_statusbar_status, .oe_button_box), jangan dihapus/diubah strukturnya.

Backend vs Frontend: Perbedaan Konteks

• Backend: fokus pada utilitas admin, density informasi, komponen form/kanban. Ikuti grid & spacing Odoo.

• Frontend/Portal: fokus pada keterbacaan publik, ruang lega, dan responsif lintas perangkat.

• Editor Website: perubahan untuk editor sering ditempatkan pada bundle terpisah; untuk tampilan pengunjung cukup web.assets_frontend.

Variabel, Mixins, dan CSS Variables

• SCSS Variables: ideal untuk kompilasi warna, font, ukuran.

• CSS Variables (--var): bermanfaat untuk runtime theming (mis. mode gelap). Dapat dipakai berdampingan.

• Mixins: buat utilitas berulang (mis. @mixin clearfix, @mixin truncate).

Contoh kecil CSS Variables untuk runtime:

:root {
  --brand-500: #6f42c1;
}
.btn-brand {
  background-color: var(--brand-500);
}

Styling Report (PDF) dengan Nyaman

• Gunakan satuan mm untuk margin/padding.

• Gunakan class tabel khusus (mis. .table-report) alih‑alih menimpa semua <table>.

• Atur page break dengan aman: page-break-inside: avoid; pada baris yang tidak boleh terputus.

• Uji pada dokumen panjang, multi‑currency, dan multi‑page.

tr.avoid-break { page-break-inside: avoid; }
.table-report thead { display: table-header-group; }

Best Practices (Do/Don’t)

Do

• Definisikan variabel di web._assets_primary_variables agar konsisten.

• Gunakan class pembungkus modul untuk membatasi scope.

• Optimalkan spesifisitas: pilih selector pendek & jelas.

• Gunakan DevTools untuk audit CSS dan cascade.

Don’t

• Jangan gunakan inline style pada QWeb kecuali darurat.

• Jangan menimpa class inti Odoo tanpa memahami efeknya.

• Jangan menambahkan style ke bundle yang salah (mis. style backend di frontend).

Debugging & Diagnostik

• Cache Assets: setelah mengubah manifest/SCSS, upgrade modul dan refresh cache (Ctrl+F5). Pada dev, aktifkan Developer Mode.

• Urutan Bundle: cek apakah file SCSS kita dimuat setelah variabel/komponen yang ingin dioverride.

• Spesifisitas: jika style tidak bekerja, periksa selector yang memenangkan cascade.

• PDF: periksa HTML hasil render report (print preview) untuk memastikan class dan gaya tepat.

Checklist Sebelum Masuk ke FAQ Detail

• Variabel brand & tipografi didefinisikan di variables.scss dan dimuat via web._assets_primary_variables.

• Backend/Frontend/Report dipisah per bundle dan file.

• Tidak ada inline style; QWeb tetap bersih.

• Uji responsif pada resolusi umum (mobile/tablet/desktop) untuk frontend/portal.

• Uji cetak PDF pada skenario tabel panjang dan multi‑page.

Yang Akan Kita Jawab di FAQ SCSS/CSS

• Cara mengganti palet warna, font, dan spacing global.

• Teknik aman override komponen backend (statusbar, button box, kanban card).

• Pola styling portal & website yang responsif.

• Template report rapi: tabel, header/footer, page break, dan tipografi.

• Mengatasi konflik spesifisitas dan best practice pengelolaan bundle.

Dengan prolog ini, kita siap melangkah ke FAQ SCSS / CSS — styling & theming dan membahas kasus nyata yang sering muncul saat memoles antarmuka Odoo 18 CE.