Sayudha

32 Config settings_schema.json, settings_data.json, markets.json

Properties2
descriptionFolder config, settings_schema.json buat definisi theme setting dan theme_info, settings_data.json buat nilai tersimpan, current, presets, platform_customizations, dan markets.json buat pewarisan kustomisasi per market
tagsshopify, theme, arsitektur

7 menit baca

Di 30 Settings dan Input Settings kita bahas setting yang hidup di section dan block. Tapi setting global theme (warna, font, layout umum) hidup di tempat lain: folder config. Bab ini pendek tapi penting karena tiga file di sini ngatur definisi, nilai, dan pewarisan theme setting.

Folder config itu tempat theme setting didefinisiin dan disimpan nilainya. Theme setting cocok buat hal umum yang berlaku di seluruh toko: tipografi, warna, skema warna, lebar halaman. Aksesnya lewat object settings dari 13 Objects Global > settings.

Lokasi dan Isi

└── theme
  ...
  ├── config
  |   ├── settings_data.json
  |   ├── settings_schema.json
  |   └── markets.json
  └── locales

Sampai tiga file, masing-masing punya schema sendiri:

  1. settings_schema.json (wajib), ngatur susunan dan isi area Theme settings di theme editor.
  2. settings_data.json (wajib), nyimpen nilai dari setting yang didefinisiin di settings_schema.json.
  3. markets.json (opsional), ngatur sumber pewarisan kustomisasi theme per market. Cuma muncul kalau theme punya kustomisasi spesifik market.

Analoginya: settings_schema.json itu formulirnya, settings_data.json itu formulir yang udah diisi, dan markets.json itu catatan formulir mana yang nyontek dari mana.

settings_schema.json

File ini berupa array object, tiap object mewakili satu kategori setting (jadi satu grup di sidebar Theme settings: Colors, Typography, Layout, dan seterusnya). Tiap object wajib punya:

  1. name, nama kategorinya.
  2. settings, array setting, tipe apapun dari 30 Settings dan Input Settings.
[
{
  "name": "Category",
  "settings": [
    ...
  ]
},
...
]

Karena ini JSON murni, semua isinya harus JSON valid, dan tiap setting harus ngikutin sintaks tipenya (misalnya range wajib min/max/default angka). Contoh kategori Colors:

{
  "name": "Colors",
  "settings": [
    {
      "type": "color",
      "id": "color_page_bg",
      "label": "Page background",
      "default": "#FFFFFF"
    }
  ]
}

Dua tipe setting yang cuma boleh di file ini: color_palette dan color_scheme_group. Dan atribut placeholder buat number, text, textarea cuma tampil buat setting di file ini.

1. theme_info: Metadata Theme

Kamu bisa nambahin metadata theme yang muncul di menu Theme actions di kiri atas theme editor: nama theme, versi, link dokumentasi, dan kontak support. Caranya, sisipin object dengan name bernilai theme_info di array settings_schema.json:

[
  {
    "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\/",
  },
  ...
]

Atributnya:

  1. name, harus theme_info.
  2. theme_name, nama theme.
  3. theme_author, pembuat theme.
  4. theme_version, nomor versi.
  5. theme_documentation_url, URL dokumentasi buat merchant.
  6. theme_support_email atau theme_support_url, kontak support.

Aturannya ketat: semua atribut di atas wajib, tapi buat support kamu cuma boleh nyantumin salah satu dari theme_support_email atau theme_support_url. Nyantumin dua-duanya, atau ninggalin salah satu atribut lain, bikin error.

❌ error, dua-duanya ada

{
  "name": "theme_info",
  "theme_name": "Toko Saya",
  "theme_author": "Sayudha",
  "theme_version": "1.0.0",
  "theme_documentation_url": "https://example.com/docs",
  "theme_support_email": "[email protected]",
  "theme_support_url": "https://example.com/support"
}

✅ benar, satu aja

{
  "name": "theme_info",
  "theme_name": "Toko Saya",
  "theme_author": "Sayudha",
  "theme_version": "1.0.0",
  "theme_documentation_url": "https://example.com/docs",
  "theme_support_email": "[email protected]"
}

Versi ini juga yang dipakai waktu ngelola rilis theme dan waktu submit ke Theme Store di 72 Review, Listing, dan Submit.

settings_data.json

Tempat nilai setting disimpan. Waktu kamu definisiin setting color_page_bg dengan default #FFFFFF di settings_schema.json, Shopify nambahin entri di settings_data.json:

...
"color_page_bg": "#FFFFFF"
...

Tiap kali merchant ngubah nilainya di theme editor, file ini diperbarui. Jadi file ini itu milik merchant: waktu kamu push update theme, hati-hati jangan nimpa file ini, kalau gak semua kustomisasi mereka hilang. Alur amannya dibahas di 08 GitHub Integration dan Version Control dan 05 Shopify CLI.

1. Strukturnya

Tiga object induk:

  1. current (wajib), semua nilai setting yang lagi tersimpan di theme editor.
  2. presets (wajib), satu object per theme preset, formatnya sama kaya current.
  3. platform_customizations (opsional), nilai setting yang dikontrol platform. Object ini ditambahin Shopify sendiri kalau merchant pakai setting semacam itu.
{
"current": {
  "color_page_bg": "#FFFFFF",
  ...
},
"presets": {
  "preset name": {
    "color_page_bg": "#000000",
    ...
  }
}
}

Catatan: current juga bisa berisi section group dan section buat area tertentu (misalnya sections buat konten yang gak di template), tapi buat theme modern kontennya udah pindah ke template JSON dan section group dari 23 Templates dan 27 Section Groups dan Migrasinya.

2. Theme Presets

Preset bikin kamu bisa nyediain sampai lima desain siap pakai dari satu basis kode theme yang sama. Tiap preset itu kombinasi layout, palet warna, tipografi, dan elemen visual lain. Semua preset dikemas dalam satu paket theme, dan di Theme Store tiap preset dapat halaman listing sendiri yang diarahin ke industri dan ukuran katalog tertentu.

Jangan ketuker sama preset section/block dari 26 Sections dan Section Schema > 11. presets: itu konfigurasi awal buat satu section. Theme preset ini konfigurasi awal buat seluruh theme setting.

Waktu merchant milih theme preset, object current diperbarui pakai nilai preset itu. Tapi cuma setting presentasional yang ditimpa.

3. Setting Presentasional

Setting yang berkaitan aspek visual: warna dan font teks, atau apakah elemen tertentu ditampilin. Tipe input yang dianggap presentasional dan ditimpa waktu ganti theme preset:

  1. checkbox
  2. color
  3. color_background
  4. color_palette
  5. color_scheme
  6. color_scheme_group
  7. font_picker
  8. number
  9. radio
  10. range
  11. select

Yang gak ada di daftar (text, richtext, image_picker, product, collection, url, dan seterusnya) dipertahankan, karena itu konten merchant: logo, judul, produk pilihan. Ini alasan kenapa di 30 Settings dan Input Settings disebut “setting text gak diperbarui waktu ganti preset”. Ganti preset ngubah gaya, bukan ngehapus isi.

4. Platform-controlled Settings

Theme editor nyediain setting Custom CSS di level theme dan section. CSS yang ditambahin merchant di level theme disimpan di atribut custom_css object platform_customizations:

{
  "current": { ... },
  "presets": { ... },
  "platform_customizations": {
    "custom_css": [
      "h1 { letter-spacing: 0.1em; }"
    ]
  }
}

Sebagai developer, jangan nambahin setting ini dan jangan ngedit nilainya setelah diset merchant. Pakai aset CSS dan tag {% stylesheet %} sendiri, dan sediain opsi kustomisasi lewat theme setting.

5. Batasan

  1. Ukuran settings_data.json maksimal 1,5MB.
  2. Theme maksimal lima preset.

Batas 1,5MB itu gampang kelewat kalau kamu nyimpen konten panjang (misalnya banyak richtext atau liquid 50kb) di theme setting, makanya konten sebaiknya di section/block, bukan di theme setting.

markets.json

File ini ngatur gimana kustomisasi theme diwariskan antar market (pasar, misalnya Eropa, Amerika Utara, Kanada). Cuma muncul di config kalau theme punya kustomisasi spesifik market, misalnya merchant ngubah banner homepage khusus buat pengunjung dari Kanada.

Fitur Markets Shopify ngizinin satu market mewarisi dari banyak induk, tapi kustomisasi theme butuh tiap market punya tepat satu induk. markets.json yang ngatur struktur pohon ini, dan developer bisa ngubahnya.

1. Isinya

/*
 * ------------------------------------------------------------
 * IMPORTANT: The contents of this file are auto-generated.
  *
 * This file may be updated by the Shopify admin theme editor
 * or related systems. Please exercise caution as any changes
 * made to this file may be overwritten.
 * ------------------------------------------------------------
  */
{
  "markets": {
    "europe": {
      "parent": "@default"
    },
  "north-america": {
      "parent": "@default"
    },
  "canada": {
      "parent": "north-america"
    },
  "united-states": {
      "parent": "north-america"
    }
  }
}

Di contoh ini: Europe dan North America mewarisi dari default toko. Canada dan United States mewarisi dari North America. Jadi kalau merchant ngubah sesuatu buat North America, Kanada dan AS otomatis ikut, kecuali mereka punya kustomisasi sendiri yang lebih spesifik.

2. Ngubah Pewarisan

Waktu merchant ngustomisasi theme buat market baru, Shopify nentuin induknya otomatis. Kalau mau ngubah, edit field parent market itu. Nilainya bisa:

  1. @default, default toko, induk bawaan semua market.
  2. Handle market induk manapun buat market itu.

File ini auto-generated dan bisa ditimpa theme editor atau sistem terkait, jadi edit seperlunya dan jangan simpan logika penting di sini. Bahasan Markets secara umum, termasuk multi currency dan multi bahasa, ada di 47 Markets Multi Currency, Multi Bahasa, Localization.

Ringkasan

  1. Folder config nampung theme setting global: settings_schema.json (definisi), settings_data.json (nilai), markets.json (pewarisan per market, opsional).
  2. settings_schema.json itu array kategori, tiap kategori punya name dan settings, harus JSON valid, dan satu-satunya tempat buat color_palette dan color_scheme_group.
  3. theme_info nyantumin metadata theme di menu Theme actions: theme_name, theme_author, theme_version, theme_documentation_url, dan salah satu dari theme_support_email/theme_support_url, semua wajib.
  4. settings_data.json punya current, presets, dan platform_customizations, diperbarui tiap merchant ngubah setting, jadi jangan ditimpa waktu update theme.
  5. Theme preset (maksimal lima) nyediain desain siap pakai dari satu kode, tiap preset dapat listing sendiri di Theme Store, dan waktu diganti cuma setting presentasional (checkbox, warna, font, number, radio, range, select) yang ditimpa, konten merchant dipertahankan.
  6. Custom CSS merchant disimpan di platform_customizations.custom_css, jangan disentuh developer.
  7. settings_data.json maksimal 1,5MB.
  8. markets.json nentuin satu induk per market lewat parent (@default atau handle market lain), auto-generated, muncul cuma kalau ada kustomisasi spesifik market.

Bab selanjutnya kita ke folder locales: storefront locale file buat teks yang dilihat pembeli, schema locale file buat label setting di theme editor, filter t, sintaks t: di schema, pluralisasi, dan cara nambahin bahasa baru ke theme.

Tampilan Grafik

Tautan Balik