component.js

This file describes the function that the Node.js module exports. So, this is a file that sets the component`s runtime behavior (functionality).

The function is called with an APPS argument that gives the module access to the Apps Editor`s runtime API.

The component itself is set up by the function ToUpperComponent that calls the APPS.nodes.createNode function to initialize the features shared by all components. After that, the component-specific code lives.

In this example, the component registers the listener to the ‘input’ event (on()) that rises each time a message arrives. And within the listener, it changes the message payload to uppercase: toUpperCase(), then passes the message on in the flow with the send function.

Then the ToUpperComponent function is registered with the runtime using the name "example-uppercase".

If the component has any external module dependencies, include them in the dependencies section of the config.json file.

Errors Handling

If the component gets an error during execution it should send the details to the done function.

This will allow a user to spectate errors with a catch component and build flow to handle the error.

Sending messages

If your component is for the start of a flow and reacts to an external event, it should use the send function on the Node object.

If the component responds to an input message, it should use the send function from inside the listener function.

If msg is null, no message is sent.

If the component responds to an input message, the output one should reuse the received msg rather than create a new message object to ensure the existing msg properties to be reserved for the rest of the flow.

Multiple outputs

You may pass an array of messages to send, and each message will be sent to a corresponding output.

Make sure that you described all inputs and outlets in the component.html file.

Multiple messages

The component may send multiple messages through a particular output. To do that, pass the array of massages within the array.

Closing the Component

You can register a listener on the close event to perform the component state reset - in such situations as, for example, disconnection from an external system.

If the component needs to do any asynchronous work to complete the reset, the registered listener should accept an argument which is a function to be called when all the work is complete.

If the registered listener accepts two arguments, the first will be a boolean flag that indicates whether the component is being closed because it has been fully removed, or that it is just being restarted. It will also be set to true if the component has been disabled.

Timeout behavior

The runtime waits for 15 secs a done function to be called. If it takes longer, the runtime timeouts the component, logs an error, and continues to operate.

Logging events

The following function allows logging something to the console.

The warn and error messages also will be available in the debug tub of Apps Editor.

Component Context

A component can store data within its context object.

There are three scopes of context available to a component:

• Node - only visible to the component that set the value

• Flow - visible to all components on the same flow (or tab in the editor)

• Global - visible to all components

Unlike the function component which provides predefined variables to access each of these contexts, a custom component must access these contexts for itself:

Each of these context objects has the same get/set functions described in the Writing Functions guide.

Note: Configuration components that are used by and shared by other components are by default global unless otherwise specified by the user of the component. As such it cannot be assumed that they have access to a Flow context.

Components Workspace Status

A component may have a status mark on the workspace. This is done by calling a status function.

A status object consists of three properties: fill, shape, and text.

The first two define the appearance of the status icon and the third is an optional short piece of text (under <20 characters) to display alongside the icon.

The shape property can be ring or dot.

The fill property can be: red, green, yellow, blue, or grey.

This allows for the following icons to be used:

If the status object is an empty object, {}, then the status entry is cleared from the component.

Custom Component Settings

A component may want to expose configuration options in a user’s settings.js file. The name of any setting must follow the following requirements:

• the name must be prefixed with the corresponding component type.

• the setting must use camel-case - see below for more information.

• the component must not require the user to have set it - it should have a sensible default.

For example, if the component type sample-component wanted to expose a setting called color, the setting name should be sampleComponentColour.

Within the runtime, the component can then reference the setting as APPS.setting.sampleComponentColour.

Exposing settings to the editor

In some circumstances, a component may want to expose the value of the setting to the editor. If so, the component must register the setting as part of its call to registerType:

• value specifies the default value the setting should take;

• exportable tells the runtime to make the setting available to the editor.

As with the runtime, the component can then reference the setting as APPS.settings.sampleComponentColor within the editor.

If a component attempts to register a setting that does not meet the naming requirements an error will be logged.