Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/danedens/node-red-contrib-file-template

A Node-RED node that loads HTML template content from file system, with file watching and dynamic reloading
https://github.com/danedens/node-red-contrib-file-template

Last synced: about 1 year ago
JSON representation

A Node-RED node that loads HTML template content from file system, with file watching and dynamic reloading

Awesome Lists containing this project

README 

          
# 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



    
{{title}}


    
Welcome, {{user.name}}!


    


        Total Items: {{stats.total}}

        Completed: {{stats.completed}}

    




```



**Input Message**:

```javascript

{

    "payload": {

        "title": "My Dashboard",

        "user": {

            "name": "John Doe"

        },

        "stats": {

            "total": 25,

            "completed": 18

        }

    }

}

```



**Output** (`msg.template`):

```html



    
My Dashboard


    
Welcome, John Doe!


    


        Total Items: 25

        Completed: 18

    




```



### Nested Properties

Access nested object properties using dot notation:

```html

{{user.profile.email}}


{{settings.theme.primaryColor}}


```



### Default Values

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

```html

{{nonexistent.property}}
  

```



## 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": "...",  // 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