This file is laying out the component’s appearance in the Apps Editor:
main component`s properties definitions;
properties edit dialog;
help text for the help tab.
Each part wrapped in distinct
Placed within JS
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
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-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.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
validate methods both) the red highlighting of the input field will appear.
It's an object with all properties the editor needs, including
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
<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 -
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.
In this dialog, a user can configure the component`s behavior. The properties available in the edit dialog are described in this section. The
<script> tag must have a
text/html type to prevent the browser from treating it like common HTML and to provide appropriate syntax highlighting in the editor.
data-template-name should be set to the component`s type otherwise the editor won't be able to show appropriate content in the edit dialog.
The edit dialog should be intuitive and consistent with other components. For example, among all components` properties should be a Name field.
The edit dialog consists of a number of rows, each has its
Each row described in a
<div> tag with a
A row usually has a
<label> (name of an editable component property) that contains an icon defined in
<i> tag with class took from Font Awesome.
The form element containing the property must have an id of
node-input-<propertyname>. In the case of Configuration nodes, the id must be
<input> type can be either
text for string/number properties or
checkbox for boolean properties. Alternatively, a
<select> element can be used if there is a restricted set of choices.
To add a button to the edit dialogue use the
<button> HTML tag with
To toggle the selected class on the active button, you will need to add code to the
oneditprepare function to handle the events.
Is done with
When the TypedInput can be set to multiple types, an extra component property is required to store information about the type. This is added to the edit dialog as a hidden
A component may contain a multi-line text editor with syntax highlighting and errors check based on Ace web code editor.
Hover the error mark to see the error description.
In the following example, the component property that we will edit is called
In your HTML, add a
<div> placeholder for the editor. This must have the
node-text-editor CSS class. You will also need to set a
height on the element.
In the component’s
oneditprepare function, the text editor is initialized using the
oneditcancel functions are also needed to get the value back from the editor when the dialog is closed and ensure the editor is properly removed from the page.
When a user selects a component help information appears in the Apps Editor help tab.
It should contain concise info about what the component does, what properties of input and output messages are available to set up.
The information in the help tab should be structured and formatted for convenient use.
The first (1) section is for general component description. It should be no more than 2 or 3
<p> tags long. The first
<p> will pop up as a tooltip when a user hovers over the component in the palette.
If a component has input, in the (2) section should be a description of its` properties and their expected types. Keep it short, if more information is needed - put it in the Details.
If the component has an output put the information about its` properties in the third (3) section. It can be multiple outputs` descriptions if needed.
The showed instance was made by this part of the HTML file:
You can add details and references if needed:
The Details section (4) provides more specific information about inputs and outputs and everything a user needs to know and that can be contained in this short form.
If much larger explanations are needed, place links to them in the References section (5).
The part of HTML used for this:
<h3> header marks for each section and
<h4> for subsections.
<dl> list of properties must have the
message-properties class attribute. Each property in the list must consist of the
<dd> tag pairs.
<dt> must contain the property name and, optionally,
<span class="property-type"> with the expected type of the property. If the property is optional, it should have the
optional class attribute.
<dd> is a description of the property.
If you describe a property outside the list of properties (in Details, for example), make sure you prefixed it with msg. and wrapped it in
For a single output, it’s enough of the
But multiple outputs will consist of
<ol> list of
<dl> lists. The
<ol> list must have the
node-ports class attribute.
Each output (aka
<dl> list) must be wrapped in
<li> tags with its short description.
No other styling tags (e.g.
<i>) should be used within the help text.
The help text should be useful for a non-experienced user. Remember that Apps Editor is made for codeless experience in the first place.