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

npm install node-red-contrib-file-template

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
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 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

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

Node Info

Version: 1.0.1

Updated 2 days ago

License: MIT

Rating: not yet rated

View on npm

View on GitHub

View Scorecard 10 2

Actions

Downloads

0 in the last week

Nodes

file-template

Keywords

node-red
template
html
file
filesystem
watch
dashboard
mustache
handlebars

Maintainers

themadtinker