Kendi temanı geliştirmek

Bir BorCube teması Liquid şablonlarından, CSS ve JavaScript dosyalarından ve bir theme.json dosyasından oluşur. Sunucu kodu yoktur. En kolay yol, Bor'u genişleten bir alt tema yazmaktır: yalnız değiştirmek istediğin dosyaları getirirsin, geri kalan her sayfa Bor'dan gelir.

Liquid, {{ }} ile değer basan ve {% %} ile koşul ve döngü kuran bir şablon dilidir. BorCube'un eklediği değişken, filtre ve etiketler Liquid referansı makalesinde.

Başlamanın en kolay yolu#

1. Yönetim paneli → Görünüm → Temalar sayfasında başlangıç olarak kullanacağın temanın kartında ZIP indir'e bas. Bir alt tema (ör. Borte) indirirsen paket de alt tema olur.
2. ZIP'i aç ve theme.json içinde id ve name değerlerini değiştir. BorCube ile gelen temaların kimlikleri kullanılamaz.
3. Dosyaları düzenle, klasörü yeniden ZIP'le ve Tema yükle (ZIP) ile kur (Tema ZIP'i).
4. Önizle ile dene. Küçük düzeltmeleri panelde Kodu düzenle ile yapabilirsin.

Klasör yapısı#

gece/
  theme.json
  layout/theme.liquid
  sections/header.liquid
  sections/gece-hero.liquid
  snippets/gece-kart.liquid
  locales/tr.json
  locales/en.json
  assets/css/gece.css
  assets/img/preview.webp

Dosya adlarında küçük harf, rakam, - ve _ kullan; boşluk ve Türkçe karakter olmaz. Bağımsız bir temada layout/theme.liquid, templates/index.liquid, templates/404.liquid ve theme.json'da tanımladığın her bölüm için sections/<bölüm>.liquid zorunludur. Bağımsız temada sitenin kullandığı bütün şablonları da sen sağlarsın; eksik şablonu olan sayfa hata verir. Bu yüzden alt tema ile başlamanı öneririz.

theme.json#

{
  "id": "gece",
  "name": "Gece",
  "version": "1.0.0",
  "author": "Senin adın",
  "description": "Bor'un koyu bir çeşitlemesi.",
  "engine": 1,
  "extends": "bor",
  "preview": "img/preview.webp",
  "locales": ["tr", "en"],
  "hide_settings": ["header_image", "pixel_headings"],
  "settings": [
    {
      "id": "colors",
      "label": "Renkler",
      "fields": [
        { "id": "color_primary", "type": "color", "label": "Ana renk", "default": "#22c55e" }
      ]
    }
  ],
  "sections": {
    "gece-hero": {
      "label": "Gece: karşılama",
      "limit": 1,
      "settings": [
        { "id": "title", "type": "text", "label": "Başlık", "default": "Hoş geldin" },
        { "id": "image", "type": "image", "label": "Görsel" }
      ]
    }
  },
  "templates": {
    "index": { "sections": [{ "type": "gece-hero" }, { "type": "home-feed" }] }
  }
}

Ayar alanları

Her alanın bir id'si (küçük harfle başlar; harf, rakam ve _), bir label'ı (en çok 80 karakter) ve isteğe bağlı bir info açıklaması (en çok 240 karakter) vardır.

Alan türüne uymayan değerler saklanmaz: bağlantı ve görsel alanlarında kayıt bir uyarıyla durur, diğer alanlarda alanın varsayılanı kullanılır. Değerlere şablonda settings.color_primary gibi, bölüm ayarlarına section.settings.title gibi ulaşırsın.

Bölümler

sections içindeki her bölümün bir label'ı, en çok 60 ayar alanı ve isteğe bağlı bir limit'i (bir sayfada en çok kaç tane, 1–20) olur. "static": true olan bölümler (başlık ve alt bilgi) özelleştiricide sıralanmaz; layout onları {% section 'header' %} ile yerleştirir. Diğer bölümleri site sahibi ana sayfaya ekler, sıralar ve gizler. Bölüm kimliği küçük harfle başlar; küçük harf, rakam ve tire içerir.

Her bölümün dosyası sections/<bölüm>.liquid'dir:

<section class="section gece-hero" id="{{ section.id }}">
  <div class="container">
    <h1>{{ section.settings.title }}</h1>
    {%- if section.settings.image != blank -%}
      <img src="{{ section.settings.image }}" alt="">
    {%- endif -%}
    <p>{{ 'home.registered' | t: n: stats.users }}</p>
  </div>
</section>

Bölümler ana sayfa şablonunun değişkenlerini de görür; örnekteki stats.users kayıtlı oyuncu sayısıdır.

Alt tema nasıl birleşir?#

• Alt temadaki bir dosya, ana temadaki aynı yoldaki dosyanın yerine geçer.
• locales dosyaları birleştirilir: alt temada yalnız eklediğin ya da değiştirdiğin yazıları yazarsın.
• Ayar alanları kimliğe göre birleşir: aynı id ana temanınkinin yerine geçer, yeni grup ve alanlar eklenir, hide_settings listesindekiler çıkarılır.
• sections ve templates anahtara göre birleşir. Alt temanın templates.index listesi Bor'unkinin yerine geçer.
• assets dosyaları önce alt temada, sonra ana temada aranır.
• Tek seviye vardır: başka bir temayı genişleten bir temayı genişletemezsin.

Kendi CSS'inin yüklenmesi için layout gerekir. Kod düzenleyicide Bor'un layout/theme.liquid dosyasını aç, içeriğini kendi temana kopyala ve Bor'un stil satırının altına kendi dosyanı ekle:

<link rel="stylesheet" href="{{ 'css/theme.css' | asset_url }}">
<link rel="stylesheet" href="{{ 'css/gece.css' | asset_url }}">

Hazır alt temalar da böyle çalışır. Bor'un stili renkleri --primary, --secondary, --bg, --surface, --text gibi CSS değişkenlerinden alır; koyu mod :root[data-scheme='dark'] seçicisiyle gelir. Kendi CSS'inde bu değişkenleri değiştirirsen mağaza, profil ve destek gibi iç sayfalar da senin renklerine geçer.

Layout'ta kalması gerekenler

Layout'u baştan yazıyorsan Bor'unkindeki şu parçaları koru:

• <title>{{ seo.title }}</title> ve {% render 'seo-meta' %}: arama motoru ve paylaşım etiketleri.
• <script src="/borcube.js" defer></script>: menü, açılır pencere, adres kopyalama gibi davranışlar.
• turnstile.site_key doluyken Cloudflare Turnstile betiği.
• minimal_layout doğruyken başlık ve alt bilginin gizlenmesi (bakım sayfası).
• {{ content_for_layout | raw }}, license_banner uyarısı, {% render 'popup', popup: popup %} ve data-toasts kutusu.

Güvenlik kuralları#

• Sayfaya yazılan her satır içi <script> etiketi nonce="{{ csp_nonce }}" taşımalı; yoksa tarayıcı çalıştırmaz.
• Dış sitelerden betik, stil dosyası ve yazı tipi yüklenmez. Bunları assets/ içine koy ve asset_url ile çağır. Görseller https:// adreslerden gelebilir.
• POST ile gönderilen her formda {% render 'security-fields' %} olmalı. Giriş, kayıt ve şifre sıfırlama formlarında {% render 'security-fields', captcha: true %} kullan.
• Kayıt, kredi yükleme ve sepet formlarında {% render 'legal-accept', scope: 'register', form: form %} gibi sözleşme kutusunu bırak; site onay istiyorsa kutu olmadan form gönderilemez.

Kod düzenleyici#

Görünüm → Kod düzenleyici etkin temayı, kartlardaki Kodu düzenle o temayı açar.

• Solda dosyalar klasörlere göre listelenir; değiştirdiğin dosyanın yanında nokta vardır.
• Düzenlenebilenler: .liquid dosyaları, locales dosyaları ve assets/ içindeki CSS ve JS dosyaları. theme.json, görseller ve yazı tipleri düzenlenmez; yeni dosya da burada oluşturulmaz. Bunlar için ZIP kullan.
• Kaydetmek için hesabında iki adımlı doğrulama açık olmalı. Bir dosya en çok 512 KB olabilir.
• Sözdizimi hatalı bir şablon kaydedilmez; "Sözdizimi hatası: …" mesajı çıkar.
• Değişikliklerin temanın dosyalarından ayrı saklanır; tema güncellemeleri onları silmez. Orijinale döndür o dosyadaki değişikliğini kaldırır.
• Alt temada Bor'dan gelen dosyalar da listelenir. Birini kaydedersen yalnız bu temaya ait bir kopya oluşur; Bor ve diğer temalar etkilenmez.

Denemek#

• Önizle ya da herhangi bir sayfanın adresine ?preview_theme=gece eklemek temayı yalnız sana gösterir (panele girebilen bir hesapla giriş yapmış olmalısın).
• Özelleştiricideki önizleme kaydettiğin ayarları gösterir.
• Bir sayfa çizilemezse ziyaretçiler genel bir hata sayfası görür. Yetkililer aynı sayfada hatalı dosyanın adını ve hata mesajını görür.
• Tanınmayan bir filtre kullanan şablon geçersiz sayılır. Bir sayfanın çizimi 1,5 saniyeyi aşarsa yarıda kesilir; çok büyük döngülerden kaçın.
• Temayı açık ve koyu modda, dar ve geniş ekranda, uzun bir menüyle dene.

Paketlemek#

Tema klasörünü ZIP'le: theme.json ZIP'in kökünde ya da tek bir klasörün içinde olmalı. Her yeni sürümde version değerini artır ve Tema yükle (ZIP) ile kur. Sınırlar ve denetimler Tema ZIP'i makalesinde.