HTML/XML Snippets (Website)

Selamat datang di bagian kedua belas FAQ OdooCamp: HTML/XML Snippets (Website). Prolog ini menyiapkan fondasi konsep dan peta kerja sebelum kita masuk ke pertanyaan teknis yang paling sering diajukan developer tentang pembuatan, kustomisasi, dan pemeliharaan website snippets di Odoo 18 CE.

Mengapa Snippets Penting?

Snippets adalah blok konten drag‑and‑drop yang dipakai editor non‑teknis untuk membangun halaman website dan portal. Dengan snippets yang rapi:

• Tim konten dapat bekerja cepat tanpa menunggu developer.

• Branding dan komponen UI menjadi konsisten di seluruh halaman.

• Perubahan UI dapat dirilis iteratif tanpa mengganggu backend.

Mindset Kerja

Template (QWeb) → Options (JS) → Styling (SCSS) → Assets (manifest) → i18n & Aksesibilitas

• Template: markup snippet di QWeb/HTML sebagai struktur dasar.

• Options: panel pengaturan di website editor (warna, layout, gambar) via JS options API.

• Styling: SCSS modular untuk tampilan responsif.

• Assets: daftar berkas di __manifest__.py agar ikut dibundel.

• i18n/A11y: teks bisa diterjemahkan; gambar mempunyai alt; kontras dan hierarki heading terjaga.

Ruang Lingkup yang Akan Kita Bahas di FAQ Snippets

1. Anatomi snippet: file, struktur template, naming konvensi.

2. Snippet options (JS): menambah kontrol (color, size, variant) di editor.

3. Styling & responsif: grid, spacing, media queries.

4. Assets & bundling: registrasi di manifest untuk frontend dan editor.

5. Gambar/icon: path absolut, optimasi, dan lisensi.

6. i18n & aksesibilitas: terjemahan, alt text, heading structure.

7. Diagnostik: preview, cache assets, konflik CSS.

Struktur Direktori yang Disarankan

my_module/
└─ static/
   └─ src/
      ├─ snippets/
      │  └─ s_my_banner/
      │     ├─ s_my_banner.xml      # template snippet (QWeb/HTML)
      │     ├─ s_my_banner.scss     # style khusus snippet
      │     └─ options.js           # (opsional) kontrol di editor
      ├─ scss/
      │  └─ frontend.scss           # import s_my_banner.scss
      └─ img/
         └─ s_my_banner_preview.png # (opsional) pratinjau di dokumentasi

Anatomi Minimal — Template Snippet

<odoo>
  <template id="s_my_banner" name="My Banner" inherit_id="website.snippets" priority="16">
    <!-- Daftarkan snippet di palet editor -->
    <xpath expr="//div[@id='snippet_structure']" position="inside">
      <div class="o_snippet_thumbnail" data-snippet="my_module.s_my_banner" data-name="My Banner">
        <img src="/my_module/static/src/img/s_my_banner_preview.png" alt="My Banner"/>
      </div>
    </xpath>
  </template>

  <!-- Konten aktual snippet -->
  <template id="snippet_s_my_banner" name="Snippet: My Banner">
    <section class="s_my_banner o_cc">
      <div class="container">
        <h2 class="s_my_banner__title">Heading yang Informatif</h2>
        <p class="s_my_banner__lead">Paragraf singkat untuk menjelaskan nilai utama.</p>
        <a class="btn btn-primary" href="#">Call To Action</a>
      </div>
    </section>
  </template>
</odoo>

Catatan:

• Thumbnail pendaftaran memunculkan kartu snippet di panel editor.

• Template konten adalah blok yang disisipkan saat snippet di‑drop ke halaman.

• Gunakan class ber‑prefix modul (s_my_banner*) agar tidak konflik.

Snippet Options (JS) — Gambaran Umum

Tujuannya menambahkan kontrol di editor (mis. variasi warna, alignment, toggle elemen).

// static/src/snippets/s_my_banner/options.js
/** Gambaran API; sesuaikan dengan registry editor Odoo 18 Anda **/
import { registry } from "@web/core/registry";

const optionsRegistry = registry.category("website_snippet_options");

optionsRegistry.add("my_module.s_my_banner_options", {
  // Dipanggil saat opsi diterapkan
  async selectColor(preview, value, { $target }) {
    // ganti kelas warna pada root snippet
    $target.classList.remove("s_my_banner--primary", "s_my_banner--secondary");
    $target.classList.add(`s_my_banner--${value}`);
  },
});

Registrasi Assets di Manifest

# __manifest__.py (ringkas)
{
  "name": "My Website Snippets",
  "depends": ["website"],
  "assets": {
    # Pengunjung website/portal
    "web.assets_frontend": [
      "my_module/static/src/scss/frontend.scss",
      "my_module/static/src/snippets/s_my_banner/s_my_banner.scss",
    ],
    # Editor website (opsi & kontrol UI editor)
    # Gunakan bundle editor yang berlaku pada Odoo Anda, misalnya salah satu:
    # "website.assets_wysiwyg" atau "web_editor.assets_wysiwyg"
    "website.assets_wysiwyg": [
      "my_module/static/src/snippets/s_my_banner/options.js",
    ],
  },
}

Tips:

• Pastikan modul website ada di depends.

• SCSS snippet bisa di‑import ke frontend.scss atau didaftarkan langsung.

Styling & Responsif

• Gunakan grid/container Odoo untuk alignment.

• Hindari inline style; letakkan style di SCSS.

• Sediakan modifier class (mis. --primary/--secondary) untuk variasi cepat.

• Uji pada viewport umum (mobile/tablet/desktop).

i18n & Aksesibilitas

• Teks statis dapat diterjemahkan melalui mekanisme i18n.

• Pastikan gambar memiliki alt yang bermakna.

• Jaga hierarki heading (H1→H2→H3) dan kontras warna yang memadai.

Best Practices (Do/Don’t)

Do

• Pakai prefix class modul (s_my_*) dan struktur BEM sederhana untuk keterbacaan.

• Dokumentasikan opsi snippet di komentar dan README modul.

• Optimalkan gambar (WebP/SVG bila cocok) dan ukuran file kecil.

• Jaga kompatibilitas editor: opsi jangan mengandalkan selector rapuh.

Don’t

• Jangan menaruh logic bisnis di snippet; snippet hanya presentasi.

• Jangan menimpa class global tanpa konteks; gunakan wrapper snippet.

• Jangan menambahkan script yang berat di frontend tanpa alasan kuat.

Debugging & Diagnostik

• Aktifkan Developer Mode dan jalankan editor Website untuk uji opsi.

• Bersihkan cache assets (upgrade modul, hard refresh) saat mengubah SCSS/JS.

• Gunakan DevTools untuk melihat kelas yang ditambahkan options.

Checklist Sebelum Masuk ke FAQ Detail

• Template snippet terdaftar di palet editor dan dapat di‑drag‑and‑drop.

• Options (jika ada) muncul dan bekerja stabil.

• SCSS modular, responsif, dan tidak konflik.

• Aset terdaftar di bundle yang benar (frontend dan editor).

• i18n & aksesibilitas dipenuhi (alt, heading, kontras).

Yang Akan Kita Jawab di FAQ Snippets

• Cara membuat snippet baru dari nol dan menampilkannya di palet.

• Menambahkan options (warna, layout, toggle elemen) yang mudah digunakan tim konten.

• Pola styling responsif dan pengelolaan gambar/icon.

• Mengatasi konflik CSS/JS dan cache assets.

• Praktik i18n & aksesibilitas agar snippet ramah pengguna.

Dengan prolog ini, kita siap melangkah ke FAQ HTML/XML Snippets (Website) dan membahas praktik konkret yang sering muncul di proyek Odoo 18 CE.