ADR-003 - template Motoru

ADR-003: template Motoru (Smarty)

XOOPS’nin Smarty template motorunu benimsemesine ilişkin Mimari Karar Kaydı.

---

Durum

Kabul edildi - XOOPS 2.0’dan bu yana temel karar

Gelişiyor - XOOPS 4.0 için Smarty 4/5’ye geçiş planlandı

---

Bağlam

XOOPS’nın aşağıdakileri sağlayacak bir şablonlama çözümüne ihtiyacı vardı:

1. Sunumu iş mantığından ayırın
2. theme tasarımcılarının PHP bilgisi olmadan çalışmasına izin verin
3. template mirasını destekleyin ve şunları içerir
4. Performans için önbelleğe alma sağlayın
5. user tarafından özelleştirilebilir şablonları etkinleştirin
6. Uluslararasılaşmayı destekleyin

---

Karar Diyagramı

flowchart TB
    subgraph "PHP Layer"
        A[Module Controller]
        B[Template Variables]
    end

    subgraph "Smarty Engine"
        C[Smarty Core]
        D[Template Compiler]
        E[Cache Manager]
    end

    subgraph "Templates"
        F[Module Templates]
        G[Theme Templates]
        H[Block Templates]
    end

    subgraph "Output"
        I[Compiled PHP]
        J[Cached HTML]
        K[Final HTML]
    end

    A --> B
    B --> C
    C --> D
    C --> E
    D --> F
    D --> G
    D --> H
    F --> I
    G --> I
    H --> I
    E --> J
    I --> K
    J --> K

---

Karar

template motoru olarak Smarty kullanacağız çünkü:

1. Endişelerin Ayrılması

// PHP (Controller) - Business logic
$items = $itemHandler->getPublishedItems();
$xoopsTpl->assign('items', $items);

// Smarty (View) - Presentation
// templates/items.tpl

{* Smarty template - No PHP logic *}
<{foreach item=item from=$items}>
    <article>
        <h2><{$item.title}></h2>
        <p><{$item.summary}></p>
    </article>
<{/foreach}>

2. XOOPS Sınırlayıcılar

XOOPS, standart { } yerine <{ ve }>’yi kullanır:

{* Standard Smarty *}
{$variable}

{* XOOPS Smarty - Avoids JavaScript conflicts *}
<{$variable}>

3. template Hiyerarşisi

graph TB
    A[Theme Master Template<br>theme.html] --> B[Module Template<br>module_index.tpl]
    A --> C[Block Templates<br>block_*.tpl]
    B --> D[Partial Templates<br>_header.tpl]
    B --> E[Partial Templates<br>_footer.tpl]

    style A fill:#f9f,stroke:#333
    style B fill:#9ff,stroke:#333
    style C fill:#ff9,stroke:#333

4. template Depolama

• database: Geri döndürme özelliği için saklanan özelleştirilmiş templates
• Dosya Sistemi: module dizinlerindeki orijinal templates
• cache: Performans için derlenmiş templates

---

Smarty Yapılandırma

// XOOPS Smarty initialization
$xoopsTpl = new XoopsTpl();

// Custom delimiters
$xoopsTpl->left_delim = '<{';
$xoopsTpl->right_delim = '}>';

// Caching
$xoopsTpl->caching = XOOPS_TEMPLATE_CACHE;
$xoopsTpl->cache_lifetime = 3600;

// Security
$xoopsTpl->security_policy = new Smarty_Security($xoopsTpl);
$xoopsTpl->security_policy->php_functions = [];
$xoopsTpl->security_policy->php_modifiers = ['escape', 'count'];

---

Kullanılan template Özellikleri

Değişkenler

{* Simple variable *}
<{$title}>

{* Object property *}
<{$item.title}>

{* With modifier *}
<{$content|truncate:200:'...'}>

{* Escaped output *}
<{$userInput|escape:'html'}>

Kontrol Yapıları

{* Conditional *}
<{if $isAdmin}>
    <a href="admin.php">Admin</a>
<{elseif $isUser}>
    <a href="profile.php">Profile</a>
<{else}>
    <a href="login.php">Login</a>
<{/if}>

{* Loop *}
<{foreach item=item from=$items name=itemloop}>
    <{$smarty.foreach.itemloop.index}>: <{$item.title}>
<{/foreach}>

İçerir

{* Include another template *}
<{include file="db:mymodule_header.tpl"}>

{* Include with variables *}
<{include file="db:mymodule_item.tpl" item=$currentItem}>

{* Include from theme *}
<{include file="file:$theme_path/partials/sidebar.tpl"}>

---

Sonuçlar

Olumlu

1. Tasarımcı dostu: HTML benzeri sözdizimi
2. Önbelleğe Alma: Yerleşik template önbelleğe alma
3. Güvenlik: PHP kod izolasyonu
4. Esneklik: Değiştiriciler, işlevler, eklentiler
5. Özelleştirme: users şablonları değiştirebilir
6. Topluluk: Büyük Smarty ekosistemi

Negatif

1. Öğrenme eğrisi: Smarty-specific sözdizimi
2. Genel gider: Derleme adımı gerekli
3. Hata ayıklama: template hataları gizemli olabilir
4. Sürüm sorunları: Sürümler arasında önemli değişiklikler

Azaltmalar

• Öğrenim: Kapsamlı belgeler
• Performans: Agresif önbelleğe alma
• Hata ayıklama: Konsolda hata ayıklama, hata mesajlarını temizleme
• Sürümler: XOOPS’deki uyumluluk katmanı

---

Sürüm Geçmişi

timeline
    title Smarty in XOOPS
    2003 : Smarty 2.x
         : Initial integration
    2013 : Smarty 3.0
         : XOOPS 2.5.5
    2020 : Smarty 3.1
         : XOOPS 2.5.10
    2026 : Smarty 4/5
         : XOOPS 4.0

---

Taşıma: Smarty 3’ten 4/5’ye

Son Değişiklikler

{* Smarty 3 - Deprecated *}
<{php}>echo date('Y');<{/php}>

{* Smarty 4+ - Use modifiers or assign from PHP *}
<{$current_year}>

{* Smarty 3 - {section} deprecated *}
<{section name=i loop=$items}>
    <{$items[i].title}>
<{/section}>

{* Smarty 4+ - Use {foreach} *}
<{foreach $items as $item}>
    <{$item.title}>
<{/foreach}>

Uyumluluk Katmanı

XOOPS sorunsuz geçişler için bir uyumluluk katmanı sağlar:

// XoopsTpl extends Smarty with compatibility methods
class XoopsTpl extends Smarty
{
    public function assign($tpl_var, $value = null)
    {
        // Handles both Smarty 3 and 4 syntax
        return parent::assign($tpl_var, $value);
    }
}

---

Alternatifler Değerlendirildi

1. Dal

Artıları: Modern, Symfony ekosistemi Eksileri: Farklı sözdizimi, geçiş çabası Karar: XOOPS 3.x için gelecekteki olası seçenek

2. Bıçak (Laravel)

Artıları: Temiz söz dizimi, popüler Eksileri: Laravel’e özgü Karar: Tek başına kullanıma uygun değil

3. Yerel PHP templates

Avantajları: Öğrenme eğrisi yok, hızlı Eksileri: Güvenlik riskleri, ayırma yok Karar: Sürdürülebilirlik nedeniyle reddedildi

---

İlgili Kararlar

• ADR-001: Modüler Mimari
• ADR-002: database Soyutlaması

---

Referanslar

• Smarty Belgeler: https://www.smarty.net/docs/en/
• XOOPS template Sistem Rehberi
• MVC Web Uygulamalarında Desen

---

#xoops #architecture #adr #smarty #templates #design-decision