Sayudha

21 Gambaran Arsitektur Theme

Properties2
descriptionBedah struktur theme secara utuh, tiap folder dan jenis file, snippet, JSON dengan komentar, dan semua batasan platform
tagsshopify, theme, arsitektur

10 menit baca

Bagian 2 selesai, kamu udah fasih Liquid. Sekarang Bagian 3: gimana file-file Liquid itu disusun jadi theme. Bab ini gambaran besarnya, bab-bab berikutnya bedah tiap lapisan.

Di 01 Apa itu Theme Shopify > Susunan Sebuah Halaman kita udah lihat sekilas enam lapisan theme. Sekarang kita ulang dengan pemahaman Liquid yang udah kita punya, terus bahas tiap folder, dan tutup dengan batasan-batasan platform yang harus dipatuhi.

Theme itu yang ngatur susunan, fitur, dan gaya toko merchant. Kodenya diatur dalam struktur folder standar yang khusus buat Shopify, plus aset pendukung kaya gambar, stylesheet, dan skrip.

Kalau kamu bikin theme buat Theme Store, ada syarat tambahan soal opsi kustomisasi, gaya, dan fitur yang harus ada. Bahasannya di 70 Theme Store Gambaran dan Requirements.

Tiga Kategori File

Semua file theme masuk salah satu dari tiga kategori:

  1. Markup dan fitur, file yang ngatur susunan dan fungsi theme. Pakai Liquid buat ngasilin HTML tiap halaman.
  2. Aset pendukung, file aset, skrip, dan locale yang dipanggil atau dipakai file lain.
  3. File config, file JSON yang nyimpen data konfigurasi yang bisa diubah merchant lewat theme editor.

Komponen Markup dan Fitur

Tiap halaman disusun dari enam komponen yang saling bertumpuk:

  1. Layout, dasar theme. Tempat elemen yang diulang di semua halaman kaya header dan footer. Bahasannya di 22 Layouts.
  2. Template, ngatur apa yang ditampilin di sebuah halaman. Tiap theme punya template buat tiap jenis konten: halaman depan, produk, koleksi, dan seterusnya. Bisa juga bikin beberapa template buat jenis yang sama (alternate templates) buat variasi. Template JSON cuma pembungkus section, template Liquid berisi kode. Bahasannya di 23 Templates dan 24 Template per Halaman.
  3. Section groups, dirender oleh layout. Wadah yang bikin merchant bisa nambah, ngehapus, dan ngurutin section di area layout kaya header dan footer. Bahasannya di 27 Section Groups dan Migrasinya.
  4. Sections, dirender oleh template. Modul konten yang bisa dipakai ulang dan dikustomisasi merchant, ditambahin ke template JSON dan section group. Bahasannya di 26 Sections dan Section Schema.
  5. Blocks, di dalam section. Modul lebih kecil yang bisa ditambah, dihapus, dan diurutin merchant. Bahasannya di 28 Blocks dan 29 Theme Blocks Mendalam.
  6. Snippets, potongan Liquid yang bisa dirender dari mana aja. Dibahas di bab ini.

Fitur theme (cara pelanggan berinteraksi sama konten) diimplementasikan di template Liquid, section, block, dan snippet, pakai Liquid, CSS, dan JavaScript. Contoh: biar pelanggan bisa nambah produk ke keranjang, theme harus nyediain tag form bertipe product.

Struktur Folder

Theme wajib pakai susunan ini:

.
├── assets
├── blocks
├── config
├── layout
├── locales
├── sections
├── snippets
└── templates
    └── customers
    └── metaobject

Subfolder selain yang di atas gak didukung. Dan cuma layout/theme.liquid yang wajib ada buat theme bisa di-upload. Contoh theme lengkap ada di repository Dawn.

1. assets

Semua aset theme: gambar, CSS, dan JavaScript. Dirujuk pakai filter asset_url dari 19 Filters HTML, URL, Media, Color, dan Font > 1. asset_url.

Ada trik penting: file aset non-biner bisa dikasih ekstensi .liquid tambahan biar dapat sedikit kemampuan Liquid. Yang umum: .js.liquid dan .css.liquid. Di dalamnya kamu bisa pakai:

  1. Object settings, buat baca pengaturan theme.
  2. Filter Liquid, buat ngolah nilainya.

Tapi cuma itu, gak ada object lain, gak ada tag. Dan ini udah gak disarankan di theme modern karena bikin file CSS/JS gak bisa di-cache dengan baik (isinya berubah tiap setting berubah). Cara yang lebih baik: deklarasiin CSS variable di theme.liquid pakai {% style %}, terus pakai di file .css biasa. Polanya udah dibahas di 06 Theme Editor dan Code Editor > 1. Pengaturan Warna.

❌ kurang bagus, file CSS-nya gak bisa di-cache efektif dan gak bisa live preview

/* assets/theme.css.liquid */
.button { background: {{ settings.color_button }}; }

✅ lebih bagus, variabel di layout, CSS statis di aset

{% comment %} layout/theme.liquid {% endcomment %}
{% style %}
  :root { --color-button: {{ settings.color_button }}; }
{% endstyle %}
/* assets/theme.css */
.button { background: var(--color-button); }

2. blocks

File-file theme block, yaitu block yang bisa dipakai di banyak section (beda sama section block yang cuma hidup di satu section). Bahasannya di 29 Theme Blocks Mendalam.

3. config

File config yang nentuin setting di area Theme settings theme editor dan nyimpen nilainya. Ini tempat setting umum kaya tipografi dan warna. Diakses lewat object settings.

Setting juga bisa dibikin buat section dan block, tapi itu didefinisikan di dalam section atau block-nya sendiri dan muncul di theme editor bareng object itu. Bahasannya di 32 Config settings_schema.json, settings_data.json, markets.json.

4. layout

File layout, yang jadi tempat template dirender. Layout itu file Liquid buat konten yang diulang di banyak jenis halaman dalam satu tempat: isi <head>, section group header dan footer. theme.liquid wajib ada.

5. locales

File terjemahan. Fungsinya tiga: nyediain pengalaman terjemahan di theme editor, terjemahan buat toko online, dan bikin merchant bisa ngubah teks toko. Bahasannya di 33 Locales dan Translasi.

6. sections

Berisi section dan section group. Section itu file Liquid modul konten yang bisa dikustomisasi merchant, bisa punya block. Section group itu wadah JSON yang bikin merchant bisa ngatur section di area layout.

Perhatiin: section group ditaruh di folder sections/ juga, bukan folder sendiri, cuma ekstensinya .json bukan .liquid.

7. snippets

File snippet Liquid buat potongan kode kecil yang bisa dipakai ulang. Dibahas lengkap di bawah.

8. templates

File template yang ngatur apa yang dirender di tiap jenis halaman. Sub-folder templates/customers/ buat halaman akun pelanggan lawas (login, ringkasan akun), dan templates/metaobject/ buat halaman metaobject.

Gak ada template yang wajib. Tapi buat ngerender jenis halaman tertentu, harus ada template yang cocok. Mau nampilin halaman produk? Harus ada minimal satu template bertipe product. Kamu juga bisa nambahin fungsi yang masuk akal per jenis halaman, misalnya rekomendasi produk di template produk, atau form komentar di template artikel.

Aset Pendukung

Aset pendukung ngatur presentasi komponen dan fitur, atau nyimpen kode yang bisa dipakai ulang. Gaya theme ditentuin sama CSS dan JavaScript yang diterapin ke layout, template, dan section, disimpan di assets/. Liquid dan HTML yang mau dipakai ulang disimpan di snippets/. Terjemahan disimpan di locales/.

JSON dengan Komentar

Ini fitur yang jarang diketahui: file JSON di theme mendukung komentar dan koma di akhir (trailing comma), yang di JSON standar itu error. Kamu bisa nambahin komentar di config/settings_schema.json dan di dalam tag {% schema %}:

[
  {
    /* context about theme schema settings */
    "name": "theme_info",
    "theme_name": "Dawn",
    "theme_author": "Shopify",
    "theme_version": "1.0.0",
    "theme_documentation_url": "https:\/\/help.shopify.com\/manual\/online-store\/themes\/os20\/themes-by-shopify\/dawn",
    "theme_support_url": "https:\/\/support.shopify.com\/",
  },
  {
  "name": "t:settings_schema.colors.name",
  "settings": [
    {
      "type": "header",
      "content": "t:settings_schema.colors.settings.header__1.content", // some useful context + see trailing comma
    },
  ...
]

Tapi ada batasnya: file yang biasanya gak diedit manual gak nyimpen komentar dan koma akhir, karena file-file itu ditulis ulang sama Shopify tiap merchant ngubah sesuatu. Yang termasuk:

templates/*.json
sections/*.json (section groups)
config/settings_data.json
locales/*.json

Jadi komentar di templates/index.json bakal hilang begitu merchant nyimpen dari theme editor. Taruh komentar cuma di settings_schema.json dan di {% schema %}.

Catatan buat yang bikin alat: kalau kamu ngambil file theme lewat Assets API, parser JSON-mu harus mendukung komentar dan koma akhir. Sejak versi API 2024-10, file yang gak nyimpen komentar bakal dikasih komentar header otomatis di atasnya.

Snippets

Snippet itu potongan Liquid yang bisa dipakai ulang, buat jaga konsistensi dan ngurangin duplikasi. Kamu bungkus logika dan markup yang rumit ke file terpisah, terus render dari mana aja.

Bedanya sama section dan block: snippet gak kelihatan sama merchant di theme editor. Merchant gak bisa nambah, ngehapus, atau ngatur snippet. Itu murni alat developer. Cocok buat kode yang diulang di seluruh theme: kartu produk, elemen navigasi, komponen form.

1. Cara Pakai

Pakai tag render yang udah dibahas tuntas di 12 Tags Khusus Theme > render, dengan parameter bernama buat ngirim data:

{% render 'product-card',
  product: product,
  show_price: true,
  max_description_length: 120
%}

Ini nyari snippets/product-card.liquid. Nama file tanpa ekstensi.

2. Scope Variabel

Ulangan dari 12 Tags Khusus Theme > 1. Aturan Scope Snippet Itu Kotak Tertutup karena ini yang paling sering bikin bingung:

  1. Di dalam snippet, gak bisa akses variabel yang dibikin di luar (hasil assign atau capture).
  2. Tapi bisa akses object global kaya product, collection, section (yang emang tersedia di tempat snippet dipanggil).
  3. Bisa nerima variabel tertentu lewat parameter.
  4. Variabel yang dibikin di dalam snippet tetap lokal, gak bisa diakses dari luar.

3. Dokumentasi dengan LiquidDoc

Karena snippet itu kaya fungsi, dokumentasiin parameternya pakai LiquidDoc yang udah dibahas di 07 Tools Lokal VS Code Extension, Prettier, LiquidDoc > LiquidDoc:

{% doc %}
  Product card snippet
 
  @param {string} title - The title to display
  @param {number} [max_items] - Optional maximum number of items to show
 
  @example
  {% render 'example-snippet', title: 'Featured Products', max_items: 3 %}
{% enddoc %}

Dengan ini, editor ngasih auto-complete parameter, peringatan parameter yang hilang, dan pengecekan tipe.

4. Kapan Snippet, Kapan Section, Kapan Block

Ini keputusan yang bakal sering kamu hadapi:

  1. Snippet kalau kodenya diulang dan merchant gak perlu ngatur apa-apa. Contoh: kartu produk, ikon, format harga.
  2. Section kalau merchant perlu nambah, ngehapus, ngurutin, dan ngatur modul itu di halaman. Contoh: banner hero, produk unggulan, testimoni.
  3. Block kalau modul itu bagian dari section dan merchant perlu ngatur isinya. Contoh: satu slide di slideshow, satu kolom di section kolom.

❌ salah, kartu produk sebagai section, merchant gak butuh ngatur ini dan gak bisa dipanggil dari loop

sections/product-card.liquid

✅ benar

snippets/product-card.liquid

Batasan Platform

Ini semua batas yang ditetapkan Shopify. Melanggar salah satunya bikin error di theme editor, atau waktu theme disimpan, di-upload, atau di-push lewat CLI. Angka-angka ini gak perlu dihafal, tapi harus tau ada biar gak kaget waktu ketemu error.

1. Template

  1. Template JSON per theme: 1.000.
  2. Section per template JSON: 25.

2. Section Group

  1. Section group per theme: 20.
  2. Section per section group: 25.

3. Section dan Block

  1. Block per section: 50. Bisa dikurangi pakai max_blocks di schema.
  2. Block per template JSON atau section group: 1.250.
  3. Kedalaman sarang theme block: 8 tingkat, gak termasuk tingkat section.
  4. File theme block (blocks/) per theme: 300.

Batas per-section dan per-template itu berlaku buat block yang bisa ditambah, dihapus, dan diurutin merchant, termasuk app block dan theme block. Static block yang dirender pakai {% content_for %} gak dihitung.

4. Ukuran File

Per file:

  1. Template JSON: 512 KB.
  2. Section group: 512 KB.
  3. settings_schema.json: 512 KB.
  4. settings_data.json: 1,5 MB.
  5. File locale: 1,5 MB.
  6. File Liquid lain (section, snippet, layout): 256 KB.
  7. Isi satu setting bertipe liquid: 50 KB.

Per theme:

  1. Paket theme yang di-upload (terkompresi): 50 MB.
  2. Total kode (semua file kecuali aset): 250 MB.
  3. File per theme: 100.000.

Batas 256 KB per file Liquid itu yang paling sering kena. Kalau section-mu udah mendekati itu, tandanya harus dipecah ke snippet. Bahasan error “can’t be larger than 64 kilobytes” (batas lama yang masih muncul di beberapa konteks) ada di 53 Troubleshooting Error Umum.

5. Penamaan

  1. Nama theme: 50 karakter.
  2. Atribut name di schema section dan block: 25 karakter.
  3. Nama kustom section dan block yang diatur merchant di theme editor: 100 karakter.

6. Theme App Extension

App yang nambahin ke theme lewat theme app extension punya batas ukuran file sendiri yang terpisah dari theme.

Ringkasan

  1. Tiga kategori file: markup dan fitur (Liquid), aset pendukung (CSS, JS, gambar, locale), dan config (JSON).
  2. Enam komponen bertingkat: layout → template → section group → section → block, plus snippet dari mana aja.
  3. Delapan folder baku, gak boleh nambah subfolder, cuma layout/theme.liquid yang wajib.
  4. File .css.liquid dan .js.liquid cuma dapat settings dan filter, dan udah gak disarankan. Pakai CSS variable di theme.liquid.
  5. Section group ditaruh di sections/ dengan ekstensi .json, bukan folder sendiri.
  6. Gak ada template yang wajib, tapi tiap jenis halaman yang mau dirender butuh minimal satu template bertipe itu.
  7. JSON theme mendukung komentar dan koma akhir, tapi cuma di settings_schema.json dan {% schema %}. Di templates/*.json, section group, settings_data.json, dan locale, komentar bakal hilang.
  8. Snippet gak kelihatan merchant, dipanggil pakai render, scope-nya tertutup, dan sebaiknya didokumentasiin pakai LiquidDoc.
  9. Snippet buat kode berulang tanpa kustomisasi merchant, section buat modul yang diatur merchant, block buat bagian dalam section.
  10. Batas penting: 25 section per template, 50 block per section, 8 tingkat sarang block, 256 KB per file Liquid, 25 karakter buat name schema.
  11. Static block gak dihitung dalam batas block.

Bab selanjutnya kita bedah lapisan terluar: file theme.liquid, apa yang wajib ada di dalamnya, layout alternatif, dan cara template milih layout mana yang dipakai.

Tampilan Grafik

Tautan Balik