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

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

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

  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

Related Nodes

Node Info

Version: 1.0.1
Updated 2 days ago
License: MIT
Rating: not yet rated

Categories

Actions

Rate:

Downloads

0 in the last week

Nodes

  • file-template

Keywords

  • node-red
  • template
  • html
  • file
  • filesystem
  • watch
  • dashboard
  • mustache
  • handlebars

Maintainers