- Administering FlowForge
- Contributing to FlowForge
- Adding Template Settings
- API Design
- Database migrations
- FlowForge Architecture
- State Flows
- FlowForge API
- FlowForge Cloud
- Using FlowForge
- Changing the Stack
- Environment Variables
- FlowForge Concepts
- FlowForge File Nodes
- FlowForge Persistent Context
- FlowForge Project Nodes
- Instance Settings
- Migrating a Node-RED project to FlowForge
- Node-RED Tools plugin
- Shared Team Library
- Staged Deployments
- Running FlowForge
- Installing FlowForge
- Configuring FlowForge
- DNS Setup
- Docker install
- Email configuration
- First Run Setup
- FlowForge File Storage
- Install FlowForge on Kubernetes
- Local Install
- Upgrading FlowForge
# Adding Template Settings
Within FlowForge, each Node-RED instance is created from a Template. The Template defines a set of preconfigured options for the instance. This includes runtime settings - values that you would normally expect to set in your Node-RED settings.js file.
The Template also defines which of those options can be customised by individual instances.
This guide explains how to add a new Node-RED runtime option to the Template object so that it can be customised and passed through to the underlying Node-RED settings.js file.
This is reasonably straight-forward for simple boolean/string/numeric types. For other types (objects/arrays) it gets more complicated and we don't currently have good examples to follow.
For the 'simple' cases, the steps are:
- Update the Frontend
- Pick a name for the setting, add it to the list of known settings and any validation logic that is needed
- Add it to the appropriate Template section
- Update the runtime
- Add it to the known list of settings and any additional validation logic
- Update the Launcher
- Update the template used to generate settings.js with the new property
# 1. Updating the Frontend
There are a set of views in the frontend used to present and edit templates. They get used in two different ways:
- When creating/editing a template. All options are available and there is a dropdown that lets the user set the policy on the setting (which controls whether an instance is allowed to override the setting)
- When editing instance settings. All options are shown, but only lets the user modify those that the template policy allows to be changed.
This reuse of the views saves a lot of code duplication, at the cost of some complication in implementing it.
# 1.1 - Pick a name for the setting
The name should try to match its corresponding property in the Node-RED settings.js file. Some thought should be made as to organisation of the properties.
- Add the new property name to the
defaultTemplateValuesobjects. Notice the names are flat strings with
_used as a hierarchy separator... that will make more sense if you're looking at the file.
- If the value needs any sort of validation, add it to
templateValidatorsin the same file.
# 1.2 - Add it to the appropriate Template section
Current there are:
- Environment - a special case that is unlikely to get other options added
These each live in their own file under
Pick an existing setting that most closely matches the setting you want to add (ie checkbox or text input), and copy its entry to the appropriate place.
Make sure you update all of the references of the copied property name to your new property name.
# 2. Updating the Runtime
# 2.1 - Adding it to the known list
forge/db/controllers/ProjectTemplate.jsto add the new property to the list of known settings.
In that same file, update the
validateSettingsfunction with any additional validation or data cleansing needed.
# 3. Update nr-launcher
lib/runtimeSettings.jsto include the new setting in the generate settings.js file. Note that you must handle the case where the new setting is not present - either by applying a sensible default, or omitting the value.