node-red-contrib-file-template

A Node-RED node that loads HTML template content from the filesystem with automatic file watching and reloading, perfect for managing large template files externally.

Features

• 📁 File-based Templates: Load HTML templates from the filesystem instead of embedding them in flows
• 🔄 Auto-reload: Automatically watches template files for changes and reloads content
• 🎯 Mustache Support: Built-in support for Mustache/Handlebars-style variable substitution
• 📊 Status Indicators: Visual feedback on file load status and errors
• 🛡️ Error Handling: Graceful fallback to inline templates when files are unavailable
• ⚡ Performance: Only reloads files when they actually change (based on modification time)

Installation

Via Node-RED Palette Manager

1. Go to Node-RED settings → Manage Palette → Install
2. Search for node-red-contrib-file-template
3. Click Install

Via npm

cd ~/.node-red
npm install node-red-contrib-file-template

Manual Installation

git clone https://github.com/danedens/node-red-contrib-file-template.git
cd node-red-contrib-file-template
npm install
npm link
cd ~/.node-red
npm link node-red-contrib-file-template

Usage

Basic Usage

1. Drag the file-template node from the function category into your flow
2. Double-click to configure:
   • Template File: Path to your HTML template file (e.g., templates/dashboard.html)
   • Template Data: Message property containing data for substitution (default: payload)
   • Template Format: Choose Handlebars/Mustache for variable substitution or Plain HTML
3. Connect your data source to the input
4. Connect the output to a dashboard template node or HTTP response

Configuration Options

| Option | Description | Default | |--------|-------------|---------| | Name | Node display name | (auto-generated) | | Template File | Path to template file relative to Node-RED working directory | required | | Template Format | handlebars for variable substitution, plain for static HTML | handlebars | | Template Data | Message property containing template data | payload | | Output | Set msg.template as string or parsed object | str | | Fallback Template | Optional inline template if file loading fails | (empty) |

Example Flow

[
    {
        "id": "template-node",
        "type": "file-template",
        "name": "Dashboard Template",
        "filename": "templates/TodoList.html",
        "format": "handlebars",
        "field": "payload",
        "fieldType": "msg",
        "output": "str"
    }
]

Template Syntax

Variable Substitution

Use Mustache-style syntax for variable substitution:

Template File (templates/dashboard.html):

<div class="dashboard">
    <h1>{{title}}</h1>
    <p>Welcome, {{user.name}}!</p>
    <div class="stats">
        <span>Total Items: {{stats.total}}</span>
        <span>Completed: {{stats.completed}}</span>
    </div>
</div>

Input Message:

{
    "payload": {
        "title": "My Dashboard",
        "user": {
            "name": "John Doe"
        },
        "stats": {
            "total": 25,
            "completed": 18
        }
    }
}

Output (msg.template):

<div class="dashboard">
    <h1>My Dashboard</h1>
    <p>Welcome, John Doe!</p>
    <div class="stats">
        <span>Total Items: 25</span>
        <span>Completed: 18</span>
    </div>
</div>

Nested Properties

Access nested object properties using dot notation:

<p>{{user.profile.email}}</p>
<p>{{settings.theme.primaryColor}}</p>

Default Values

If a variable doesn't exist, it will be replaced with an empty string:

<p>{{nonexistent.property}}</p>  <!-- Results in: <p></p> -->

File Watching

The node automatically watches your template files for changes:

• ✅ File Modified: Automatically reloads content when you save changes
• ⚠️ File Deleted: Shows warning status, falls back to inline template if available
• 🔄 File Restored: Automatically detects when file is restored and reloads
• 📊 Status Updates: Visual indicators show current file status

Status Indicators

| Color | Meaning | |-------|---------| | 🟢 Green | Template file loaded successfully | | 🟡 Yellow | Using fallback inline template | | 🔴 Red | Error loading file or processing template | | ⚪ Grey | No file specified or node inactive |

Output Format

The node adds the processed template to msg.template and includes metadata:

{
    "template": "<html>...</html>",  // Processed template content
    "_fileTemplate": {               // Metadata
        "filename": "templates/dashboard.html",
        "lastModified": 1640995200000,
        "length": 2048,
        "format": "handlebars"
    }
}

Use Cases

Dashboard Templates

Perfect for Node-RED dashboards with large HTML templates:

[data source] → [file-template] → [dashboard template]

Web Applications

Generate dynamic web pages:

[HTTP request] → [data processing] → [file-template] → [HTTP response]

Email Templates

Create dynamic email content:

[trigger] → [user data] → [file-template] → [email sender]

Report Generation

Generate HTML reports from data:

[database query] → [data formatting] → [file-template] → [PDF converter]

Advanced Features

Multiple Data Sources

Pull template data from different contexts:

• msg - From incoming message (default)
• flow - From flow context
• global - From global context

Error Recovery

• Automatic retry on file system errors
• Fallback to inline template content
• Graceful handling of malformed templates
• Detailed error logging

Performance Optimization

• File content caching
• Modification time checking (only reload when changed)
• Efficient file watching with chokidar
• Memory-efficient string processing

Troubleshooting

Common Issues

Template file not found

• Verify the file path is relative to Node-RED working directory
• Check file permissions
• Ensure the file exists and is readable

Variables not substituting

• Verify the input data structure matches your template variables
• Check that the data is in the specified message property (payload by default)
• Ensure you're using correct Mustache syntax: {{variable}}

File watching not working

• Some file systems (like network drives) may not support file watching
• Restart Node-RED if file watching stops working
• Check Node-RED logs for file watcher errors

Debug Tips

1. Check Status: Node status indicator shows current state
2. View Logs: Check Node-RED debug panel for detailed error messages
3. Test Data: Use a debug node to verify your input data structure
4. File Permissions: Ensure Node-RED has read access to template files

Development

Local Development

git clone https://github.com/danedens/node-red-contrib-file-template.git
cd node-red-contrib-file-template
npm install
npm link
cd ~/.node-red
npm link node-red-contrib-file-template
# Restart Node-RED

Testing

npm test

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: [email protected]

Related Nodes

• node-red-contrib-file-function - File-based function nodes
• node-red-dashboard - Dashboard templates
• node-red-node-email - Email integration