Sayudha

23 Templates

Properties2
descriptionTemplate JSON vs Liquid, semua jenis template, struktur file JSON template beserta section data dan wrapper, alternate template, dan contextual template
tagsshopify, theme, arsitektur

10 menit baca

Di 22 Layouts kita punya bingkainya. Sekarang isinya: template, yang nentuin apa yang tampil di tiap jenis halaman.

Tiap jenis halaman di toko punya tipe template yang terkait. Mau ngerender halaman produk? Theme harus punya minimal satu template bertipe product. Mau ngerender halaman metaobject? Butuh template metaobject/{tipe}, misalnya metaobject/book atau metaobject/author.

Template itu tempat nambahin fungsi yang masuk akal buat jenis halaman itu. Rekomendasi produk di template produk, form komentar di template artikel. Dan kamu bisa bikin beberapa versi dari tipe yang sama (alternate template) buat kasus berbeda: template produk khusus pakaian, template halaman khusus yang ada videonya.

JSON vs Liquid

Ada dua jenis file template, dan ini keputusan pertama yang harus kamu ambil:

  1. JSON (.json), file data yang berisi daftar section yang mau dirender. Section bisa ditambah, dihapus, dan diurutin merchant lewat theme editor. Semua HTML dan Liquid harus ada di dalam section yang dirujuk template.
  2. Liquid (.liquid), file markup yang bisa langsung berisi Liquid dan HTML. Gak bisa pakai section.

Aturan milihnya sederhana: kalau mau pakai section, harus JSON. Dan hampir selalu kamu mau pakai section, karena:

  1. Merchant bisa nambah, ngehapus, dan ngurutin section, termasuk section dari app.
  2. Data disimpan di template-nya sendiri, bukan numpuk di settings_data.json. Ini bikin theme editor lebih cepat.

Jadi di theme modern, hampir semua template itu JSON. Liquid template cuma buat kasus khusus yang dibahas di bawah.

❌ kurang bagus, template Liquid buat halaman yang merchant pengen atur section-nya

templates/index.liquid

✅ benar

templates/index.json

Satu tipe cuma boleh punya satu jenis file. Kalau product.liquid udah ada, kamu gak bisa bikin product.json. Harus hapus yang lama dulu. Ini yang jadi inti migrasi Online Store 2.0 di 52 Online Store 2.0 dan Migrasinya.

Semua Tipe Template

Gak ada tipe yang wajib, tapi tiap jenis halaman yang mau dirender butuh template yang cocok. Batasnya 1.000 template JSON per theme di semua tipe: 20 template produk + 10 halaman + 5 koleksi = 35, sisa 965.

  1. index, halaman depan di URL root /.
  2. product, halaman produk: media, konten, dan form buat milih varian dan nambah ke keranjang.
  3. collection, halaman koleksi yang ngelist produk di dalamnya.
  4. list-collections, halaman daftar semua koleksi di /collections.
  5. cart, halaman /cart dengan isi keranjang.
  6. search, halaman /search dengan hasil pencarian.
  7. page, halaman statis kaya About us dan Contact us.
  8. blog, halaman blog yang ngelist semua artikelnya.
  9. article, halaman artikel dengan isi lengkap dan komentar opsional.
  10. 404, halaman kalau URL-nya gak valid.
  11. password, halaman /password waktu toko dikunci. Berisi pesan yang bisa diedit merchant dan form password.
  12. gift_card.liquid, halaman gift card yang dilihat pelanggan setelah beli. Wajib Liquid.
  13. metaobject, halaman metaobject kaya “artis” atau “penulis”. Definisi metaobject-nya harus punya web page capability.
  14. robots.txt.liquid, file robots.txt di /robots.txt buat mesin pencari. Wajib Liquid.
  15. agents.md.liquid, file agents.md di /agents.md, deskripsi toko buat AI agent biar tau cara nemuin dan bertransaksi. Wajib Liquid.
  16. llms.txt.liquid dan llms-full.txt.liquid, di /llms.txt dan /llms-full.txt, URL alternatif buat AI agent yang bawaannya nyerminin /agents.md. Wajib Liquid.

Lima yang wajib Liquid (gift_card, robots.txt, agents.md, llms.txt, llms-full.txt) itu karena outputnya bukan halaman HTML biasa yang butuh section. Sisanya bebas JSON atau Liquid. Tiap tipe dibedah di 24 Template per Halaman dan 25 Template Spesial robots.txt, llms.txt, agents.

Template Akun Pelanggan Lama

Ada satu kelompok yang deprecated: template customers/* (customers/account, customers/activate_account, customers/login, customers/order, customers/register, customers/reset_password, customers/addresses). Akun pelanggan sekarang jalan terpisah dari theme, dan template-template ini gak perlu lagi ada.

Yang menarik: publish theme tanpa template-template ini otomatis nge-upgrade merchant ke customer accounts baru. Sebagai gantinya, tambahin komponen <shopify-account> di header biar pelanggan bisa login tanpa ninggalin toko. Bahasannya di 46 Customer Sign-in, Account Component, Contact Form, Email Consent.

Kamu masih bakal nemuin folder templates/customers/ di theme lama, dan form-form akun di 12 Tags Khusus Theme > 5. Form Akun Pelanggan masih jalan di situ. Tapi buat theme baru, lewati aja.

Lokasi

└── theme
  ├── layout
  ├── templates
  |   ├── 404.json
  |   ├── article.json
  |   ...
  ...

Template JSON

Template JSON itu file data berisi daftar section yang mau dirender beserta setting-nya. Waktu halaman dirender, section-section itu dirender sesuai urutan di atribut order, tanpa markup apapun di antaranya.

Batasnya: 25 section per template, dan 50 block per section.

Prinsip pentingnya: waktu bikin template JSON, kamu juga harus bikin section yang berisi fungsi inti template itu. Template list-collections harus ngerujuk section yang pakai object collections. Template product harus ngerujuk section yang punya object product dan form produk. Template JSON-nya sendiri gak bisa ngapa-ngapain, dia cuma daftar.

1. Schema

Isinya harus object dengan atribut-atribut ini:

  1. layout (string atau false, opsional), nama file layout tanpa ekstensi. "full-width" ngerender layout/full-width.liquid. Bawaannya theme.liquid. false buat tanpa layout, tapi template tanpa layout gak bisa dikustomisasi di theme editor.
  2. wrapper (string, opsional), elemen HTML pembungkus semua section. Dibahas di bawah.
  3. sections (object, wajib), object dengan ID section sebagai kunci dan data section sebagai nilai. Minimal satu section, dan ID gak boleh duplikat.
  4. order (array, wajib), array ID section sesuai urutan render. Semua ID harus ada di sections, dan gak boleh duplikat.

Contoh lengkap template produk:

{
  "sections": {
    "main": {
      "type": "product",
      "settings": {
        "show_vendor": true
      }
    },
    "recommendations": {
      "type": "product-recommendations"
    }
  },
  "order": [
    "main",
    "recommendations"
  ]
}

Ini ngerender sections/product.liquid dengan setting show_vendor = true, diikuti sections/product-recommendations.liquid.

Semua section yang dirujuk (kecuali app section) harus ada di theme. Kalau nggak, error.

❌ salah, ID recommendations ada di order tapi gak ada di sections

{
  "sections": {
    "main": { "type": "product" }
  },
  "order": ["main", "recommendations"]
}

✅ benar

{
  "sections": {
    "main": { "type": "product" },
    "recommendations": { "type": "product-recommendations" }
  },
  "order": ["main", "recommendations"]
}

2. Penamaan

Nama file harus tipe template yang valid, dengan akhiran opsional buat alternate template: product.json atau product.alternate.json.

3. Section Data

Format data tiap section di dalam sections:

sections: {
<SectionID>: {
  "type": <SectionType>,
  "disabled": <SectionDisabled>,
  "settings": {
    <SettingID>: <SettingValue>
  },
  "blocks": {
    <BlockID>: {
      "type": <BlockType>,
      "settings": {
        <SettingID>: <SettingValue>
      }
    }
  },
  "block_order": <BlockOrder>
}
}

Penjelasannya:

  1. <SectionID>, ID unik section, cuma alfanumerik.
  2. type (wajib), nama file section tanpa ekstensi.
  3. disabled (opsional), kalau true section-nya gak dirender tapi masih bisa dikustomisasi di theme editor. Ini yang terjadi waktu merchant klik “sembunyikan section”. Bawaannya false.
  4. settings, pasangan ID setting dan nilainya, sesuai schema section.
  5. blocks, object dengan ID block (alfanumerik) sebagai kunci, tiap-tiapnya punya type (sesuai schema section) dan settings.
  6. block_order, array ID block sesuai urutan. Harus ada di blocks, gak boleh duplikat.

Formatnya sama persis dengan data section di settings_data.json yang dibahas di 32 Config settings_schema.json, settings_data.json, markets.json. Dan data section gak bisa dibagi antar template: tiap template punya data section-nya sendiri, jadi ID section cukup unik di dalam template itu.

Section bisa ditambahin ke template lewat kode (edit JSON-nya) atau lewat theme editor. Section mana yang muncul di theme editor bisa dibatasi pakai atribut enabled_on atau disabled_on di schema section. Kalau gak ada, section bisa ditambahin ke template manapun. Bahasannya di 26 Sections dan Section Schema.

Satu syarat penting: section harus punya presets di schema-nya biar bisa ditambahin lewat theme editor. Section tanpa preset harus ditulis manual di JSON, dan gak bisa dihapus merchant dari theme editor. Ini berguna buat section inti (kaya main-product) yang emang gak boleh dihapus.

4. Wrapper

Atribut wrapper nyisipin tag HTML di sekeliling semua section template. Cuma boleh <div>, <main>, atau <section>, dengan sintaks mirip selector CSS:

{
  "wrapper": "div#div_id.div_class[attribute-one=value]",
  "sections": {
    "main": {
      "type": "product"
    }
  },
  "order": [
    "main"
  ]
}

Hasilnya:

<div id="div_id" class="div_class" attribute-one="value">
    <!-- product.json sections -->
</div>

Berguna kalau kamu butuh satu pembungkus buat grid atau padding tanpa harus nambahin di tiap section.

5. Setting yang Dikontrol Platform

Di theme editor, Shopify nyediain setting custom CSS di level theme dan section. CSS yang ditulis merchant di situ disimpan di atribut custom_css di data section.

Ini bukan buat developer. Jangan nambahin setting ini sendiri, dan jangan ngedit nilainya setelah diset merchant. Buat kustomisasi CSS dari sisi developer, pakai file CSS di assets/ dan tag stylesheet, terus sediain opsi kustomisasinya lewat theme settings.

Template Liquid

Template Liquid itu file .liquid yang langsung berisi HTML dan Liquid, gak punya schema tetap, dan gak bisa pakai section. Bisa akses semua object global plus object yang terkait template-nya (product di template produk, dan seterusnya).

Kegunaan utamanya sekarang:

  1. Lima template yang wajib Liquid (gift_card, robots.txt, agents.md, llms.txt, llms-full.txt).
  2. Theme lama yang belum migrasi ke JSON.
  3. Kasus khusus di mana kamu butuh layout yang beda total buat halaman tertentu dan merchant gak perlu ngatur apa-apa.

Dulu template Liquid dipakai buat bikin tampilan produk yang beda-beda (semua pakaian pakai template ini, semua elektronik pakai itu). Sekarang itu dilakuin pakai alternate template JSON yang section-nya beda.

Alternate Template

Kadang kamu butuh markup berbeda buat tipe template yang sama. Misalnya template produk khusus yang punya section tambahan buat produk tertentu. Itu alternate template.

Bisa dibikin secara lokal, lewat code editor, atau lewat theme editor. Tapi ada aturan: template default gak bisa diganti sama alternate. Kalau template default gak sesuai, ya edit template default-nya.

1. Penamaan

template-name.template-suffix.template-file-type

Alternate template produk bernama alternate dalam JSON:

product.alternate.json

Dan template.suffix dari 13 Objects Global > template bakal berisi alternate.

2. Cara Pakai

Setelah dibikin, alternate template bisa diterapin dengan tiga cara:

  1. Ditetapkan ke sumber daya di Shopify admin. Buka produknya, di bagian Theme template pilih alternate. Sejak itu produk itu selalu pakai template ini.
  2. Di-preview di theme editor, buat lihat sebelum diterapin.
  3. Dirender lewat parameter URL view, dibahas di bawah.

3. Parameter view

Alternate template bisa dipanggil langsung lewat URL dengan ?view=[suffix]:

/products/example-product?view=alternate

Ini ngerender produk itu pakai product.alternate.json tanpa harus ditetapkan di admin. Berguna buat ngetes, atau buat bikin “tampilan cetak” dan “tampilan cepat” yang diakses lewat link.

❌ salah, alternate template gak bisa ganti default, produk yang gak ditetapkan tetap pakai product.json

Hapus product.json, ganti dengan product.alternate.json, terus berharap semua produk pakai itu

✅ benar, edit product.json langsung kalau mau ngubah semua produk

Edit templates/product.json

Contextual Template

Ini fitur yang lebih baru: merchant bisa nyesuaiin template buat konteks pembeli tertentu, misalnya market Kanada atau pelanggan B2B, lewat theme editor. Waktu itu dilakuin, Shopify bikin file contextual template baru dengan nama:

index.context.<context-string>.json

Isinya cuma override (perubahan) dari template induknya, bukan salinan lengkap. Konteks dan induknya didefinisikan di atas:

{
  "context": {
    "market": "ca"
  },
  "parent": "index.json",
  "sections": {
    "image_banner": {
      "blocks": {
        "heading": {
          "disabled": true,
          "settings": {
            "heading_size": "h2"
          }
        },
      "settings": {
        "show_text_box": true
      }
    }
  }
}

Nilai context bisa "market": "handle-market" atau "b2b": true. Contoh di atas: buat market ca, section image_banner di halaman depan punya block heading yang dimatiin dan setting show_text_box nyala. Section lain tetap ngikutin index.json.

Sebagai developer, kamu jarang nyentuh file ini langsung, karena dibikin merchant lewat theme editor. Tapi kamu harus tau ada, biar gak bingung waktu lihat file index.context.ca.json muncul di theme. Bahasannya di 47 Markets Multi Currency, Multi Bahasa, Localization.

Ringkasan

  1. Template JSON itu daftar section, template Liquid itu markup langsung. Mau section, harus JSON, dan hampir semua template modern JSON.
  2. Satu tipe cuma boleh satu jenis file. product.liquid dan product.json gak bisa hidup bareng.
  3. 16 tipe template, lima di antaranya wajib Liquid: gift_card, robots.txt, agents.md, llms.txt, llms-full.txt.
  4. Template customers/* deprecated. Publish theme tanpa itu otomatis nge-upgrade merchant ke customer accounts baru.
  5. Batas: 1.000 template JSON per theme, 25 section per template, 50 block per section.
  6. JSON template wajib punya sections dan order, opsional layout (atau false) dan wrapper.
  7. Semua ID di order harus ada di sections, semua type harus ada file section-nya, kecuali app section.
  8. disabled: true nyembunyiin section tapi tetap bisa diedit.
  9. Section butuh presets biar bisa ditambahin lewat theme editor, tanpa preset harus ditulis manual dan gak bisa dihapus merchant.
  10. custom_css itu setting platform, jangan ditambahin atau diedit developer.
  11. Alternate template dinamai tipe.suffix.json, diterapin di admin, atau dipanggil pakai ?view=suffix. Gak bisa ganti template default.
  12. Contextual template index.context.<konteks>.json berisi override per market atau B2B, dibikin merchant lewat theme editor.

Bab selanjutnya kita bedah tiap tipe template satu-satu: apa yang harus ada di halaman produk, koleksi, keranjang, blog, dan lainnya, beserta form dan object yang dipakai di masing-masing.

Tampilan Grafik

Tautan Balik