ADR-003 - เครื่องมือเทมเพลต

ADR-003: เครื่องมือเทมเพลต (ฉลาด)

บันทึกการตัดสินใจด้านสถาปัตยกรรมสำหรับการนำกลไกเทมเพลต Smarty มาใช้ของ XOOPS

---

สถานะ

ยอมรับแล้ว - การตัดสินใจหลักตั้งแต่ XOOPS 2.0

กำลังพัฒนา - การวางแผนการย้ายข้อมูลไปยัง Smarty 4/5 สำหรับ XOOPS 4.0

---

บริบท

XOOPS ต้องการโซลูชันการสร้างเทมเพลตที่จะ:

1. แยกการนำเสนอออกจากตรรกะทางธุรกิจ
2. อนุญาตให้นักออกแบบธีมทำงานโดยไม่ต้องมีความรู้ PHP
3. รองรับการสืบทอดเทมเพลตและรวมถึง
4. จัดเตรียมแคชเพื่อประสิทธิภาพ
5. เปิดใช้งานเทมเพลตที่ผู้ใช้ปรับแต่งได้
6. สนับสนุนความเป็นสากล

---

แผนภาพการตัดสินใจ

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

---

การตัดสินใจ

เราจะใช้ Smarty เป็นเครื่องมือสร้างเทมเพลตเนื่องจาก:

1. การแยกข้อกังวล

// 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 ตัวคั่น

XOOPS ใช้ <{ และ }> แทนมาตรฐาน { }:

{* Standard Smarty *}
{$variable}

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

3. ลำดับชั้นของเทมเพลต

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. การจัดเก็บเทมเพลต

• ฐานข้อมูล: เทมเพลตแบบกำหนดเองที่จัดเก็บไว้สำหรับความสามารถในการเปลี่ยนกลับ
• ระบบไฟล์: เทมเพลตดั้งเดิมในไดเร็กทอรีโมดูล
• แคช: เทมเพลตที่คอมไพล์เพื่อประสิทธิภาพ

---

การกำหนดค่าอันชาญฉลาด

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

---

คุณสมบัติเทมเพลตที่ใช้

ตัวแปร

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

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

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

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

โครงสร้างการควบคุม

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

รวมถึง

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

---

ผลที่ตามมา

คิดบวก

1. เป็นมิตรกับนักออกแบบ: HTML-like syntax
2. การแคช: การแคชเทมเพลตในตัว
3. ความปลอดภัย: PHP การแยกโค้ด
4. ความยืดหยุ่น: ตัวดัดแปลง ฟังก์ชัน ปลั๊กอิน
5. การปรับแต่ง: ผู้ใช้สามารถแก้ไขเทมเพลตได้
6. ชุมชน: ระบบนิเวศที่ชาญฉลาดขนาดใหญ่

เชิงลบ

1. เส้นโค้งการเรียนรู้: ไวยากรณ์เฉพาะของ Smarty
2. ค่าใช้จ่าย: ต้องมีขั้นตอนการคอมไพล์
3. การแก้ไขจุดบกพร่อง: ข้อผิดพลาดของเทมเพลตอาจเป็นความลับได้
4. ปัญหาเวอร์ชัน: การเปลี่ยนแปลงการเปลี่ยนแปลงระหว่างเวอร์ชันต่างๆ

การบรรเทาผลกระทบ

• การเรียนรู้: เอกสารที่ครอบคลุม
• ประสิทธิภาพ: การแคชเชิงรุก
• การดีบัก: คอนโซลดีบั๊ก ลบข้อความแสดงข้อผิดพลาด
• เวอร์ชัน: เลเยอร์ความเข้ากันได้ใน XOOPS

---

ประวัติเวอร์ชัน

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

---

การย้ายถิ่น: Smarty 3 ถึง 4/5

การเปลี่ยนแปลงที่ทำลายล้าง

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

เลเยอร์ความเข้ากันได้

XOOPS มีเลเยอร์ความเข้ากันได้สำหรับการเปลี่ยนที่ราบรื่น:

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

---

พิจารณาทางเลือกอื่นแล้ว

1. กิ่ง

ข้อดี: ทันสมัย ระบบนิเวศ Symfony ข้อเสีย: รูปแบบที่แตกต่างกัน ความพยายามในการโยกย้าย การตัดสินใจ: ตัวเลือกในอนาคตที่เป็นไปได้สำหรับ XOOPS 3.x

2. ใบมีด (Laravel)

ข้อดี: ไวยากรณ์ที่ชัดเจน เป็นที่นิยม ข้อเสีย: เฉพาะ Laravel การตัดสินใจ: ไม่เหมาะสำหรับการใช้งานแบบสแตนด์อโลน

3. เทมเพลต PHP แบบเนทีฟ

ข้อดี: ไม่ต้องเรียนรู้ รวดเร็ว ข้อเสีย: ความเสี่ยงด้านความปลอดภัย ไม่มีการแบ่งแยก การตัดสินใจ: ถูกปฏิเสธเนื่องจากการบำรุงรักษา

---

การตัดสินใจที่เกี่ยวข้อง

• ADR-001: สถาปัตยกรรมแบบโมดูลาร์
• ADR-002: ฐานข้อมูลที่เป็นนามธรรม

---

อ้างอิง

• เอกสาร Smarty: https://www.smarty.net/docs/en/
• XOOPS คู่มือระบบเทมเพลต
• MVC รูปแบบในเว็บแอปพลิเคชัน

---

#xoops #architecture #adr #smarty #templates #การออกแบบ-การตัดสินใจ