Bu kılavuz, MegaforBB forum yazılımında Twig tabanlı tema sistemini kullanarak nasıl tema geliştirebileceğinizi adım adım ve tüm teknik detaylarıyla anlatır. Çekirdek dosyalara dokunmadan yalnızca tema klasörü ve şablonlarla çalışırsınız.

İçindekiler

1. Tema Sistemine Giriş

MegaforBB'de ön yüz ve admin paneli ayrı tema sistemleriyle çalışır:

• Ön yüz temaları: Forumun ziyaretçilere görünen kısmı. templates/frontend/ altında her klasör bir temadır.
• Admin temaları: Yönetim panelinin görünümü. templates/admin/ altında tanımlanır.

Tema motoru Twig şablon dilini kullanır. Aktif tema, yönetim panelinden İçerik → Tema Yönetimi bölümünden seçilir. Sistem önce aktif temanın şablonlarına bakar; bulamadığı dosyaları default temadan alır. Bu sayede tüm sayfaları yeniden yazmadan sadece değiştirmek istediğiniz şablonları override edebilirsiniz.

2. Tema Klasör Yapısı

Ön yüz teması için standart yapı aşağıdaki gibidir. Klasör adı (slug) tema listesinde ve ayarlarda kullanılır; yalnızca harf, rakam, tire ve alt çizgi kullanın (örn. benim-temam).

templates/frontend/benim-temam/
├── theme.json          # Zorunlu — tema bilgisi (yoksa listede görünmez)
├── screenshot.png      # İsteğe bağlı — tema önizleme resmi (veya screenshot.jpg)
├── views/              # Zorunlu — Twig şablonları (.html.twig)
│   ├── base.html.twig  # Ana iskelet (header, footer, content alanı)
│   ├── index.html.twig # Forum ana sayfa içeriği
│   ├── showthread.html.twig
│   └── ...
└── assets/             # İsteğe bağlı — CSS, JS, resimler
    ├── css/
    │   ├── theme.css
    │   └── ...
    ├── js/
    │   └── theme.js
    └── images/

• views/ — Tüm sayfa şablonları burada yer alır. Sadece değiştirmek istediğiniz dosyaları kopyalayıp düzenlemeniz yeterlidir; diğer sayfalar otomatik olarak default temadan kullanılır.
• assets/ — Tema özelinde CSS, JavaScript ve resimler. Bu klasör yoksa veya bir dosya yoksa sistem default temanın aynı yoldaki dosyasına düşer. Böylece tüm asset'leri kopyalamak zorunda kalmazsınız.

3. theme.json ve Tema Tanımı

Her tema klasöründe theme.json dosyası bulunmalıdır; yoksa tema yönetim sayfasında listelenmez ve etkinleştirilemez.

Örnek theme.json:

{
    "name": "Benim Tema Adım",
    "version": "1.0.0",
    "author": "Adınız",
    "description": "Kısa tema açıklaması; liste görünümünde kullanılır."
}

Dosya UTF-8 ve geçerli JSON olmalıdır.

4. Şablon (Twig) Çalışma Mantığı

• Sistem önce aktif temanınviews/ klasörüne bakar.
• İstenen şablon orada yoksa default temanın views/ klasörüne bakılır.
• Aynı isimli şablon hem sizin temanızda hem default'ta varsa sizin temanızdaki kullanılır.

Bu sayede:

• Sadece base.html.twig ve index.html.twig ekleyerek bile yeni bir tema oluşturabilirsiniz; diğer tüm sayfalar default'tan gelir.
• İstediğiniz sayfayı tek tek kopyalayıp özelleştirebilirsiniz.

Şablon dosya isimleri, çekirdeğin kullandığı view isimleriyle aynı olmalıdır (örn. showthread.html.twig, profile.html.twig). Sayfa şablonları listesi Bölüm 6'da verilmiştir.

5. Asset (CSS, JS, Resim) Kullanımı

Tema içinde CSS, JavaScript veya resim dosyalarınıza Twig'den şu fonksiyonla link verirsiniz:

{{ theme_asset_url('css/theme.css') }}
{{ theme_asset_url('js/theme.js') }}
{{ theme_asset_url('images/logo.png') }}

• URL her zaman /theme-assets/... formatındadır.
• Önce aktif temanınassets/ klasörüne bakılır.
• Dosya orada yoksa default temanın assets/ klasöründeki aynı yol kullanılır.

Böylece kendi temanızda yalnızca değiştirdiğiniz CSS/JS dosyalarını tutabilir; diğerleri (örn. tailwind.css, theme.js) default'tan gelir.

Örnek (base.html.twig içinde):

6. Sayfa Şablonları Listesi

Aşağıdaki view isimleri, çekirdeğin kullandığı sayfa şablonlarına karşılık gelir. Şablon dosya adı {view}.html.twig veya alt dizinde alt/view.html.twig şeklindedir. Hepsini override etmek zorunda değilsiniz; sadece değiştirmek istediklerinizi temanıza ekleyin.

Genel ve giriş sayfaları:
404, index, portal, login, register, register_pending, reactivate-account, forgot_password, maintenance, security-check

Forum ve konular:
forum_display, topics/create, showthread, topic/private_topic, topic/single_post, topics/edit, topics/move, topics/merge, posts/edit, edit_history

Üyeler ve profil:
members/index, profile, member/subscriptions, member/topics, member/posts, member/likes, member/reputation, profile/edit, profile/password, profile/account, profile/preferences

Makaleler:
article/index, article/show, article/create

Mesajlar ve bildirimler:
conversations/index, conversations/show, conversations/new, notifications/index

Diğer:
search, moderation/reports, moderation/approvals, documentation/index, documentation/show, online/index, timeline/index, page, contact/index

7. Layout'a Gelen Değişkenler

Tüm layout sayfalarında (base şablonu kullanan sayfalarda) aşağıdaki değişkenler çekirdek tarafından sağlanır. İçerik şablonuna özel ek değişkenler (ör. konu sayfasında topic, posts) ilgili controller'dan gelir.

Genel

Bildirim ve mesaj

Site ve SEO

Menüler

Özellik bayrakları

İstatistik ve içerik

Hero alanı

Sidebar ve hook'lar

Tema ve script ayarları

Şablonlarda bu değişkenlere doğrudan erişirsiniz (örn. {{ pageTitle }}, {{ user.username }}). Tanımsız olabilecekler için |default(...) kullanabilirsiniz: {{ forum_logo_url|default('') }}.

8. Twig Fonksiyonları

Tema şablonları içinde aşağıdaki fonksiyonlar kullanılabilir.

URL'ler

Konu, mesaj, üye URL'leri

Çeviri ve metin

Güvenlik ve form

İçerik işleme

Diğer

Örnek kullanımlar:

{{ core_e(pageTitle) }} - {{ core_e(site_name) }}
{{ core__('common.forum') }}

 {{ core_csrf_field('login') }} ... 

9. Twig Filtreleri

Twig'in standart filtreleri (default, length, upper, lower, join, slice, date vb.) de kullanılabilir.

10. Base Şablon ve Bloklar

Tüm sayfa şablonları (index, showthread, profile vb.) base.html.twig'i extend eder ve content blokunu doldurur. Tema geliştirirken base'i override ederek tüm sayfalarda ortak header, footer ve yapıyı kontrol edersiniz.

Override edebileceğiniz bloklar:

Değişkenler (hook çıktıları):

• header_extra: Head bölümünün sonuna eklenecek HTML (örn. eklenti script'leri).
• footer_extra: Sayfa sonuna, öncesi eklenecek HTML.

Bunlar base şablonunda zaten kullanılıyorsa, kendi base override'ınızda aynı yerlere yazmak yeterlidir:

{% if header_extra is defined and header_extra is not empty %}{{ header_extra|raw }}{% endif %}
...
{% if footer_extra is defined and footer_extra is not empty %}{{ footer_extra|raw }}{% endif %}

Örnek içerik şablonu (index.html.twig):

{% extends 'base.html.twig' %}
{% block content %}
  
{{ core_e(site_name) }}
    ...
  
{% endblock %}

11. Yeni Tema Oluşturma Adımları

1. Klasör oluşturun — templates/frontend/benim-temam/ (slug'ı kendi adınızla değiştirin).
2. theme.json ekleyin — En az name alanı olacak şekilde tema adı, sürüm, yazar, açıklama yazın.
3. views/ klasörü oluşturun — İçine en azından override etmek istediğiniz şablonları koyun. Yeni başlıyorsanız base.html.twig ve index.html.twig ile başlamak yeterlidir; diğer sayfalar default'tan gelir.
4. base.html.twig — Default temadaki base.html.twig'i kopyalayıp kendi tasarımınıza göre düzenleyin. {% block content %}, header_extra, footer_extra ve menü/istatistik değişkenlerini kullanın.
5. Asset'ler (isteğe bağlı) — Sadece değiştirdiğiniz CSS/JS dosyalarını assets/css/, assets/js/ altına koyun. Diğerleri default'tan yüklenecektir. Şablonlarda theme_asset_url('css/theme.css') gibi kullanın.
6. Önizleme (isteğe bağlı) — screenshot.png veya screenshot.jpg ekleyerek tema listesinde önizleme gösterebilirsiniz.
7. Temayı etkinleştirin — Yönetim paneli → İçerik → Tema Yönetimi → Ön yüz temalarından Aktifleştir ile seçin.

Tema listesinde görünmesi için theme.json'ın geçerli ve tema klasörünün templates/frontend/ altında olması yeterlidir.

12. Admin Paneli Teması

Admin temaları templates/admin/{slug}/ altında, aynı mantıkla (views + theme.json) tanımlanır. Şablon arama sırası yine önce aktif admin teması, sonra default'tır.

• Admin paneli görünümü büyük ölçüde Tabler tabanlıdır; özel admin temasında sadece şablonları override edebilirsiniz.
• Admin tarafı için ayrı bir theme asset route'u (örn. /admin-theme-assets/...) yoktur. Özel admin CSS/JS eklemek için Sistem Ayarları içindeki Özel CSS ve Özel JS alanlarını kullanabilirsiniz; bu alanlar tüm admin sayfalarına enjekte edilir.

13. Sık Sorulan Sorular

S: Tüm şablonları kopyalamak zorunda mıyım?
Hayır. Sadece değiştirmek istediğiniz şablonları kendi tema klasörünüze kopyalayıp düzenlemeniz yeterli. Diğer sayfalar default temadan kullanılır.

S: CSS/JS dosyalarımın hepsini tema klasörüne koymalı mıyım?
Hayır. Sadece eklediğiniz veya değiştirdiğiniz dosyaları assets/ altına koyun. theme_asset_url() önce sizin temanıza, bulamazsa default temaya bakar.

S: Tema listesinde görünmüyor.
theme.json dosyasının tema klasörünün içinde, geçerli JSON ve en az "name" alanıyla olduğundan emin olun.

S: Bir sayfa boş veya hatalı görünüyor.
O sayfa için kullandığınız şablon dosya adının çekirdeğin beklediği view adıyla aynı olduğunu kontrol edin (Bölüm 6'daki listeye bakın). Eksik veya yanlış değişken kullanımı için şablonu inceleyin; tanımsız değişkenlerde |default(...) kullanın.

S: Çevirileri nasıl kullanırım?
core__('anahtar') çekirdek dil dosyalarından, lang('anahtar') uygulama dil dosyalarından çeviri döndürür. Parametreli kullanım için lang('anahtar', { 'param': deger }) kullanılabilir.

S: Eklenti view'larına nasıl referans verilir?
Eklenti şablonları @EklentiAdi/view.html.twig şeklinde namespace ile yüklenir. Tema içinden {% include '@EklentiAdi/partial.html.twig' %} gibi kullanabilirsiniz (eklenti buna izin veriyorsa).

Bu kılavuz MegaforBB tema sisteminin güncel sürümüne göre hazırlanmıştır. Güncellemeler için resmi dokümantasyonu ve forum duyurularını takip edebilirsiniz.