ADR-003 - Enjin Templat

ADR-003: Enjin Templat (Smarty)> Rekod Keputusan Seni Bina untuk penggunaan enjin templat Smarty XOOPS.---

StatusDiterima - Keputusan teras sejak XOOPS 2.0Berkembang - Penghijrahan ke Smarty 4/5 dirancang untuk XOOPS 4.0---

KonteksXOOPS memerlukan penyelesaian templat yang akan:1. Asingkan pembentangan daripada logik perniagaan

2. Benarkan pereka tema bekerja tanpa pengetahuan PHP
3. Sokongan templat warisan dan termasuk
4. Sediakan caching untuk prestasi
5. Dayakan templat yang boleh disesuaikan pengguna
6. Menyokong pengantarabangsaan---

Gambarajah Keputusan

mermaid
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

---

KeputusanKami akan menggunakan Smarty sebagai enjin templat kerana:### 1. Pemisahan Kebimbangan

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

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

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

2. XOOPS PembatasXOOPS menggunakan <{ and }> dan bukannya { standard }:

Smarty
{* Standard Smarty *}
{$variable}

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

3. Hierarki Templat

mermaid
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. Storan Templat- Pangkalan Data: Templat tersuai disimpan untuk keupayaan kembali

• Sistem Fail: Templat asal dalam direktori modul
• Cache: Templat yang disusun untuk prestasi---

Konfigurasi Pintar

php
// 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'];

---

Ciri Templat Digunakan### Pembolehubah

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

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

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

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

Struktur Kawalan

Smarty
{* 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}>

Termasuk

Smarty
{* 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"}>

---

Akibat### Positif1. Mesra pereka: sintaks seperti HTML

2. Caching: Caching templat terbina dalam
3. Keselamatan: Pengasingan kod PHP
4. Fleksibiliti: Pengubah suai, fungsi, pemalam
5. Penyesuaian: Pengguna boleh mengubah suai templat
6. Komuniti: Ekosistem Smarty Besar### Negatif1. Keluk pembelajaran: Sintaks khusus Smarty
7. Overhead: Langkah penyusunan diperlukan
8. Nyahpepijat: Ralat templat boleh menjadi samar
9. Isu versi: Memecahkan perubahan antara versi### Tebatan- Pembelajaran: Dokumentasi yang komprehensif

• Prestasi: Caching agresif
• Nyahpepijat: Konsol nyahpepijat, kosongkan mesej ralat
• Versi: Lapisan keserasian dalam XOOPS---

Sejarah Versi

mermaid
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

---

Migrasi: Smarty 3 ke 4/5### Memecahkan Perubahan

Smarty
{* 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}>

Lapisan KeserasianXOOPS menyediakan lapisan keserasian untuk peralihan yang lancar:

php
// 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);
    }
}

---

Alternatif Dipertimbangkan### 1. Ranting

Kebaikan: Moden, ekosistem Symfony Kontra: Sintaks yang berbeza, usaha migrasi Keputusan: Pilihan masa depan yang mungkin untuk XOOPS 3.x### 2. Bilah (Laravel) Kebaikan: Sintaks bersih, popular Keburukan: Khusus Laravel Keputusan: Tidak sesuai untuk kegunaan sendiri### 3. Templat PHP Asli Kebaikan: Tiada keluk pembelajaran, pantas Keburukan: Risiko keselamatan, tiada pemisahan Keputusan: Ditolak kerana kebolehselenggaraan---

Keputusan Berkaitan- ADR-001: Seni Bina Modular

• ADR-002: Abstraksi Pangkalan Data---

Rujukan- Dokumentasi Smarty: https://www.Smarty.net/docs/en/

• Panduan Sistem Templat XOOPS
• Corak MVC dalam Aplikasi Web---

#XOOPS #architecture #adr #Smarty #templates #design-decision