Main Definitions
Last updated
Last updated
Placed within JS script tag.
A component must be registered with the editor by the APPS.nodes.registerType() function that takes two arguments: the type of component and its definitions object.
The component type is used to identify the component in the editor. It must be equal to the APPS.nodes.registerType call value in the corresponding .js file.
A component's properties are listed in the defaults object. In the new component template, it's only name, but you can add as many as you need:
Each entry includes a default value to be used when a component is dragged onto the workspace.
After adding the property to the defaults list, add a corresponding entry to the edit dialog <script>:
It should contain an <input> element with node-input-<propertyname> in id.
The editor uses this template when the edit dialog is opened. It looks for an <input> element with an id set to node-input-<propertyname>, (or node-config-input-<propertyname> for the Configuration components). This input is then automatically populated with the current value of the property. When the edit dialog is closed, the property takes whatever value is in the input.
See more in Properties Edit Dialog.
To use this property edit the component.js function:
See the component.js chapter.
The entries of the default object must be objects and can have these attributes:
value: (any type) the default value the property takes;
required: (boolean) optional whether the property is required. If set to true, the property will be invalid if its value is null or an empty string;
validate: (function) optional a function that can be used to validate the value of the property;
type: (string) optional if this property is a pointer to a configuration node, this identifies the type of the component.
There are reserved property names that are not available to use:
single characters - x, y, z, and so on;
id, type, wires, inputs, outputs.
You can add outputs to the defaults object to configure multiple outputs of the component.
Editor attempts to validate a property with the required attribute - the property must be non-blank and non-null.
For more specific validation the validate function is used. It is called within the context of the component which means this can be used to access other properties of the component. This allows the validation to depend on other property values. While editing a component the this object reflects the current configuration of the component and not the current form element value. The validate function should try to access the property configuration element and take the this object as a fallback to achieve the right user experience.
Ready-to-use validator functions:
APPS.validators.number() - check the value is a number;
APPS.validators.regex(re) - check the value matches the provided regular expression.
In this instance, the custom property is only valid if its length is greater than the current value of the minimumLength property or the value of the minimumLength form element:
If a property doesn’t pass the validation check (by required or validate methods both) the red highlighting of the input field will appear.
It's an object with all properties the editor needs, including defaults.
category: (string) the palette category the component appears in. Notice, it’s better to create a specific category for new projects, than using an existing one.
defaults: (object) the editable properties for the component.
credentials: (object) the credential properties for the component.
inputs: (number) how many inputs the component has, either 0 or 1.
outputs: (number) how many outputs the component has. Can be 0 or more.
color: (string) the background color to use.
paletteLabel: (string|function) the label to use in the palette.
label: (string|function) the label to use in the workspace.
labelStyle: (string|function) the style to apply to the label.
inputLabels: (string|function) optional label to add on hover to the input port of a component.
outputLabels: (string|function) optional labels to add on hover to the output ports of a component.
icon: (string) the icon to use.
align: (string) the alignment of the icon and label.
button: (object) adds a button to the edge of the component.
onpaletteadd: (function) called when the component type is added to the palette.
onpaletteremove: (function) called when the component type is removed from the palette.
Sometimes there is a need to define some specific behavior for a component. For example, if a property cannot be properly edited as a simple <input> or <select>, or if the edit dialog content itself needs to have certain behaviors based on what options are selected.
A component definition can include two functions to customize the edit behavior.
oneditprepare: (function) called when the edit dialog is being built.
oneditsave: (function) called when the edit dialog is okayed.
oneditcancel: (function) called when the edit dialog is canceled.
oneditdelete: (function) called when the delete button in a configuration component’s edit dialog is pressed.
oneditresize: (function) called when the edit dialog is resized.
For example, when the Inject component is configured to repeat, it stores the configuration as a cron-like string: 1,2 * * * *. The component defines an oneditprepare function that can parse that string and present a more user-friendly UI. It also has an oneditsave function that compiles the options chosen by the user back into the corresponding cron string.
A component may define a number of credential properties that are stored separately to the main flow file and are not included in the flow export from the editor.
The entries take a single option - text or password.
In the edit template <script> regular conventions for id are used:
To use the credentials the component.js function must be updated too:
Within the runtime, a component can access its credentials using the credentials property (add to the component.js file):
Within the Apps Editor, a component has restricted access to its credentials. Any that are of type text are available under the credentials property - just as they are in the runtime. But credentials of type password are not available. Instead, a corresponding boolean property called has_<property-name> is present to indicate whether the credential has a non-blank value assigned to it.
Whilst the credential system outlined above is sufficient for most cases, in some circumstances it is necessary to store more values in credentials than just those that get provided by the user.
For example, for a component to support an OAuth workflow, it must retain server-assigned tokens that the user never sees. The Twitter component provides a good example of how this can be achieved.
