From 8e79418074b4aac19ede7f5834e2aa6ba8048c8d Mon Sep 17 00:00:00 2001 From: GogoVega <92022724+GogoVega@users.noreply.github.com> Date: Wed, 19 Feb 2025 17:27:15 +0100 Subject: [PATCH] Update credentials and node properties --- docs/creating-nodes/credentials.md | 14 ++++----- docs/creating-nodes/properties.md | 47 +++++++++++++++++++----------- 2 files changed, 37 insertions(+), 24 deletions(-) diff --git a/docs/creating-nodes/credentials.md b/docs/creating-nodes/credentials.md index 4b27c3a1..31c4c359 100644 --- a/docs/creating-nodes/credentials.md +++ b/docs/creating-nodes/credentials.md @@ -14,12 +14,12 @@ To add credentials to a node, the following steps are taken: 1. Add a new `credentials` entry to the node's definition: ```javascript credentials: { - username: {type:"text"}, - password: {type:"password"} + username: { type: "text", required: true }, + password: { type: "password" } }, ``` - The entries take a single option - their `type` which can be either `text` or - `password`. + The entries take the same options as [node properties](./properties.md#property-definitions) + except `type` which can be either `text` or `password`. 2. Add suitable entries to the edit template for the node ```html @@ -38,10 +38,10 @@ To add credentials to a node, the following steps are taken: 3. In the node's `.js` file, the call to `RED.nodes.registerType` must be updated to include the credentials: ```javascript - RED.nodes.registerType("my-node",MyNode,{ + RED.nodes.registerType("my-node", MyNode, { credentials: { - username: {type:"text"}, - password: {type:"password"} + username: { type: "text" }, + password: { type: "password" } } }); ``` diff --git a/docs/creating-nodes/properties.md b/docs/creating-nodes/properties.md index b2ef7435..609d1c18 100644 --- a/docs/creating-nodes/properties.md +++ b/docs/creating-nodes/properties.md @@ -50,15 +50,19 @@ property called `prefix` to the node: ### Property definitions -The entries in the `defaults` object must be objects and can have the following attributes: +The entries in the `defaults` object must be objects and can have the following +attributes: -- `value` : (any type) the default value the property takes +- `value` : (any type) the default value the property takes. Do not use for + legacy properties. +- `label` : (string) *optional* the label showed in the error message if the + property is invalid. - `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. + value of the property. See [Property validation](#property-validation). - `type` : (string) *optional* if this property is a pointer to a - [configuration node](config-nodes), this identifies the type of the node. + [configuration node](config-nodes), this identifies the type of the node. ### Reserved property names @@ -66,8 +70,10 @@ There are some reserved names for properties that **must not be used**. These ar - Any single character - `x`, `y`, `z`, `d`, `g`, `l` are already used. Others are reserved for future use. - - `id`, `type`, `wires`, `inputs`, `outputs` - + - Any word with the prefix `_` - `_config`, `_def`... + - `id`, `type`, `name`, `changed`, `dirty`, `icon`, `info`, `inputs`, `outputs`, + `inputLabels`, `outputLabels`, `label`, `selected`, `users`, `valid`, + `validationErrors` and `wires`. If a node wants to allow the number of outputs it provides to be configurable then `outputs` may be included in the `defaults` array. The Function node is @@ -83,7 +89,8 @@ non-blank. If more specific validation is required, the `validate` attribute can be used to provide a function that will check the value is valid. The function is passed the -value and should return either true or false. It is called within the context of +value and should return either true or false. If the value is not valid a string +can also be returned to give a reason. It is called within the context of the node which means `this` can be used to access other properties of the node. This allows the validation to depend on other property values. While editing a node the `this` object reflects the current configuration of the @@ -101,17 +108,18 @@ Both methods - `required` attribute and `validate` attribute - are reflected by the UI in the same way. The missing configuration marker on the node is triggered and the corresponding input is red surrounded when a value is not valid or missing. - The following example shows how each of these validators can be applied. ```javascript defaults: { - minimumLength: { value:0, validate:RED.validators.number() }, - lowerCaseOnly: {value:"", validate:RED.validators.regex(/[a-z]+/) }, - custom: { value:"", validate:function(v) { - var minimumLength=$("#node-input-minimumLength").length?$("#node-input-minimumLength").val():this.minimumLength; - return v.length > minimumLength - } } + nameRequired: { value: "", required: true }, + minimumLength: { value: 0, validate: RED.validators.number() }, + lowerCaseOnly: { value: "", validate: RED.validators.regex(/[a-z]+/) }, + custom: { value: "", validate: function (val, opt) { + const minimumLength = $("#node-input-minimumLength").val() ?? this.minimumLength; + if (val.length > parseInt(minimumLength, 10)) return true; // Valid + return opt ? "The word length is too small" : false; // Not valid + } }, }, ``` @@ -119,15 +127,20 @@ Note how 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 the `validate` function takes only one argument, it **must** return a boolean. +If it takes two and the second argument exists, it can return either a boolean +or a string. + ### Property edit dialog When the edit dialog is opened, the editor populates the dialog with the edit template for the node. For each of the properties in the `defaults` array, it looks for an `` -element with an `id` set to `node-input-`, or `node-config-input-` in the case of Configuration nodes. 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. +element with an `id` set to `node-input-`, or +`node-config-input-` in the case of Configuration nodes. +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. More information about the edit dialog is available [here](edit-dialog).