Static assets — gambar, ikon, font, deskripsi app

Selamat datang di bagian kesembilan FAQ OdooCamp: Static assets — gambar, ikon, font, dan deskripsi app. Prolog ini menyiapkan fondasi konsep sebelum kita masuk ke pertanyaan teknis yang sering diajukan developer tentang pengelolaan aset statis di Odoo 18 CE.

---

Mengapa Static Assets Penting?

Aset statis menentukan kualitas visual, performa, dan kesan profesional modul kita. Pengelolaan yang rapi akan:

• Menjaga branding konsisten (logo, ikon, ilustrasi, font).
• Meningkatkan UX/kecepatan lewat ukuran file yang efisien dan cache yang benar.
• Memastikan keterbacaan di berbagai konteks (backend, portal/website, report/PDF, halaman Apps/Marketplace).

---

Mindset Kerja

Struktur Direktori → Referensi Path → Bundling → Cache/Performa → Lisensi

• Simpan aset di direktori standar (static/src/... dan static/description/...).
• Referensikan aset dengan path absolut Odoo (/nama_modul/static/...) di QWeb/HTML/SCSS.
• Daftarkan SCSS/JS ke bundle assets via __manifest__.py agar ikut dibuild/cached.
• Optimalkan ukuran/format; hormati lisensi aset (ikon/font/gambar eksternal).

---

Ruang Lingkup yang Akan Kita Bahas di FAQ Assets

1. Struktur direktori untuk gambar/ikon/font/description.
2. Cara mereferensikan aset di QWeb, CSS/SCSS, dan Website/Portal.
3. Bundling melalui __manifest__.py dan dampaknya pada cache/performa.
4. Optimasi (format, ukuran, SVG vs PNG/WebP) dan tips report/PDF.
5. Font kustom: penempatan, @font-face, dan lisensi.
6. Deskripsi App: static/description/index.html, ikon, dan aset pendukung.
7. Diagnostik: path 404, cache tidak tersinkron, konflik spesifisitas.

---

Struktur Direktori yang Disarankan

my_module/
└─ static/
   ├─ src/
   │  ├─ img/        # ikon, ilustrasi, logo, screenshot UI (untuk portal/backend)
   │  ├─ fonts/      # font kustom (woff2/woff/ttf sesuai kebutuhan)
   │  ├─ scss/       # stylesheet modul
   │  └─ js/         # skrip frontend/backend
   └─ description/   # halaman & gambar deskripsi modul (Apps/Marketplace)
      ├─ index.html
      ├─ icon.png    # ikon aplikasi modul
      └─ banner.png  # gambar promosi/screenshot (opsional)

---

Referensi Path Aset

1) QWeb / HTML

<img src="/my_module/static/src/img/logo.svg" alt="Logo"/>

2) SCSS / CSS

.my-hero {
  background-image: url('/my_module/static/src/img/hero.webp');
}

3) Website/Portal (templating)

<a href="/"><img src="/my_module/static/src/img/cta.png" alt="CTA"/></a>

Gunakan path absolut /my_module/static/... agar dapat diakses di backend maupun portal.

---

Bundling Aset di __manifest__.py

# __manifest__.py (ringkas)
{
  "depends": ["web"],
  "assets": {
    "web._assets_primary_variables": [
      "my_module/static/src/scss/variables.scss",
    ],
    "web.assets_backend": [
      "my_module/static/src/scss/backend.scss",
      "my_module/static/src/js/backend.js",
    ],
    "web.assets_frontend": [
      "my_module/static/src/scss/frontend.scss",
      "my_module/static/src/js/frontend.js",
    ],
    "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: gambar & font tidak perlu didaftarkan eksplisit di assets selama direferensikan dari SCSS/HTML dengan path yang benar.

---

Font Kustom (@font-face)

@font-face {
  font-family: 'MyBrand';
  src: url('/my_module/static/src/fonts/MyBrand.woff2') format('woff2'),
       url('/my_module/static/src/fonts/MyBrand.woff') format('woff');
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}
.body-brand { font-family: 'MyBrand', system-ui, sans-serif; }

Tips:

• Gunakan woff2 (utama) dan woff (fallback) untuk size kecil & kompatibilitas.
• Tambahkan font-display: swap agar teks tetap terlihat saat font belum termuat.
• Pastikan lisensi font membolehkan redistribusi.

---

Optimasi Format & Ukuran

• SVG: pilihan utama untuk logo/ikon sederhana (tajam di semua DPI, kecil, mudah diwarnai via CSS).
• PNG: untuk ikon/ilustrasi yang butuh transparansi dan detail tajam.
• WebP: untuk foto/hero/gambar besar di frontend (ukuran kecil, kualitas baik). Siapkan fallback PNG jika perlu.
• JPEG: foto dengan gradasi halus, pilih kualitas terkompresi.
• PDF/Report: gunakan gambar dengan resolusi cukup (sekitar 150–300 DPI) agar tidak pecah saat dicetak.
• Kompres gambar sebelum commit; hindari menyimpan file berukuran puluhan MB.

---

Deskripsi App (Marketplace)

static/description/index.html menampilkan halaman deskripsi modul pada Apps/Marketplace. Simpan ikon di static/description/icon.png dan gambar pendukung di folder yang sama. Jaga konten HTML sederhana, gambar teroptimasi, dan tautan yang relevan.

---

Best Practices (Do/Don’t)

Do

• Simpan aset di lokasi standar (static/src/..., static/description/...).
• Gunakan path absolut /my_module/static/... untuk referensi lintas konteks.
• Pilih format tepat guna (SVG/PNG/WebP/JPEG) dan kompres sebelum commit.
• Dokumentasikan sumber dan lisensi aset (ikon, font, foto).
• Pisahkan aset untuk backend vs frontend vs report pada SCSS yang berbeda.

Don’t

• Jangan menaruh gambar besar inline base64 di template kecuali ikon kecil.
• Jangan menggunakan CDN eksternal tanpa alasan kuat (ketergantungan jaringan, kebijakan privasi).
• Jangan menimpa class inti Odoo hanya demi styling gambar; gunakan class pembungkus modul.

---

Debugging & Diagnostik

• 404 Not Found: cek penulisan path absolut dan nama modul.
• Aset tidak berubah: upgrade modul, bersihkan cache browser (Ctrl+F5), aktifkan Developer Mode.
• Font tidak termuat: periksa MIME type/format dan path @font-face.
• Gambar blur di PDF: gunakan resolusi lebih tinggi atau format yang sesuai.

---

Checklist Sebelum Masuk ke FAQ Detail

• Struktur static/src/ dan static/description/ sudah rapi.
• Path aset konsisten memakai /my_module/static/....
• SCSS/JS terdaftar di bundle yang sesuai di manifest.
• Gambar & font terkompresi dan lisensinya jelas.
• Deskripsi app (index.html + icon) siap untuk Apps/Marketplace.

---

Yang Akan Kita Jawab di FAQ Static Assets

• Pola referensi aset yang benar di QWeb/SCSS/Website.
• Cara memilih format terbaik untuk kebutuhan spesifik.
• Praktik aman memakai font kustom dan lisensinya.
• Strategi optimasi performa (kompresi, caching, bundling).
• Menyiapkan deskripsi app yang informatif dan ringan.

Dengan prolog ini, kita siap melangkah ke FAQ Static assets — gambar, ikon, font, deskripsi app dan membahas praktik konkret di proyek Odoo 18 CE.