# Handlebars.js Template Engine Integration ## Overview DesignFast使用Handlebars.js作为模板引擎来生成设计文档和原型HTML。 ## Installation (for development) ```bash npm install handlebars --save ``` ## Basic Usage ### Compiling Templates ```javascript const Handlebars = require('handlebars'); // Load template const templateSource = fs.readFileSync('template.hbs', 'utf8'); // Compile template const template = Handlebars.compile(templateSource); // Render with data const result = template({ projectName: 'My Project', description: 'A cool project' }); // Write output fs.writeFileSync('output.html', result, 'utf8'); ``` ## Template Locations ``` src/templates/ ├── documents/ │ ├── design-document.hbs # 设计文档模板 │ ├── requirements.hbs # 需求文档模板 │ └── design-system.hbs # 设计系统模板 ├── prototypes/ │ ├── base-prototype.hbs # 基础原型模板 │ ├── page.hbs # 页面模板 │ └── component.hbs # 组件模板 └── prompts/ ├── design-director.hbs # 代理提示模板 └── requirements-analyzer.hbs # 代理提示模板 ``` ## Custom Helpers ### Conditional Helpers ```javascript // Register custom helpers Handlebars.registerHelper('if_eq', function(a, b, options) { if (a === b) { return options.fn(this); } return options.inverse(this); }); Handlebars.registerHelper('if_gt', function(a, b, options) { if (a > b) { return options.fn(this); } return options.inverse(this); }); ``` Usage: ```handlebars {{#if_eq priority 'P1'}} 高优先级 {{/if_eq}} {{#if_gt confidence 0.8}} 高置信度 {{/if_gt}} ``` ### Format Helpers ```javascript // Date formatting Handlebars.registerHelper('formatDate', function(date) { return new Date(date).toLocaleDateString('zh-CN'); }); // Markdown to HTML Handlebars.registerHelper('markdown', function(text) { // Simple markdown conversion return text .replace(/\*\*(.*?)\*\*/g, '$1') .replace(/\*(.*?)\*/g, '$1') .replace(/\n/g, '
'); }); // Truncate text Handlebars.registerHelper('truncate', function(text, length) { if (text.length > length) { return text.substring(0, length) + '...'; } return text; }); ``` Usage: ```handlebars

创建时间: {{formatDate createdAt}}

{{{markdown description}}}

{{truncate summary 100}}

``` ### CSS Class Helpers ```javascript // Generate Tailwind classes based on data Handlebars.registerHelper('priorityClass', function(priority) { const classes = { 'P1': 'bg-red-100 text-red-800', 'P2': 'bg-yellow-100 text-yellow-800', 'P3': 'bg-green-100 text-green-800' }; return classes[priority] || 'bg-gray-100 text-gray-800'; }); Handlebars.registerHelper('statusClass', function(status) { const classes = { 'draft': 'bg-gray-100 text-gray-800', 'in-progress': 'bg-blue-100 text-blue-800', 'completed': 'bg-green-100 text-green-800', 'failed': 'bg-red-100 text-red-800' }; return classes[status] || 'bg-gray-100 text-gray-800'; }); ``` Usage: ```handlebars {{priority}} {{status}} ``` ## Template Examples ### Design Document Template ```handlebars {{projectName}} - 设计文档

{{projectName}}

{{description}}

需求列表

{{#each requirements}}

{{title}}

{{priority}}

{{{markdown description}}}

验收标准:
    {{#each acceptanceCriteria}}
  • {{this}}
    • {{/each}}
{{/each}}

设计系统

颜色方案

{{#each designSystem.colorPalette}}
{{/each}}

排版

字体: {{designSystem.typography.fontFamily}}

基础字号: {{designSystem.typography.baseFontSize}}

``` ### Component Template ```handlebars
{{#if hasHeader}}

{{headerText}}

{{/if}}
{{{content}}}
{{#if hasFooter}}
{{{footerContent}}}
{{/if}}
``` ## Partial Templates ### Register Partials ```javascript Handlebars.registerPartial('header', fs.readFileSync('partials/header.hbs', 'utf8')); Handlebars.registerPartial('footer', fs.readFileSync('partials/footer.hbs', 'utf8')); Handlebars.registerPartial('nav', fs.readFileSync('partials/nav.hbs', 'utf8')); ``` ### Use Partials ```handlebars {{title}} {{> header}} {{> nav}}
{{{content}}}
{{> footer}} ``` ## PowerShell Integration ### Compile Template Script ```powershell # compile-template.ps1 param( [string]$TemplatePath, [string]$DataPath, [string]$OutputPath ) $templateContent = Get-Content $TemplatePath -Raw $dataContent = Get-Content $DataPath -Raw | ConvertFrom-Json # Call Node.js script to compile node -e " const Handlebars = require('handlebars'); const template = Handlebars.compile(\`$templateContent\`); const result = template($($dataContent | ConvertTo-Json -Depth 10 -Compress)); console.log(result); " | Out-File -FilePath $OutputPath -Encoding UTF8 ``` ## Error Handling ```javascript // Strict mode Handlebars.compile(templateSource, { strict: true, // Throw on missing properties noEscape: false // Auto-escape HTML }); // Custom error handling try { const result = template(data); } catch (error) { console.error('Template compilation error:', error.message); // Fallback or error reporting } ``` ## Best Practices 1. **Always escape user input** (unless using {{{triple braces}}} intentionally) 2. **Use partials** for reusable components 3. **Register helpers** for complex logic 4. **Validate data** before passing to templates 5. **Cache compiled templates** for performance 6. **Use descriptive variable names** in templates ## Performance Considerations ```javascript // Pre-compile templates for production const fs = require('fs'); const Handlebars = require('handlebars'); // Compile once const compiledTemplates = {}; const templateFiles = fs.readdirSync('src/templates/prototypes'); templateFiles.forEach(file => { const source = fs.readFileSync(`src/templates/prototypes/${file}`, 'utf8'); compiledTemplates[file] = Handlebars.compile(source); }); // Reuse compiled templates const result = compiledTemplates['base-prototype.hbs'](data); ``` ## Constitutional Compliance ✅ **File-Based**: Templates stored as .hbs files ✅ **Accessibility**: Helpers for ARIA attributes and semantic HTML ✅ **Mobile-First**: Templates use responsive Tailwind classes ✅ **Performance**: Pre-compilation for < 1s rendering ✅ **Maintainability**: Partials and helpers for DRY code