# 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.liquid` ile `index`, `product`, `collection`, `cart`, `page`, `search` ve `404` şablonları yoksa hata; `list-collections` ve `password` şablonları, `config/settings_schema.json` ve 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_if` koş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](../cli.md)).

## 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ı).

```liquid
<!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:

```json
{
  "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:

```json
{
  "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ı.

```liquid
<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:

```json
{
  "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:

```json
[
  {
    "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:

```json
{
  "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:

```json
{
  "general": {
    "skip_to_content": "İçeriğe geç"
  }
}
```

```liquid
<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:

```liquid
{{ '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](#temanin-cagirdigi-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ı](../apps/configuration.md)); 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` (`.json` ekiyle de). Sepeti değiştiren bir istek `sections` parametresiyle bölümleri de ister; yanıt onları `sections` altında, `sections_url` sayfası için (yoksa isteğin geldiği sayfa için) çizilmiş verir.
- Sepetin ve `localization` formunun 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.root` ve `designMode`.
- `window.Biticaret.customerPrivacy`, ziyaretçinin çerez iznini verir: `analyticsProcessingAllowed()`, `marketingAllowed()`, `preferencesProcessingAllowed()`, `shouldShowBanner()`, `showPreferences()`, `setTrackingConsent({ analytics, marketing, preferences }, geriÇağırma)` ve `currentVisitorConsent()`. Temanın gizli bir bağlantısı veya düğmesi `data-biticaret-privacy-preferences` taşı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üzenleyicide `request.design_mode` doğrudur.

## Başvuru

- [Nesneler](objects.md)
- [Etiketler](tags.md)
- [Filtreler](filters.md)
