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 ```bash cd ~/.node-red npm install node-red-contrib-file-template ``` ### Manual Installation ```bash 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 ```json [ { "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`): ```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**: ```javascript { "payload": { "title": "My Dashboard", "user": { "name": "John Doe" }, "stats": { "total": 25, "completed": 18 } } } ``` **Output** (`msg.template`): ```html <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: ```html <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: ```html <p>{{nonexistent.property}}</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: ```javascript { "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 ```bash 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 ```bash 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](LICENSE) file for details. ## Support - 🐛 **Issues**: [GitHub Issues](https://github.com/danedens/node-red-contrib-file-template/issues) - 💬 **Discussions**: [GitHub Discussions](https://github.com/danedens/node-red-contrib-file-template/discussions) - 📧 **Email**: your.email@example.com ## Related Nodes - [node-red-contrib-file-function](https://flows.nodered.org/node/node-red-contrib-file-function) - File-based function nodes - [node-red-dashboard](https://flows.nodered.org/node/node-red-dashboard) - Dashboard templates - [node-red-node-email](https://flows.nodered.org/node/node-red-node-email) - Email integration