ADR-003 - Μηχανή προτύπων

ADR-003: Template Engine (Smarty)

Αρχείο απόφασης αρχιτεκτονικής για την υιοθέτηση από τον XOOPS της μηχανής προτύπου Smarty.

Κατάσταση

Αποδεκτό - Βασική απόφαση από το XOOPS 2.0

Εξελίσσεται - Η μετάβαση στο Smarty 4/5 έχει προγραμματιστεί για το XOOPS 4.0

Περιεχόμενο

Το XOOPS χρειαζόταν μια λύση προτύπου που θα:

Ξεχωρίστε την παρουσίαση από την επιχειρηματική λογική
Επιτρέψτε στους σχεδιαστές θεμάτων να εργαστούν χωρίς PHP γνώση
Υποστήριξη προτύπου κληρονομιάς και περιλαμβάνει
Παρέχετε προσωρινή αποθήκευση για απόδοση
Ενεργοποιήστε πρότυπα προσαρμόσιμα από το χρήστη
Υποστήριξη διεθνοποίησης

Διάγραμμα απόφασης

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. Ιεραρχία προτύπων

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. Αποθήκευση προτύπων

Βάση δεδομένων: Προσαρμοσμένα πρότυπα που αποθηκεύονται για δυνατότητα επαναφοράς
Σύστημα αρχείων: Αρχικά πρότυπα σε καταλόγους λειτουργικών μονάδων
Cache: Μεταγλωττισμένα πρότυπα για απόδοση

Smarty Configuration

// 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"}>

Συνέπειες

# Θετικό

Κατάλληλο για σχεδιαστή: σύνταξη όπως HTML
Caching: Ενσωματωμένη προσωρινή αποθήκευση προτύπων
Ασφάλεια: PHP απομόνωση κωδικού
Ευελιξία: Τροποποιητές, λειτουργίες, πρόσθετα
Προσαρμογή: Οι χρήστες μπορούν να τροποποιήσουν πρότυπα
Κοινότητα: Μεγάλο Smarty οικοσύστημα

# Αρνητικό

Καμπύλη μάθησης: Έξυπνη σύνταξη
Γενικά: Απαιτείται βήμα μεταγλώττισης
Εντοπισμός σφαλμάτων: Τα σφάλματα προτύπου μπορεί να είναι κρυπτικά
Προβλήματα έκδοσης: Διακοπή αλλαγών μεταξύ των εκδόσεων

# Μετριασμούς

Μάθηση: Ολοκληρωμένη τεκμηρίωση
Απόδοση: Επιθετική προσωρινή αποθήκευση
Εντοπισμός σφαλμάτων: Κονσόλα εντοπισμού σφαλμάτων, διαγραφή μηνυμάτων σφάλματος
Εκδόσεις: Επίπεδο συμβατότητας στο XOOPS

Ιστορικό έκδοσης

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 Πρότυπα

Πλεονεκτήματα: Χωρίς καμπύλη εκμάθησης, γρήγορα Μειονεκτήματα: Κίνδυνοι ασφάλειας, χωρίς διαχωρισμό Απόφαση: Απορρίφθηκε λόγω δυνατότητας συντήρησης