node-red-contrib-file-template 1.0.1
A Node-RED node that loads HTML template content from file system, with file watching and dynamic reloading
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
- Go to Node-RED settings → Manage Palette → Install
- Search for
node-red-contrib-file-template
- Click Install
Via npm
cd ~/.node-red
npm install node-red-contrib-file-template
Manual Installation
git clone https://github.com/yourusername/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
- Drag the file-template node from the function category into your flow
- 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
- Template File: Path to your HTML template file (e.g.,
- Connect your data source to the input
- 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 contextglobal
- 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
- Check Status: Node status indicator shows current state
- View Logs: Check Node-RED debug panel for detailed error messages
- Test Data: Use a debug node to verify your input data structure
- File Permissions: Ensure Node-RED has read access to template files
Development
Local Development
git clone https://github.com/yourusername/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
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- 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