frodovdr/node-red
1
0
Fork 0
mirror of https://github.com/node-red/node-red.git synced 2023-10-10 13:36:53 +02:00
Code Issues Releases Wiki Activity
Page: Design: Subflow Enhancements
Pages
API Reference Architecture Overview Architecture: Cluster Multi Process Contribution Process Dashboard layout tool Definitions Deprecated: Message properties overriding set node properties Design Notes Design: dynamic palette Design: API Token management Design: CLI tool to produce a node skeleton Design: Concurrent editing Design: Custom Node admin route handling Design: Dynamic MQTT node Design: Dynamic node's icon Design: Editable port labels Design: Editor Events Design: Editor Themes Design: Editor UI Customisation Design: Encryption of credentials Design: Enhancements to Split Join nodes Design: Flow Linter Design: Flow Manipulation API Design: Flow file format v2 Design: Function Library node Design: Library Sidebar Design: Logging Framework Design: Node Generator Design: Node Messaging API Design: Node blacklist whitelist function Design: Node module lifecycle Design: Node settings Design: Palette Management UI Design: Persistable Context Design: Platform Specific Nodes Design: Projects Design: Runnable Project Design: Runtime Editor Split Design: Runtime Events Design: Runtime extension points Design: Subflow Enhancements Design: Subflow Instance properties Design: Subflow Node modules Design: Usage telemetry Design: Using environment variables Design: Version Control Design: adminAuth User Management Design: external file for function and templates nodes Design: i18n de Design: i18n Design: msg.parts description of usage Design: multiuser Design: subflows vNext Design: subflows Design:Shared Global Context Editor Mouse Actions Editor Runtime API Flow Format Flow testing Home Input node feature definitions Live runtime information Node Design Guidelines Node documentation guide Node msg Conventions Output node feature definitions Pluggable Message Routing Query node feature definitions ReadMe Raspberry Pi Advanced Runtime Editor Comms protocol Technical Interchange 2018 04 13 Technical Interchange Meetings Testing UI testing Watch node feature definitions Web Nodes outline adminAuth Credential Authentication dynamic palette join in auto mode npm installable nodes
0 Design: Subflow Enhancements
Nick O'Leary edited this page 2019-02-27 14:37:32 +00:00
Table of Contents

Parts of this design have now moved to the node-red/designs repository:

The parts of this design note that have already been merged for 0.20 have been left here.

This is a work in progress.

SUBFLOW Customization

This Design Node describes proposal on SUBFLOW customization enhancements to Node-RED.

Background

By recent enhancements to Node-RED, functionalities similar to Nodes can be implemented with Subflow using GUI. Following table show comparison of features between Nodes and SUBFLOWs:

No. Item Node SUBFLOW
1 Icon Any Picture,
Icon Font (via GUI)		 Icon Font (via GUI)
2 Info Text HTML,
Markdown (via GUI)		 Markdown (via GUI)
3 Logic JavaScript Flow (via GUI)
4 Parameter
Settings UI		 HTML None
5 Color Any Color None
6 Category Any Category Any Category (via GUI)

According to this table, by adding feature to specify parameter settings UI and Color, SUBFLOW can describe similar functionalities to normal Node using GUI.

This enhancement will greatly enhances programmability and reusability of Node-RED nodes.

Since adding interface to specify SUBFLOW color is trivial one, we discuss enhancement of SUBFLOW UI definition in this document.

SUBFLOW Environment Variable

; changed by H.N. 01/22/2019

Currently, environment variable in Node-RED is stored within single global name space and can only hold string values. In order to store subflow parameters, environment variable will be enhanced to be defined for each SUBFLOW instance. It will also be enhanced to be able to store general JavaScript objects.

When accessing environment variable value, environment variable definition of enclosing context up to top-level flow are looked up if not found. If no definition is found, undefined is returned.

env-var

Subflow environment variable can be defined by following methods:

  • Environment variables input list in property tab of Subflow settings panel,
  • User defined UI for subflow (described in the next section).

Defining environment variable in subflow property tab

Environment variables can be defined as key-value pair in property tab of Subflow-instance/template settings panel.

env-sf-inst

Type of a value in the list can be defined using TypedInput interface.

Subflow-instance environment variables precedes over subflow-template environment variables.

When a environment variable is defined in the list following three variables are defined.

name value
name input value represented by specified type
name_type type of input value
name_info JavaScript object that represents input information. It contains following properties:
- name: name of field
- label: ""
- value: input value
- type: type of input value
- target_type: “env var”
- target: name

UI definition

Next figure shows a process to define new parameter settings UI for a SUBFLOW.

Subflow-dev-process

UI Edit Panel is added to SUBFLOW Template Edit Panel of a SUBFLOW. Simple parameter setting UI for the SUBFLOW can be created using this panel by adding UI items on UI items list. Created UI can be previewed by clicking preview button or selecting preview tab.

Parameter settings UI of a SUBFLOW can be show by double clicking the SUBFLOW (and selecting parameter edit tab) on flow edit pane. SUBFLOW customization parameters can be set using this UI.

SUBFLOW Parameter Representation

Each UI item defined in UI Edit Panel can store the defined value into two kinds of targets: SUBFLOW environment variable and node property within the SUBFLOW.

Edit UI Panel

Edit UI Panel have add button at the bottom. By clicking this button, new UI item can be added to UI items list. UI items are shown from top to bottom in generated parameter settings UI. Order of UI items can be rearragned by dragging an item in the list.

UI-edit-panel

UI item definition consists of following sub-items:

UI-element

  • name - name of defined UI item. Used to access input value.

  • label - label of defined UI item. HTML tags can be used in label definition. For internationalization (i18n) of label text, locale of the text can be selected from menu.

    label field appearance is as follows:

    field-label

  • type - type of defined item. Currently following types are supported:

    type input item description
    simple type - initial value simple input for basic types supported by TypedInput such as string, number, etc.
    any - selection of candidate types
    - initial value    		 set of basic types supported by TypedInput
    label - only show label
    menu - menu items
    - initial value    		 select one item from list of menu items
    checkbox - label
    - initial value    		 checkbox to select from items
    spinner - initial value spinner input of numeric value
    node - target node select from set of nodes
    node property - target property of a node select from set of node properties
    ui_group - group of UI widget select group of Node-RED Dashboard
    ui_size - size of UI widget set size of Node-RED Dashboard UI Widget

    type field appearance is as follows:

    field-type

  • tgt. type - type of target to which input value is stored. Curtly supported tgt. types are as follow:

    name description
    env var environment variable
    node property property of a specified node in SUBFLOW

    There are some kind of UI input types of nodes in SUBFLOW that can not be specified using environment variable. For such input type, we allow directly specifying property of nodes from node settings UI.

    tgt. type field appearance is as follows:

    field-tgt

  • target - specification of target for selected tgt. type.

    If tgt. type is env var, target field appearance is as follows:

    field-target-envvar

    If tgt. type is node property, target field appearance is as follows:

    field-target-target

  • type specific inputs - input items specific to each UI item type.

UI Input Elements

This section describes UI definition, UI appearance, and environment variable defined by UI element for each UI input element type.

Simple Type

  • UI Definition

    UI-def-simple

    • initial value accepts a value of type specified by field.

  • UI Appearance

    UI-app-simple

  • Environment Variable

    name value
    name input value represented by specified type
    name_type type of input value
    name_info JavaScript object that represents input information. It contains following properties:
    - name: name of field
    - label: label of field
    - value: input value
    - type: type of UI element
    - target_type: “env var” or “node property”
    - target: name or [id, name]

any

  • UI Definition

    UI-def-any

    • A set of candidate types can be selected by checkbox.
    • Initial value can be defined using initial value field.

  • UI Appearance

    UI-app-any

    • A value can be input using TypedInput interface.

  • Environment Variable

    same as simple type

label

  • UI Definition

    UI-def-label

  • UI Appearance

    UI-app-label

  • Environment Variable

    name value
    name_type “label”
    name_info JavaScript object that represents input information. It contains following properties:
    - name: name of field
    - label: label of field
    - type: “label"

menu

  • UI Definition

    UI-def-menu

    • menu items are defined by adding item label (with locale) and its value pair.
    • initial value of menu can be defined using initial value menu.

  • UI Appearance

    UI-app-menu

  • Environment Variable

    name value
    name value of selected item
    name_type "menu"
    name_info JavaScript object that represents input information. It contains following properties:
    - name: name of field
    - label: label of field
    - value: value of selected item
    - type: “menu"
    - target_type: “env var”, “node”, or “node property”
    - target: name or [id, name]
    - items: list of objects with following properties:
    + labels: list of objects with following properties:
    * lang: locale of label
    * label: label
    + value: value of item

checkbox

  • UI Definition

    UI-def-checkbox

    • initial value (true or false) can be defined by initial value field.

  • UI Appearance

    UI-app-checkbox

    • item label is shown after check box.

  • Environment Variable

    name value
    name true or false
    name_type “checkbox”
    name_info JavaScript object that represents input information. It contains following properties:
    - name: name of field
    - label: label of field
    - value: true or false
    - type: “checkbox"
    - target_type: “env var” or “node property”
    - target: name or [id, name]

spinner

  • UI Definition

    UI-def-spinner

    • initial value can be defined by initial value field.

  • UI Appearance

    UI-app-spinner

  • Environment Variable

    name value
    name numeric value
    name_type “spinner”
    name_info JavaScript object that represents input information. It contains following properties:
    - name: name of field
    - label: label of field
    - value: numeric value
    - type: “spinner"
    - target_type: “env var” or “node property”
    - target: name or [id, name]

node

  • UI Definition

    UI-def-node

    • filter specifies a regular expression that filters node type.

  • UI Appearance

    UI-app-node

  • environment variable

    name node ID
    name_type "node"
    name_info JavaScript object that represents input information. It contains following properties:
    - name: name of field
    - label: label of field
    - value: numeric value
    - type: “node"
    - target_type: “env var” or “node property”
    - target: name or [id, name]

node property

T.B.D. (will be implemented as an extension of TypedInput interface)

Subflow Instantiation

A SUBFLOW template can be customized as new SUBFLOW template to be used for specific purpose/domain. It can be accomplished by selecting Customize button after modifying existing SUBFLOW template.

Subflow-Instantiation

Exporting SUBFLOW as Node

By adding customization capability of Subflow, Subflow can define similar functionality to normal Node using Node-RED editor GUI.

No. Item Node SUBFLOW
1 Icon Any Picture,
Icon Font (via GUI)		 Icon Font (via GUI)
2 Info Text HTML,
Markdown (via GUI)		 Markdown (via GUI)
3 Logic JavaScript Flow (via GUI)
4 Parameter
Settings UI		 HTML None → via GUI
5 Color Any Color None → via GUI
6 Category Any Category Any Category (via GUI)

This enables even novice IT users creating, modifying, and sharing nodes without much efforts (e.g. no use of command-line tools or JavaScript/HTML coding) using SUBFLOW.

Subflow-export

Exporting SUBFLOW Node

Node can be exported as JSON code or converted to a Node.

Subflow-export-UI

By clicking Export button on Subflow Setting Panel of Subflow template, Subflow Export Panel is shown.

In this panel, new node information such as node name, version, etc. can be specified. There is As JSON check box on this panel. If this is checked, JSON export panel is shown. Otherwise, new node is installed on editor palette.

New node created from SUBFLOW is sealed. Thus, its internal flow or UI definition can not be edited.

Importing SUBFLOW Node

Node represented as JSON data can be imported in Node-RED environment from palette management UI.

Subflow-import-UI

There is Install(JSON) button on top of the panel. After importing JSON, new node is installed on editor palette.

Other Runtime Enhancements

SUBFLOW Context

In a SUBFLOW, flow context of enclosing context (flow or subflow) can be accessed using $parent property of flow context. $parent can be used multiple times up to top-level flow. If $parent is applied to top-level flow, undefined value is returned.

Subflow-context-parent

The result of keys function on flow context do not contain $parent property.

Other Topics

  • Implementation of Generic Nodes

    Enhancement to Function Node and ui_template Node should be considered to allow implementation of complex features as Subflow. This includes use of external JavaScript libraries, code execution without VM module, etc. Support for invoking external services using Swagger definition should also considered.

  • Library Enhancements

    T.B.D.

  • Node JSON Format

    T.B.D.

  • UI Setting Meta-data Representation

    T.B.D.

Implementation Plan

  • Phase1: Environment Variable, and Scope enhancements.
  • Phase2: UI definition, Environment Variable, and Scope enhancements.
  • Phase3: Exporting as Node
  • Phase4: Subflow Instantiation