Magicblock Lesson 3
Nodes can be added to the workspace by either:
- Dragging them from the palette
- Using the quick-add dialog
- Importing from the library or clipboard
Nodes are joined together by wires via their ports. A node can have at most one input port and many output ports. A port may have a label that is displayed when the mouse hovers over it. A node may specify labels, for example, the Switch node shows the rule that matches the port. The labels can also be customized in the node edit dialog.
Some nodes display a status message and icon below the node. This is used to indicate the runtime state of the node — for example, the MQTT nodes indicate if they are currently connected or not.
If a node has any undeployed changes, it displays a blue circle above it. If there are errors with its configuration, it displays a red triangle.
Some nodes include a button on either its left or right edge. These allow some interaction with the node from within the editor. The Inject and Debug nodes are the only core nodes that have buttons.
Editing node configuration
A node’s configuration can be edited by double-clicking on the node, or pressing Enter when the workspace has focus. If multiple nodes are selected, the _first_ node in the selection will be edited.
The node edit dialog has two separate sections; properties and settings. The properties section shows the edit form specific to the node type being edited. The settings section shows the common settings that can be set on all nodes. This includes the custom port labels as well as the icon for the node.
Clicking on the icon shows the Node icon picker that can be used to select the icon for the node from the list of all available icons.
A Configuration (config) Node is a special type of node that holds reusable configuration that can be shared by regular nodes in a flow.
For example, the MQTT In and Out nodes use an MQTT Broker config node to represent a shared connection to an MQTT broker.
Configuration nodes are added through the edit dialog of a node that requires the config node. It will have a field to select from the available config nodes of the required type, or to add a new instance. . Image:: https://github.com/magicbitlk/Magicbit-Magicblocks.io/blob/master/Images/editor-edit-node-config-node.png?raw=true
Clicking the button next to the select box will open the edit dialog for the selected node, or add a new instance.
Nodes are wired together by pressing the left mouse button on a node’s port, dragging it to the destination node, and releasing the mouse button.
Alternatively, if the Ctrl/Command key is held down, the left-mouse button can be clicked (and released) on a node’s port and then clicked on the destination. If the Ctrl/Command key remains held and the just-wired destination node has an output port, a new wire is started from that port. This allows a set of nodes to be quickly wired together.
This can also be combined with the Quick-Add dialog that is triggered by a Ctrl/Command-Click on the workspace to quickly insert new nodes and have them already wired to previous nodes in the flow.
If a node with both an input and output port is dragged over the mid-point of a wire, the wire is drawn with a dash. If the node is then dropped, it is automatically inserted into the flow at that point.
To disconnect a wire from a port, select the wire by clicking on it, then press and hold the Shift key when the left mouse button is pressed on the port. When the mouse is then dragged, the wire disconnects from the port and can be dropped on another port. If the mouse button is released over the workspace, the wire is deleted.
If a port has multiple wires connected to it, if none of them is selected when the button is pressed with the Shift key held, all of the wires will move.
To delete a wire, first select it by clicking on it and then press the delete key.
A node is selected when it is clicked on. This will deselect anything currently selected. The Information Sidebar will update to show the node’s properties and help text for its type.
If the Ctrl or Command key is held when clicking on the node, the node will be added to the current selection (or removed if it was already selected).
If the Shift key is held when clicking on the node, it will select that node and all other nodes it is connected to.
A wire is selected when it is clicked on. Unlike nodes, it is only possible to select one wire at a time.
The lasso tool can be used to select multiple nodes. It is enabled by click-dragging on the workspace.
It cannot be used to select a wire.
Selecting all nodes
To select all nodes on the current flow, ensure the workspace has focus, and then press Ctrl/Command-a.
The editor supports the standard copy/cut/paste actions. Note, they use an internal clipboard rather than the system clipboard.
Import & Export
Flows can be imported and exported from the editor using their JSON format, making it very easy to share flows with others.
To import a flow, open the Import dialog, paste in the flow JSON, and click ‘Import’.
The ‘Import’ button will only be active if a valid JSON is pasted into the dialog.
The dialog also offers the option to import the nodes into the current flow, or to create a new flow for them.
The Export dialog can be used to copy flow JSON out of the editor.
It can export either the selected nodes, the current flow (including its tab node), or the complete flow configuration.
The Magicblocks palette includes a default set of nodes that are the basic building blocks for creating flows. This page highlights the core set you should know about.
All nodes include documentation you can see in the Info sidebar tab when you select a node.
The inject node can be used to manually trigger a flow by clicking the node’s button within the editor. It can also be used to automatically trigger flows at regular intervals.
The message sent by the Inject node can have its payload and topic properties set.
The payload can be set to a variety of different types:
- a flow or global context property value
- a String, number, boolean, Buffer or Object
- a Timestamp in milliseconds since January 1st, 1970
The Debug node can be used to display messages in the Debug sidebar within the editor.
The sidebar provides a structured view of the messages it is sent, making it easier to explore the message.
Alongside each message, the debug sidebar includes information about the time the message was received and which debug node sent it. Clicking on the source node ID will reveal that node within the workspace.
The button on the node can be used to enable or disable its output. It is recommended to disable or remove any Debug nodes that are not being used.
The node can also be configured to send all messages to the runtime log or to send short (32 characters) to the status text under the debug node.
The page on working with messages gives more information about using the Debug sidebar.
A complete guide for using the Function node is available here.
The Change node can be used to modify a message’s properties and set context properties without having to resort to a Function node.
Each node can be configured with multiple operations that are applied in order. The available operations are:
- Set — set a property. The value can be a variety of different types or can be taken from an existing message or context property.
- Change — search and replace parts of a message property.
- Move — move or rename a property.
- Delete — delete a property.
- When setting a property, the value can also be the result of a JSONata expression. JSONata is a declarative query and transformation language for JSON data.
The Switch node allows messages to be routed to different branches of a flow by evaluating a set of rules against each message.
The node is configured with the property to test — which can be either a message property or a context property.
There are four types of rule:
- Value rules are evaluated against the configured property
- Sequence rules can be used on message sequences, such as those generated by the Split node
- A JSONata Expression can be provided that will be evaluated against the whole message and will match if the expression returns a _true_ value.
- An Otherwise rule can be used to match if none of the preceding rules have matched.
The node will route a message to all outputs corresponding to matching rules. But it can also be configured to stop evaluating rules when it finds one that matches.