Tema yapısı
Bir Biticaret temasının klasörleri, şablonları, bölümleri, blokları, ayarları, çevirileri ve varlıkları.
Bir tema; Liquid, JSON, CSS ve JavaScript dosyalarından oluşan bir klasördür. Mağaza vitrinini tema çizer; müşteri hesabı sayfaları ve ödeme adımı platformundur.
Buradaki örnekler iskelet temadandır (biticaret theme init).
Klasörler
layout/ theme.liquid her sayfayı sarar; password.liquid şifre sayfasını
templates/ her sayfa türü için bir şablon (JSON veya Liquid)
sections/ bölümler ve bölüm grupları (header-group.json, footer-group.json)
blocks/ tema blokları
snippets/ {% render %} ile çağrılan parçalar
assets/ CSS, JavaScript, görseller, yazı tipleri
config/ settings_schema.json ve settings_data.json
locales/ çeviriler ve *.schema.json dosyaları
Bir tema yalnızca bu sekiz klasörden oluşur. Alt klasöre yalnızca templates/customers ve templates/metaobject altında izin vardır.
Yükleme ve denetim
Tema bir ZIP olarak yüklenir ve yayınlanmamış bir tema olur; adı config/settings_schema.json içindeki theme_info bölümünden, yoksa ZIP'in dosya adından gelir. biticaret theme check yüklemenin denetimlerini çalıştırır:
- Sınırlar: ZIP en çok 50 MB, açılmış hali en çok 200 MB, mağaza başına en çok 20 tema. Tema klasörlerinin dışındaki dosyalar, mutlak yollar,
..ve sembolik bağlar reddedilir. Temayı saran tek bir üst klasör kabul edilir. - Zorunlu dosyalar:
layout/theme.liquidileindex,product,collection,cart,page,searchve404şablonları yoksa hata;list-collectionsvepasswordşablonları,config/settings_schema.jsonve varsayılan çeviri dosyası yoksa uyarı. - JSON: her JSON dosyası ayrıştırılabilmelidir.
- Liquid: ayrıştırma hataları dosya ve satırıyla bildirilir; bilinmeyen bir etiket ve bilinmeyen bir filtre hatadır. Bozuk olduğu halde çizilebilen Liquid uyarıdır.
- Diğer: ayrıştırılamayan bir
visible_ifkoşulu ve Sass dosyaları hatadır.
Hatalar yüklemeyi durdurur, uyarılar durdurmaz. --strict uyarıları da hata sayar.
Yüklenen bir temayı mağazada yayınlamadan önizleme bağlantısıyla görebilirsiniz; bir geliştirme mağazasının temalarını ve önizleme bağlantılarını biticaret theme list --store <handle> listeler (CLI).
Düzen
layout/theme.liquid her sayfayı sarar. İki nesne zorunludur: content_for_header (<head> içinde; window.Biticaret nesnesini ve derlenen varlık bağlantılarını yazar) ve content_for_layout (şablonun çıktısı).
<!doctype html>
<html lang="{{ request.locale.iso_code }}">
<head>
<title>{{ page_title }}{% unless page_title contains shop.name %} | {{ shop.name }}{% endunless %}</title>
<link rel="canonical" href="{{ canonical_url }}">
{{ content_for_header }}
{{ 'base.css' | asset_url | stylesheet_tag }}
</head>
<body class="template-{{ template.name }}">
{% sections 'header-group' %}
<main id="main" class="page-width">
{{ content_for_layout }}
</main>
{% sections 'footer-group' %}
</body>
</html>
Bir Liquid şablonu {% layout 'ad' %} ile başka bir düzen seçer.
Şablonlar
Her sayfa türünün bir şablonu vardır. Vitrinin çizdiği şablonlar:
| Şablon | Sayfa |
|---|---|
index |
Ana sayfa |
product |
Ürün |
collection |
Koleksiyon |
list-collections |
Koleksiyon listesi |
cart |
Sepet |
page |
İçerik sayfası |
search |
Arama |
404 |
Bulunamayan sayfa |
password |
Şifre korumalı mağazanın giriş sayfası |
gift_card |
Hediye kartı sayfası |
blog |
Blog (/blogs/<blog>) ve etikete göre süzülmüş blog (/blogs/<blog>/tagged/<etiket>) |
article |
Blog yazısı (/blogs/<blog>/<yazı>) |
metaobject/<tür> |
Web sayfaları açık bir özel veri türünün kaydı (/pages/<tür adresi>/<kayıt adresi>); şablon yoksa adres 404 verir |
product.<ek>.json gibi adlarla aynı türün başka şablonları yazılabilir. Şablon sırasıyla ?view=<ek> parametresinden, kaynağın kendi şablon ekinden, yoksa varsayılandan seçilir; temada olmayan bir ek varsayılan şablonu çizer.
password şablonu yoksa platform basit bir şifre formu yazar. Politika sayfalarını (/policies/<ad>) platform yazar ve temanın düzeninin içine yerleştirir.
Müşteri hesabı sayfalarını (giriş, hesap, sipariş, adresler, profil, verilerim) platform çizer ve temanın düzeninin içine yerleştirir; templates/customers/* dosyaları temada bulunabilir ama kullanılmaz. Düzen bu sayfaları request.page_type ile ayırt eder (customers/login, customers/account, customers/order, customers/addresses, customers/profile). Müşteriler e-postalarına gelen kodla giriş yapar; /account/register ve /account/recover giriş sayfasına yönlenir. Blog yorumları yoktur: yorum alanları boş döner.
Bir JSON şablonu, sayfadaki bölümleri ve sıralarını söyler:
{
"sections": {
"featured-collection": {
"type": "featured-collection",
"settings": {}
}
},
"order": [
"featured-collection"
]
}
type, sections/ altındaki dosyanın adıdır; settings o bölümün ayar değerleridir.
Bir bölümün blokları blocks ve block_order ile yazılır:
{
"sections": {
"featured-collection": {
"type": "featured-collection",
"settings": { "heading": "Öne çıkanlar" },
"blocks": {
"promo": {
"type": "promo",
"settings": { "text": "Kargo bedava" }
},
"note": {
"type": "promo",
"disabled": true,
"settings": { "text": "Gizli not" }
}
},
"block_order": ["promo", "note"]
}
},
"order": ["featured-collection"]
}
blocks bloğun kimliğinden bloğa giden bir nesnedir; type bölüm şemasının blocks listesindeki ya da blocks/ altındaki bir adı, settings o bloğun ayar değerlerini taşır. Bloklar block_order sırasıyla çizilir; block_order yoksa blocks nesnesindeki sıra kullanılır. "disabled": true olan blok çizilmez. "static": true olan blok listede görünmez, yalnızca kimliğiyle çizilir ({% content_for 'block', type: 'promo', id: 'note' %}; ayarlarını blocks içindeki aynı kimlikli girdiden alır). Bir tema bloğu kendi içinde de blocks ve block_order taşıyabilir.
Bölümler
Bir bölüm, sections/ altında bir Liquid dosyasıdır: işaretlemesi ve sonunda {% schema %} içinde ayarlarının tanımı.
<section class="featured-collection">
<h2>{{ section.settings.heading | escape }}</h2>
<ul class="grid">
{%- for product in featured.products limit: section.settings.limit -%}
<li>{% render 'product-card', product: product %}</li>
{%- else -%}
<li>{{ 'collections.general.empty' | t }}</li>
{%- endfor -%}
</ul>
</section>
{% schema %}
{
"name": "t:sections.featured-collection.name",
"settings": [
{
"type": "text",
"id": "heading",
"label": "t:sections.featured-collection.settings.heading.label",
"default": "Öne çıkanlar"
},
{
"type": "collection",
"id": "collection",
"label": "t:sections.featured-collection.settings.collection.label"
}
],
"presets": [
{
"name": "t:sections.featured-collection.name"
}
]
}
{% endschema %}
Her bölüm sayfada <div id="biticaret-section-<id>" class="biticaret-section"> içinde çizilir. Bölüm; section.id, section.settings ve section.blocks ile kendi verisine ulaşır.
Bölüm grupları düzenin çağırdığı bölüm listeleridir ({% sections 'header-group' %}), JSON şablonu gibi yazılır ve biticaret-section-group-<grup> sınıfıyla çizilir:
{
"type": "header",
"name": "t:sections.header-group.name",
"sections": {
"header": {
"type": "header",
"settings": {}
}
},
"order": [
"header"
]
}
{% section 'ad' %} tek bir bölümü doğrudan çizer.
Bloklar
Bir bölümün şeması blocks ile hangi blokları kabul ettiğini söyler; bölüm onları section.blocks üzerinden çizer. blocks/ klasöründeki tema blokları {% content_for 'blocks' %} ile çizilir ve <div id="biticaret-block-<id>" class="biticaret-block …"> içine sarılır.
Her bloğun kök öğesine {{ block.biticaret_attributes }} yazın: tema düzenleyicisi bloğu bununla bulur. Düzenleyici dışında boştur.
Şemasının blocks listesinde {"type": "@app"} olan bir bölüm uygulama bloklarını kabul eder. Uygulama blokları <div id="biticaret-block-<id>" class="biticaret-app-block"> içinde çizilir; JSON şablonlarında türleri biticaret://apps/<uygulama>/blocks/<ad>/<uuid> biçimindedir; uygulama kaldırılınca blok hiçbir şey çizmez.
Uygulama gömmeleri (sayfanın tamamına eklenen uygulama blokları) config/settings_data.json içinde current.blocks altında tutulur; açık olanlar </head> veya </body> öncesine yazılır. Mağaza sahibi onları tema düzenleyicisinden açıp kapatır.
Ayarlar
config/settings_schema.json temanın genel ayarlarını tanımlar; ilk öğesi theme_info temanın adını ve sürümünü taşır:
[
{
"name": "theme_info",
"theme_name": "Skeleton",
"theme_version": "1.0.0",
"theme_author": "Biticaret"
},
{
"name": "t:settings_schema.colors.name",
"settings": [
{
"type": "color",
"id": "color_background",
"label": "t:settings_schema.colors.settings.background.label",
"default": "#ffffff"
}
]
}
]
config/settings_data.json değerleri current altında tutar; Liquid onları settings.<id> olarak okur:
{
"current": {
"color_background": "#ffffff",
"page_width": 1200
}
}
Mağaza sahibi değerleri yönetim panelindeki ayar formundan ve tema düzenleyicisinden değiştirir; ikisi de bu dosyaları yazar.
Ayar türleri:
| Tür | Değer |
|---|---|
text, textarea, html, richtext, inline_richtext |
Metin |
select, radio, text_alignment |
Seçeneklerden biri |
checkbox |
Doğru veya yanlış |
number, range |
Sayı |
color, color_background |
Renk |
color_scheme, color_scheme_group |
Renk şeması ve şemaların tanımı (1 ile 50 arası şema) |
font_picker |
Biticaret'in yazı tipi kataloğundan veya sistem yazı tiplerinden biri |
image_picker, video, video_url |
Görsel, yüklenmiş video, YouTube veya Vimeo bağlantısı |
url, link_list |
Bağlantı, menü |
product, collection, page, product_list, collection_list |
Mağazanın kaynakları |
blog, article |
Blog ve blog yazısı (blog/yazı tanıtıcısıyla); Liquid'de blog ve article nesnesi |
metaobject, metaobject_list |
Bir özel veri kaydı veya kayıt listesi; tür şemada metaobject_type ile verilir. Liquid'de özel veri kaydı nesnesi |
liquid |
Liquid kodu (en çok 50 000 bayt) |
Kaynak ayarlarının değerleri kaydedilirken mağazanın kayıtlarıyla denetlenir; bulunamayan bir kaynak boş döner.
url ayarı yolları, #, http(s), mailto:, tel: ve biticaret:// başvurularını alır. Bir ayarın visible_if koşulu yanlışken ayar formda gizlenir ve değerini korur; vitrin her değeri çizer.
Çeviriler
locales/ altında dil başına bir dosya vardır; varsayılan dilin dosyası .default taşır (tr.default.json). Alıcının gördüğü her metin buradan t filtresiyle okunur:
{
"general": {
"skip_to_content": "İçeriğe geç"
}
}
<a class="skip-link" href="#main">{{ 'general.skip_to_content' | t }}</a>
*.schema.json dosyaları ayar formundaki adları tutar; şemalar onlara t: ile başvurur ("label": "t:settings_schema.colors.settings.background.label").
Varlıklar
assets/ altındaki dosyalara asset_url ile bağlanın; adres dosyanın içeriğinden türeyen bir ?v= taşır, bu yüzden dosya değişince adres de değişir:
{{ 'base.css' | asset_url | stylesheet_tag }}
Sabit CDN veya mağaza adresi yazmayın: asset_url, file_url ve routes kullanın. Sass desteklenmez.
Bölümlerin {% stylesheet %} ve {% javascript %} içerikleri temanın tamamı için tek pakette derlenir ve content_for_header ile bağlanır.
Sepet ve ödeme sınırı
Tema sepet sayfasını (templates/cart) ve sepete ekleme arayüzünü çizer; sepeti /cart/*.js adresleriyle değiştirir (Temanın çağırdığı adresler). Ödeme sayfası (/checkouts/<sepet jetonu>) platformundur: tema onu çizmez ve değiştiremez; tutarlar, kargo seçenekleri, ödeme yöntemleri ve onay kutuları orada platformun kendi arayüzüyle gelir. Ödeme adımını uygulamalar uzantılarla değiştirir (ödeme fonksiyonları ve arayüz uzantıları: Yapılandırma dosyaları); tema bunun için bir şey yapmaz.
Önizleme ve yayın
Yönetim panelinde Online mağaza > Temalar sayfası yayındaki temayı ve tema kitaplığını gösterir. Yüklenen ya da kopyalanan her tema yayınlanmamış olarak gelir ve her temanın Önizle bağlantısı vardır. Bağlantı mağazanın adresine ?preview_theme_id=<tema numarası> ekler; tema numarası o bağlantıdadır. Vitrin numarayı imzalı bir çereze yazar, parametresiz sayfaya yönlendirir ve tarayıcı o temayı görmeye devam eder; numarayı boş vermek önizlemeyi kapatır. Bağlantıya sahip olan herkes önizleyebilir; şifreli bir mağaza yine şifre ister.
Hazır olduğunda temanın Yayınla düğmesi onu mağazanın yayındaki teması yapar ve ziyaretçiler onu görür. Kopyala bir temanın yayınlanmamış bir kopyasını açar, yani yayındaki temayı değiştirmeden denemek için kullanılır. Bir mağaza en çok 20 tema tutar. Şimdilik bir tema mağazasına gönderim yoktur: temalar ZIP olarak yüklenir ve yalnızca yükleyen mağazada bulunur.
Temanın çağırdığı adresler
- Sepet:
/cart.js,/cart/add.js,/cart/change.js,/cart/update.js,/cart/clear.js(.jsonekiyle de). Sepeti değiştiren bir isteksectionsparametresiyle bölümleri de ister; yanıt onlarısectionsaltında,sections_urlsayfası için (yoksa isteğin geldiği sayfa için) çizilmiş verir. - Sepetin ve
localizationformunun gönderimleri yalnızca mağazanın kendi sayfalarından kabul edilir: başka bir adresten gelen gönderim 403 alır ve hiçbir şeyi değiştirmez. - Ürün:
/products/<ürün>.jsürünü bütün varyantlarıyla JSON olarak verir. - Bölüm çizimi:
?sections=<id,…>(en çok beş bölüm) ve?section_id=<id>. - Arama önerileri:
/search/suggest.json. Ürün önerileri:/recommendations/products. - Blog akışı:
/blogs/<blog>.atom.
Adlar ve JavaScript
- HTML, CSS ve JavaScript'te:
biticaret-section-<id>,biticaret-section,biticaret-block-<id>,biticaret-app-block. window.Biticaret:shop,locale,currency,country,theme,routes.rootvedesignMode.window.Biticaret.customerPrivacy, ziyaretçinin çerez iznini verir:analyticsProcessingAllowed(),marketingAllowed(),preferencesProcessingAllowed(),shouldShowBanner(),showPreferences(),setTrackingConsent({ analytics, marketing, preferences }, geriÇağırma)vecurrentVisitorConsent(). Temanın gizli bir bağlantısı veya düğmesidata-biticaret-privacy-preferencestaşırsa, mağazanın çerez bildirimi açıkken gösterilir ve tercihleri yeniden açar.- Tema düzenleyicisi bölümün veya bloğun düğümünde şu olayları yayar:
biticaret:section:load,biticaret:section:unload,biticaret:section:select,biticaret:section:deselect,biticaret:section:reorder,biticaret:block:select,biticaret:block:deselect. Düzenleyiciderequest.design_modedoğrudur.