Developer Guide

This guide is intended for developers who want to understand the internals, extend the engine, or contribute to CandidTemplate. It covers architecture, design decisions, class responsibilities, rendering pipeline, and roadmap.

1. Core Philosophy

• No string templating — no {{ }}, no %placeholder%, no regex replacement
• Real DOM — every operation works on a DOMDocument tree
• Deferred binding — pick() queues changes, applied only at render()
• Clean separation — structure in HTML, binding in PHP, no mixing
• Designer-friendly — HTML files are valid, openable in any browser without PHP

2. Core Classes

3. Class Responsibility Boundary

The most important boundary is between CandidTemplate and CandidTemplateAdaptor:

4. Rendering Pipeline

CandidTemplate::render()
    │
    ├── applyDataFiles()
    │       └── execute each registered .data.php file
    │           ($this = template instance)
    │
    ├── renderIncludes()  ← pass 1
    │       └── resolve include selectors → replaceTargetWithHtml()
    │
    ├── renderSlots()
    │       └── for each registered slot:
    │               └── slot->render()  ← recursive
    │                       ├── applyDataFiles()
    │                       ├── renderIncludes()
    │                       ├── renderSlots()
    │                       ├── renderIncludes()
    │                       ├── applyLoops()
    │                       └── applyAssignments()
    │           replaceTargetWithHtml() ← wrapper removed
    │
    ├── renderIncludes()  ← pass 2 (catches slot-introduced includes)
    │
    ├── applyLoops()
    │       └── for each loop container:
    │               ├── remove original container
    │               └── for each item:
    │                       ├── renderIncludes()
    │                       ├── renderSlots()
    │                       └── applyAssignments()
    │
    ├── applyAssignments()
    │       └── apply all pick() queued bindings to DOM
    │
    └── ctx->render()
            └── serialize DOM → HTML string
                restore Vue event attributes (@click etc.)
                html_entity_decode

5. Slot Wrapper Removal

A key design decision — the data-slot wrapper element is replaced by its content, not filled. This keeps rendered HTML clean with no leftover placeholder divs.

// replaceTargetWithHtml() — used by both renderSlots() and renderIncludes()
private function replaceTargetWithHtml(DOMNode $target, CandidTemplate $tpl): void
{
    $parent = $target->parentNode;
    if (!$parent) return;

    $html = $tpl->render();
    foreach ($this->importHtml($html) as $n) {
        $parent->insertBefore($n, $target);
    }
    $parent->removeChild($target);
}

6. Assignment System

All pick() calls are queued — not applied immediately. The internal structure:

// Internal assignments map
$assignments = [
    'selector' => [
        0 => ['data' => 'plain string or array'],   // index 0
        1 => ['data' => [...]]                       // index 1 (pickAll)
    ]
];

// Array data structure (for content + attribute assignments)
[
    'content'    => 'Hello World',
    'attributes' => ['class' => 'active', 'href' => '/home']
]

Priority during applyAssignments():

1. If remove: true — element removed from DOM
2. If array with attributes — attributes applied first
3. If array with content — inner HTML replaced
4. If plain string — element itself replaced via replaceNode()

7. Selector Resolution

findNodes() converts selectors to XPath internally:

8. Data Store — Inheritance Model

root->share('appName', 'Sony News')     ← stored on root
    │
    ├── content template
    │       get('appName') ✅            ← walks parent chain to root
    │       ├── slider
    │       │       get('appName') ✅    ← inherited through chain
    │       └── sidebar
    │               get('appName') ✅
    └── footer
            get('appName') ✅

root->set('theme', 'dark')
    ├── content → get('theme') ✅        ← parent data flows down
    └── footer  → get('theme') ✅

content->set('slides', 5)
    root   → get('slides') ❌            ← child data does not flow up
    footer → get('slides') ❌
    slider → get('slides') ✅            ← only child of content

9. Script and Style Protection

DOMDocument mangles content inside <script> and <style> blocks. CandidDomContext protects them using token substitution:

Load HTML
    ↓
Replace <script>/<style> content with ___CANDID_SCRIPT_N___ tokens
    ↓
DOMDocument::loadHTML()
    ↓
Restore original content from token map
    ↓
Safe serialization via saveHTML()

10. Vue Event Compatibility

Vue event bindings use @ prefix which DOMDocument cannot parse. They are transparently protected and restored:

@click="handler"
    ↓  protectVueEvents()
data-candid-on-click="handler"
    ↓  DOMDocument parses safely
data-candid-on-click="handler"
    ↓  restoreVueEvents() in render()
@click="handler"

11. Key Design Decisions

12. Extension Points

Recommended ways to extend without modifying core:

• New selector strategies — extend selectorToXpath() with additional CSS patterns
• Custom utility functions — wrap pick() chains into reusable helpers (e.g. updateImage(), updateLink())
• Custom adaptor — extend CandidTemplateAdaptor for different file structures or frameworks
• Data file conventions — establish naming conventions for auto-resolved data files
• Hook system — use onLoad() for cross-cutting concerns (asset URL rewriting, i18n replacement)

13. Error Handling Strategy

14. Debugging

Both CandidTemplate and CandidElement provide built-in debug output:

// Full template debug — shows assignments, slots, loops, data store
echo $tpl->debugHtml();

// Specific slot debug
echo $tpl->debugHtml('slider');

// Element debug — shows pending assignments for one element
echo $tpl->pick('#newsCard')->debugHtml();

Debug output includes:

• Template name, page, basePath, parent status
• All pending assignments with selector, content, attributes
• Registered slots and their assignment state
• Registered includes
• Loop containers and item count
• Shared data store values
• Rendered HTML preview (collapsible)

15. Coding Guidelines

• All files must declare strict_types=1
• All methods must have full type hints including return types
• Keep methods small and single-purpose
• Core engine (CandidTemplate) must remain framework-agnostic — no file I/O, no HTTP, no framework dependencies
• Adaptor handles all file system concerns — never add file resolution to core
• Avoid side effects during rendering — render() should be idempotent
• New selector types belong in selectorToXpath()
• New element operations belong in CandidElement
• Maintain backward compatibility — existing selectors must continue to work

16. Testing Strategy

• Unit — test each method of CandidElement in isolation
• Integration — test full render pipeline with nested slots and loops
• Selector — test all selector types against known HTML fixtures
• Assignment — test deferred assignment application order and priority
• Data store — test parent chain inheritance for get() and share()
• Security — test data file validation rejects all forbidden superglobals
• Vue compatibility — test event attribute protection and restoration round-trip
• Script/style protection — test token substitution preserves content byte-for-byte

17. Performance Considerations

• DOMDocument parsing is the largest cost — one parse per template file per request
• getWrapperElement() caches its XPath result after first call
• CandidViewResolver caches resolved file paths — repeated slot calls for the same file hit cache
• Loop items clone DOM subtrees — keep loop container HTML lean
• getMergedAssignments() walks the parent chain iteratively — keep template nesting shallow
• Use slotIf(false) to skip file I/O entirely for conditional sections

18. Planned Features — Roadmap

19. Versioning Strategy

20. Contribution Guidelines

• Follow existing class responsibility boundaries — do not add file I/O to core
• Add declare(strict_types=1) to all new files
• Add full type hints to all new methods
• Write tests for all new features before submitting
• Update relevant documentation sections
• Do not break existing selector behaviour
• New element operations must handle pending assignments — read via getPendingAttribute() not raw DOM