Tema Geliştirme

Giriş

Not: exripe temaları PHP SSR view’lardır. Vitrin, aktif tema klasöründeki PHP şablonlarla render edilir; etkileşim Alpine.js + Storefront JSON API ile sağlanır.

Tema geliştiricisi zorunlu view’ları yazar, theme.json tanımlar, mağaza ayarları / bölüm verilerini okur ve gerektiğinde storefront API’lerini çağırır. Katalog, fiyat, sipariş ve kampanya mantığı çekirdekte kalır — temada yeniden yazılmaz.

Referans: themes/primex/. Yeni tema için Primex’i kopyalayıp giydirin.

Cursor / Claude’a nasıl verilir?

Kod ajanına (Cursor Agent, Claude vb.) tema işi verirken şu dosyayı ekleyin — sözleşmenin kanonik metnidir:

@docs/theme.md
# veya
docs/theme.md

•docs/theme.md — ajan talimatları + tam sözleşme
•docs/theme.contract.json — makine okunur özet
•.cursor/rules/theme-development.mdc — themes/** düzenlenirken otomatik yüklenir

HTML bu sayfa görsel okuma içindir. Ajanların birincil kaynağı her zaman theme.md olsun.

Mimari

Controller ──data──▶ ThemeManager::render(view, $data)
                              │
                              ├─ inject: $themeFolder, $baseUrl, $themeAssetUrl, $temaCssUrl, SEO, CSRF
                              └─ require themes/{aktif}/views/{view}.php
                                       └─ yoksa templates/{view}.php

•core/ThemeManager.php
•Fallback tema: primex
•ZIP kurulum: ThemeInstaller → Admin Tema Yönetimi

İlk temayı oluşturma

cp -R themes/primex themes/my-theme
# theme.json → name, folder, author güncelle (folder = klasör adı)
# Admin → Tema Yönetimi → aktif et
# veya ZIP yükle

Klasör yapısı

themes/my-theme/
├── theme.json
├── assets/tema.css
├── views/  (partials/, home.php, category.php, …)
└── screenshots/preview.png

theme.json

{
  "name": "Primex",
  "folder": "primex",
  "version": "1.0.0",
  "author": "exripe",
  "description": "Primex mağaza teması",
  "cover": "primex.jpg",
  "required_views": ["home", "category", "product-detail", "cart", "search", "checkout", "page", "auth/login", "auth/register"]
}

folder dizin adıyla birebir aynı olmalı. Admin listesi geçersiz manifest ve eksik view uyarısı gösterir.

View değişkenleri

ThemeManager her render’da: $themeFolder, $baseUrl, $themeAssetUrl, $temaCssUrl, SEO alanları, $csrfField.

<link rel="stylesheet" href="<?= htmlspecialchars($temaCssUrl ?? '') ?>">
<script src="<?= htmlspecialchars($themeAssetUrl ?? '') ?>/assets/datalayer.js"></script>

Sepet sözleşmesi

Sunucu sepet CRUD yok. Anahtar: localStorage['exripe_cart']. Satır alanları: productId, variantId, name, slug, color, size, price, compare_at_price, quantity, image.

Kupon: exripe_coupon_code. Olay: cart-update. Sipariş: POST /odeme + CSRF.

Storefront API

Tam liste theme.md ve theme.contract.json içindedir. Özet:

Grup	Örnek uçlar
Katalog	/api/search, /api/product/realtime, /api/variant/{id}, /api/category/{slug}/products
Ticaret	/api/coupon/validate, /api/campaigns/calculate
Müşteri	/api/wishlist/toggle, /api/customer-login
Checkout	/api/checkout-hold, /api/abandoned-cart, /odeme

Tema kullanmaz: /api/store-*, /api/admin/*, /api/plugin-*.

Bölümler & ayarlar

slider banner banner_grid product_list marquee text_block image_text brand_images text_slider

Global ayarlar $themeSettings ile gelir. Tema kendi settings şemasını tanımlamaz.

Çeviriler

<?= htmlspecialchars(lang('frontend.cart.empty', 'Sepetiniz boş')) ?>

ZIP / paketleme

ZIP kökünde theme.json + views/ (+ assets/)
Admin → Tema Yönetimi → Tema yükle (ZIP) (POST /admin/themes/upload)
İsteğe bağlı: aynı klasör adına üzerine yaz
Aktif et

Güvenlik: path traversal engelli, izinli uzantılar, Theme::validateManifest.