diff --git a/docs/api/ui/typedInput/index.md b/docs/api/ui/typedInput/index.md index d4de6b0b..41922194 100644 --- a/docs/api/ui/typedInput/index.md +++ b/docs/api/ui/typedInput/index.md @@ -376,6 +376,387 @@ $("#node-input-example4").typedInput({type:"fruit", types:[{
+#### Select multiple items from a list of options + +```html +` that allows the type of the value to be +chosen, including options for string, number and boolean types. + +- [Options](#options) +- [Methods](#methods) +- [Events](#events) +- [Types](#types) +- [Examples](#examples) +- [Runtime handling of typed values](#runtime-handling-of-typed-values) + +
+
+
+

Options

+ + + + +
default
types
typeField
+
+
+

Methods

+ + + + + + + + + + + +
disable
disabled
enable
hide
show
type
types
validate
value
width
+
+
+
+
+

Events

+ + +
change
+
+
+

Types

+ + +
TypeDefinition
+
+
+
+ + +### Options + +#### default + +Type: String + +If defined, sets the default type of the input if [`typeField`](#options-typeField) +is not set. + +```javascript +$(".input").typedInput({ + default: "msg" +}); +``` + +#### types + +Type: Array + +Sets the list of types the element will offer. + +The value of the option is an array of string-identifiers for the +predefined types and [TypeDefinition](#types-typedefinition) objects for any custom types. + +The predefined types are: + +identifier | description +-----------|------------ +`msg` | a `msg.` property expression +`flow` | a `flow.` property expression +`global` | a `global.` property expression +`str` | a String +`num` | a Number +`bool` | a Boolean +`json` | a valid JSON string +`bin` | a Node.js Buffer +`re` | a Regular Expression +`jsonata` | a Jsonata Expression +`date` | the current timestamp +`env` | an environment variable +`node` | a `node.` property expression +`cred` | a secure credential + +```javascript +$(".input").typedInput({ + types: ["msg","str"] +}); +``` + +#### typeField + +Type: CSS Selector + +In some circumstances it is desirable to already have an `` element to store +the type value of the typedInput. This option allows such an existing element to be +provided. As the type of the typedInput is changed, the value of the provided input +will also change. + +```javascript +$(".input").typedInput({ + typeField: ".my-type-field" +}); +``` + +When used in a Node-RED node, this value can be stored as a node property by adding +an entry for it in the node's `defaults` object. This ensures the type is saved +along with the value in the node configuration. + +```html +
+ + + +
+``` +```javascript +RED.nodes.registerType('example', { + defaults: { + myField: { value: "" }, + myFieldType: { value: "str" } + }, + ... + oneditprepare: function () { + $("#node-input-myField").typedInput({ + typeField: "#node-input-myFieldType" + }); + } +}) +``` + + + +### Methods + + + +#### disable( state ) + +*Since Node-RED 1.2.7* + +Disable the typedInput when it is currently enabled. + +The optional `state` parameter can be used to toggle the disabled/enabled state of the typedInput. If `state` is true, the element will be disabled, otherwise it will be enabled. + +```javascript +$(".input").typedInput('disable'); +``` + +#### disabled() + +*Since Node-RED 1.2.7* + +Returns: Boolean + +Gets whether the typedInput is currently disabled or not. + +```javascript +$(".input").typedInput('disabled'); +``` + +#### enable() + +*Since Node-RED 1.3.3* + +Enable the typedInput when it is currently disabled. + +```javascript +$(".input").typedInput('enable'); +``` + + + +#### hide() + +Hide the typedInput when it is currently visible. + +```javascript +$(".input").typedInput('hide'); +``` + +#### show() + +Show the typedInput when it is currently hidden. + +```javascript +$(".input").typedInput('show'); +``` + +#### type() + +Returns: String + +Gets the selected type of the typedInput. + +```javascript +var type = $(".input").typedInput('type'); +``` + +#### type( type ) + +Sets the selected type of the typedInput. + +```javascript +$(".input").typedInput('type','msg'); +``` + +#### types( types ) + +Sets the list of types offered by the typedInput. See the description of the [`types` option](#options-types). + +```javascript +$(".input").typedInput('types',['str','num']); +``` + +#### validate() + +Returns: Boolean + +Triggers a revalidation of the typedInput's type/value. This occurs automatically +whenever the type or value change, but this method allows it to be run manually. + +```javascript +var isValid = $(".input").typedInput('validate'); +``` + + + +#### value() + +Returns: String + +Gets the value of the typedInput. + +```javascript +var value = $(".input").typedInput('value'); +``` + +#### value( value ) + +Sets the value of the typedInput. + +```javascript +$(".input").typedInput('value','payload'); +``` + +#### width( width ) + +Sets the width of the typedInput. + +```javascript +$(".input").typedInput('width', '200px'); +``` + +### Events + +#### change( event, type, value ) + +Triggered when either the type or value of the input is changed. + +```javascript +$(".input").on('change', function(event, type, value) {} ); +``` + +*Note:* The `value` property was added in Node-RED 1.3 + +### Types + +#### TypeDefinition + +A `TypeDefinition` object describes a type that can be offered by a typedInput +element. + +It is an object with the following properties: + +Property | Type | Required | Description +---------|---------|----------|------------- +`value` | string | yes | The identifier for the type +`label` | string | | A label to display in the type menu +`icon` | string | | An icon to display in the type menu. This can be either an image url, or a FontAwesome 4 icon, for example `"fa fa-list"`. +`options`| array | | If the type has a fixed set of values, this is an array of string options for the value. For example, `["true","false"]` for the boolean type. +`multiple`|boolean | | If `options` is set, this can enable multiple selection of them. +`hasValue`|boolean | | Set to `false` if there is no value associated with the type. +`validate`|function| | A function to validate the value for the type. +`valueLabel` | function | | A function that generates the label for a given value. The function takes two arguments: `container` - the DOM element the label should be constructed in, and `value`. +`autoComplete` | function | | *Since 2.1.0.* If set, enable autoComplete on the input, using this function to get completion suggestions. See [autoComplete](../autoComplete) for details. This option cannot be used with `options`, `hasValue=false` or `valueLabel` + + +### Examples + +#### Built-in String, Number, Boolean types + +```html + +``` + +```javascript +$("#node-input-example1").typedInput({ + type:'str', + types:['str','num','bool'] +}) +``` + +
+ +#### Message Properties + +```html + +``` + +```javascript +$("#node-input-example2").typedInput({ + type:'msg', + types:['msg'] +}) +``` + +
+ +#### Flow/Global Context Properties + +```html + +``` + +```javascript +$("#node-input-example3").typedInput({ + type:'flow', + types:['flow','global'] +}) +``` + +
+ + +#### Select from a list of options + +```html + +``` + +```javascript +$("#node-input-example4").typedInput({type:"fruit", types:[{ + value: "fruit", + options: [ + { value: "apple", label: "Apple"}, + { value: "banana", label: "Banana"}, + { value: "cherry", label: "Cherry"}, + ] +}]}) +``` + +
+ + #### Select multiple items from a list of options ```html @@ -505,3 +886,152 @@ $(function() { }]}) }); +de-input-example5"> +``` + +```javascript +$("#node-input-example5").typedInput({type:"fruit", types:[{ + value: "fruit", + multiple: true, + options: [ + { value: "apple", label: "Apple"}, + { value: "banana", label: "Banana"}, + { value: "cherry", label: "Cherry"}, + ] +}]}) +``` + +
+ + +### Runtime handling of typed values + +Due to the way the `typedInput` enhances a regular HTML ``, its value is +stored as a string. For example, booleans are stored as `"true"` and `"false"`. + +When stored as node properties, it is necessary for the runtime part of the node +to parse the string to get the typed value. + +A utility function is provided to handle the built-in types provided by the TypedInput. + +```javascript +RED.util.evaluateNodeProperty(value, type, node, msg, callback) +``` + +Property | Type | Required | Description +---------|---------|----------|------------- +`value` | string | yes | The property to evaluate +`type` | string | yes | The type of the property +`node` | Node | yes, for certain types | The node evaluating the property +`msg` | Message Object | yes, for certain types | A message object to evaluate against +`callback` | Callback | yes, for `flow`/`global` types | A callback to receive the result + +For most types, the function can be used synchronously without providing a callback. + +```javascript +const result = RED.util.evaluateNodeProperty(value, type, node) +``` + +For `msg` type, the message object should also be provided: + +```javascript +const result = RED.util.evaluateNodeProperty(value, type, node, msg) +``` + +To handle `flow` and `global` context types, the node needs to be provided as well as +a callback function due to the asynchronous nature of context access: + +```javascript +RED.util.evaluateNodeProperty(value, type, node, msg, (err, result) => { + if (err) { + // Something went wrong accessing context + } else { + // Do something with 'result' + } +}) +``` + + + + + + + + + + + + + +#### nodeTypeFilter + +Type: Array + +Specifies which node types the TypedInput should be restricted to. +Only the types allowed for the listed nodes will appear in the dropdown. +This is useful when you want to limit the user to valid type options based on the node being edited. + +```html +
+ + + +
+ +