component.html
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 <script> tags.
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()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.
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.
The tag's 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 label and input.
Each row described in a
<div>tag with aform-rowclass.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 benode-config-input-<property-name>.The
<input>type can be eithertextfor string/number properties orcheckboxfor 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 editor-button class.
Note: avoid whitespace between the <button> elements as the button-group span does not currently collapse whitespace properly. This will be addressed in the future.
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 <input> tag.
HTML:
oneditprepare definition:
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 <input>.
HTML:
oneditprepare definition:
HTML:
oneditprepare definition:
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 exampleText.
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 APPS.editor.createEditor function:
The oneditsave and 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:
Use <h3> header marks for each section and <h4> for subsections.
The <dl> list of properties must have the message-properties class attribute. Each property in the list must consist of the <dt> and <dd> tag pairs.
Each <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.
Each <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 <code> tags.
For a single output, it’s enough of the <dl> list.
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. <b>,<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.
