Developer Guide

This document is intended for developers who want to understand, extend, or contribute to CandidTemplate.

---

1. Core Philosophy

• No string-based templating
• Operate on real DOM
• Keep API clean (pick-based)

---

2. Core Classes

Class	Responsibility
CandidTemplateAdaptor	Entry point (bind, slot, include)
CandidTemplate	Main engine (slots, loops, render)
CandidDomContext	DOM parsing + rendering
CandidElement	Fluent API (content, attribute)

---

3. Rendering Pipeline

Load DOM
   ↓
Register slots/includes
   ↓
Execute data files
   ↓
Render includes (pass 1)
   ↓
Render slots (recursive)
   ↓
Render includes (pass 2)
   ↓
Process loops
   ↓
Apply assignments
   ↓
Output HTML

---

4. Key Design Decisions

• DOM-based: avoids string parsing issues
• Two-pass include: supports nested structures
• pick() abstraction: hides internal complexity

---

5. Template Hierarchy

Base Template
   ↓
Child Template (slot)
   ↓
Nested Template

---

6. Data Flow

set() → local
get() → local + parent
share() → global (root)

---

7. Extension Points

Developers can extend:

• New selector strategies (enhance pick)
• Custom directives
• Component system
• Data store enhancements

---

8. Planned Features (Roadmap)

• Dot notation for data (user.name)
• Component system using data-component
  Example:

  <div data-component="card"></div>

• Caching layer
• Debug mode
• Strict validation mode

---

9. Coding Guidelines

• Keep methods small and focused
• Avoid side effects in rendering
• Prefer immutability where possible
• Maintain backward compatibility

---

10. Error Handling Strategy

• Throw exceptions for critical issues
• Avoid silent failures
• Provide meaningful messages

---

11. Testing Strategy

• Test rendering output
• Test nested layouts
• Test loops and includes
• Test Vue compatibility

---

12. Performance Considerations

• DOM parsing cost
• Avoid unnecessary re-renders
• Optimize loop handling

---

13. Contribution Guidelines

• Follow existing structure
• Add tests for new features
• Update documentation

---

14. Debugging Tips

• Inspect intermediate HTML
• Check slot resolution order
• Verify selector matches

---

15. Versioning Strategy

• v0.x → experimental
• v1.0 → stable API
• Follow semantic versioning

---

16. Component System (Planned)

Components will be defined using data-component attributes.

---

Example

<div data-component="card"></div>

$tpl->component('card', 'card-template');

---

Concept

• Similar to include()
• More semantic and reusable
• Supports nesting

---

Why not custom tags?