Tema sözleşmesi

Tema, sitenin ön yüzünü çizen pakettir. Bir modül ne gösterileceğini (blog yazısı, forum konusu), tema nasıl gösterileceğini belirler. Bu ayrım bilinçlidir: tema değiştirince modüller ve veriler değişmez, sadece görünüm değişir.

Temalar çekirdekten tamamen ayrıdır. Tema yazarı Vite, esbuild ya da düz CSS kullanabilir; CPalius yalnızca derlenmiş çıktıyı sunar ve tema varlıklarını derlemez.

Klasör düzeni

cp-content/themes/ornek-tema/
  theme.json                    manifest (zorunlu)
  screenshot.png                mağaza ve tema listesi görseli
  Resources/
    views/
      layout.html.twig          ön yüz ana şablonu (zorunlu)
      partials/header.html.twig
      partials/footer.html.twig
      blog/ forum/ page/ ...    modül sayfaları (isteğe bağlı geçersiz kılmalar)
    dist/                       derlenmiş CSS ve JS (theme.json'da bildirilir)
    translations/               temaya özgü çeviriler (isteğe bağlı)

Dizin adı kebab-case olmalıdır (ornek-tema, cpalius-website); aksi halde paket reddedilir.

theme.json

{
    "name": "Örnek Tema",
    "version": "1.0.0",
    "description": "Kısa açıklama.",
    "author": "Ben",
    "screenshot": "screenshot.png",
    "entry": {
        "css": ["dist/style.css"],
        "js":  ["dist/main.js"]
    },
    "supports": ["blog", "menu", "pages"],
    "menu_locations": {
        "main_header": "Ana başlık",
        "footer": "Alt bilgi"
    }
}

Alan	Zorunlu	Anlamı
`name`	evet	Görünen ad
`version`	evet	`MAJOR.MINOR.PATCH`; `0.0.0` ya da boş geçersizdir
`description`, `author`	hayır	Tema listesinde görünür
`screenshot`	hayır	Önizleme görseli (tema klasörüne göre yol)
`entry.css`, `entry.js`	hayır	Yayınlanan CSS/JS dosyaları. `Resources/` altına göre yazılır ve dosyalar mevcut olmalıdır
`supports`	hayır	Temanın şablon getirdiği modüller (`blog`, `forum`, `pages`, `menu`, `roadmap`…)
`menu_locations`	hayır	Temanın menü konumları (anahtar → görünen ad); bkz. Menü, widget ve görünüm

Bütün alanlar name dışında isteğe bağlı okunur: manifesti eksik bir tema listeyi bozmaz, bozuk bir theme.json ise o temayı listeden düşürür (boş sayılır), diğer temaları etkilemez.

Paket kuralları

Tema paketi (zip ya da dizin) etkinleştirilmeden önce kodla denetlenir. Şunlardan biri varsa reddedilir:

theme.json yok ya da geçersiz JSON.
name ya da version eksik.
Resources/views/layout.html.twig yok.
entry içinde bildirilen bir CSS/JS dosyası yok.
Pakette sunucu tarafı kod var: .php, .phtml, .phar, .pht uzantıları ya da .htaccess, .user.ini, web.config dosyaları.
Pakette cp-core/ ya da cp-includes/ yolu var, ya da zip girişinde .. (yol gezintisi) ya da mutlak yol var.
Kendi dosyasında App\ ad alanı bildiriyor.

Bu, bir temanın sunucuda kod çalıştıramaması demektir: yalnızca Twig, CSS, JS ve görsel taşır.

Neden PHP yok?

Tema, ön yüzü çizen sunum katmanıdır. Sunucu kodu çalıştırabilen bir tema, her modüle ve her yönetici hesabına erişebilen bir arka kapı olurdu. Mantık gerekiyorsa bir modül yazın.

Şablon çözümleme: @Theme

Modüller şablonlarını doğrudan temanın adıyla değil, ortak @Theme ad alanıyla çağırır: @Theme/layout.html.twig, @Theme/blog/show.html.twig. Çekirdek bu ad alanını şöyle kurar:

Etkin temanın Resources/views/ klasörü @Theme yolunun ilk girişidir.
Diğer kurulu temalar sırayla yedek olarak eklenir.

Sonuç: etkin tema bir şablonu tanımlamışsa o kullanılır; tanımlamamışsa yedek temalardan (genellikle varsayılan tema) gelir. Bu yüzden bir temayı kısmen yazabilirsiniz:

githeme/Resources/views/
  layout.html.twig            ← geçersiz kılındı
  partials/header.html.twig   ← geçersiz kılındı
  (diğer her şablon varsayılan temadan gelir)

Githeme teması yalnızca layout, partials/header ve portal hero şablonlarını geçersiz kılar; geri kalanı varsayılan temadan alır, bu yüzden varsayılan tema kurulu kalmalıdır.

Her temanın ayrıca kendi ad alanı vardır (@OrnekTemaTheme: dizin adının PascalCase hali + Theme), böylece bir tema başka bir temanın şablonunu açıkça çağırabilir.

Tema değiştirmek önbellek ister

Twig yolları derleme anında kurulur. Etkin temayı değiştirince önbelleğin yeniden kurulması gerekir; AACP tema ekranı bunu kayıttan sonra kendisi yapar. Elle dosya koyduysanız cache:clear çalıştırın.

Varsayılan tema ve yedek tema

cpalius-website adlı tema yedek (fallback) temadır: etkin tema ayarı (core.active_theme) geçersizse bu kullanılır. Kendi temanız ne yaparsa yapsın bu tema bozulmadan kalmalıdır; silmeyin.

Temaya özgü çeviriler

Resources/translations/messages+intl-icu.<dil>.yaml etkin temanın çevirilerini ekler. Bu dosyalar çeviri listesinin en başına eklenir; yani çekirdek ve modül çevirileri onları ezer ve bir tema çekirdek anahtarını asla değiştiremez. Temaya özgü anahtarlar için tema. gibi bir önek kullanın.

Başlangıç

Mevcut bir tema klasörünü kopyalayıp adını ve theme.json içeriğini değiştirmek en hızlı yoldur. Sonra:

Şablon yapısı ve yardımcılar: Şablonlar ve Twig yardımcıları
Menü, widget alanı, renk ve yazı tipi: Menü, widget ve görünüm
CSS ve JS: CSS derleme ve varlıklar
Yayın: Temayı yayınlamak

Klasör düzeni#

theme.json#

Paket kuralları#

Şablon çözümleme: @Theme#

Varsayılan tema ve yedek tema#

Temaya özgü çeviriler#

Başlangıç#

Klasör düzeni

theme.json

Paket kuralları

Şablon çözümleme: @Theme

Varsayılan tema ve yedek tema

Temaya özgü çeviriler

Başlangıç