Enum Formfield

A powerful dropdown field with filtering and search capabilities, perfect for long lists or categorized options with single or multiple selection.

Properties

Attribute	Comments
basic
name string / required / unique	Field name Alfanumeric + underscore + dash This attribute represents the name of the form field.
type string / required	Field type Other attributes might only be available for some field types. Choices: text textarea datetime html file number password checkbox radio enum expression table
label string	Field label Free text A friendly name/label for the field. Note: if not set, the field name is used as label, but not when type is html. Since 6.0.3: Supports placeholders for dynamic labels (e.g., Label: $(fieldname)).
placeholder string	In-field help value Free text Some form fields allow an in-field hint value. Since 6.0.3: Supports placeholders for dynamic hints (e.g., Enter password (min $(minLength) chars)).
help string	Field help message Free text Some fields require additional help information. This help message will be shown below the field. Since 6.0.3: Supports placeholders for dynamic help text (e.g., This field depends on $(fieldname)).
data
values array	A list of values To manually populate an enum field
default many	Default value The type of the value depends on the field type. Can be string,boolean, number, array or object. When using multiple, the default must be an array. When using an enum field, you can use the following special values : __auto__ : select the first __none__ : select none __all__ : select all (if multiple is true)
evalDefault boolean added in version 4.0.5	Evaluates default value A default can be treated as javascript and can thus hold expressions like '$(other_field)'.toUpperCase() or Math.PI or Date.getDate.toISOString() Default: false
expression string	A javascript expression. Valid javascript By default this javascript is evaluated on the server side and limited to predefined functions (for security). However in combination with runLocal, the evaluation is ran in the browsers sandbox and allows the full javascript power. When used in an enum field, the expression must return a flat array or array of flat objects, to make it presentable in a dropdown box. An expression supports placeholders. Read more about placeholders here. [TODO] Click here to find out more about the predefined functions. [TODO] tip : use the alias local (type=’expression’,runLocal=true,hide=true,noOutput=true) tip : use the alias local_out (type=’expression’,runLocal=true,hide=true) tip : use the alias credential (type=’expression’,runLocal=true,hide=true,asCredential=true)
runLocal boolean	Run an expression locally When running expressions, by default they are run remotely on the server. But remote expressions are limited to predefined functions. To unleash more javascript power, use this property. The code will be evaluated in the sandbox of the browser, offloading the server, saving api-calls and making it more secure. Default: false
refresh boolean|string	Allow a manual or auto refresh A query or expression is by default run once (if it doesn’t contain any dependencies). Sometimes a refresh would be handy. Set this property to true to allow a refresh, or set 5s for example to allow auto refresh. Default: false
dbConfig string, array or object	A database connection When you want to query data from a database, you will need the proper connection information. We use a credential name to lookup the connection details. Legacy was to pass an object (name and type). Since version 5.0.2 you can just specify the name of the credential. The type is fetched from the credential itself (mysql, mssql, postgres, oracle or mongodb). In case of no type set, mysql is assumed. Additionally you can set an array of credential names, to use multiple databases with a single query. The result will be a join of the results. Doubles will not be removed automatically.
query string	The query to select data from a database A valid sql query This is typically a classic SELECT statement. However, in the case of mongodb, the query is slightly different. See the examples. An expression supports placeholders. Read more about placeholders here. [TODO]
multiple boolean	Allow multiple selection When you want to select multiple items from a dropdown box, set this property to true. horizontal: true will automatically trigger multiple. Default: false
valueColumn string	The column of a selected item that needs to exported as extravar When you select an item in an enum field, by default the first column is used to send as extravar. By setting this property, you can change it to another field. This setting is ignored when outputObject is true. new in v4.0.20 : setting valueColumn to “*” will export all columns Default: first column
placeholderColumn string	The column of a selected item that is used in a placeholder When you select an item in an enum field and later on you use this field as a placeholder, by default the first column is used as a value. By setting this property you change the column to be used. NOTE : this property is somewhat out-of-date since the introduction of the dot-notation. See examples below. New in v4.0.20 : setting placeholderColumn to “*” will output the entire record, instead of a single column. Default: first column
interaction
dependencyFn string added in version 4.0.0	The dependency logical function This attribute represents the logical function between multiple dependencies. Choices: and (default) or
dependencies list / elements=object	Show/hide this field based on the values or other fields Reference to other formfields and their values Each dependency element is either an object with the following 2 attributes: name : holds the fieldname. values : a list of valid values for the referenced field. Or with the following 2 attributes: name : holds the fieldname. isValid : a boolean to check if the referenced is validated or not. Use in combination with attribute dependencyFn.
filterColumns array	The list of columns that you can filter on By default the previewColumn or first visible column is used to filter on. With this property you can filter on the columns you want.
output
noOutput boolean	Do not output as extravar Form fields are by default send as extravars. If you do not want a field to be sent as extravar, set this attribute to true. Default: false
model string or array	Extravar modelling An dot-based string notation of an object, or an array of these By default, a field is sent as a root-extravar. If you want model the output of the extravars, you can specify a dot-notation of how this field should be modelled.
asCredential boolean	Send credential as extravar Use the value of this field to search for a credential with the same name and send that credential (with user and password) hidden to the playbook as extravar. Since 4.0.16, you can use this in combination with the credentials form-property. Default: false
outputObject boolean	Output the selection of a enum-field as a full object. When selecting from an enum-field (dropdown), either the first column or the column defined in valueColumn is sent as an extravar. If you want the full selected record, use the property. New in v4.0.20 : valueColumn: “*” has the same behavior, and will output all columns Default: false
security
noLog boolean added in version 2.2.3	Disable backend logging Disables logging in the backend, to hide passwords for example. Default: false
validation
required boolean	Required field Makes the field required. Default: false
validIf object added in version 2.2.4	An field based validation (field must be true) Enforces a validation where a referencing (expression) field must be true. This field requires an object with 2 attributes: field : The name of the referencing field description : A validation message to show when the validation is not met. (Since 5.0.1: Supports placeholders for dynamic messages)
validIfNot object added in version 2.2.4	An field based validation (field must be false) Enforces a validation where a referencing (expression) field must be false. This field requires an object with 2 attributes: field : The name of the referencing field description : A validation message to show when the validation is not met. (Since 5.0.1: Supports placeholders for dynamic messages)
ignoreIncomplete boolean	Allow form submit on non-evaluated placeholders When an expression-based field has placeholders, the default form behaviour is not to allow form submit until all placeholders are resolved. When this attribute is true, the form does not wait for placeholder completion for this field. Default: false
visualization
icon string	Field icon Free fontawesome 6 icon Some formfields can hold a nice looking icon. The icon name is a free fontawesome 6 icon. You can find more information at www.fontawesome.com
group string	The field group name Free text With this attribute you can group fields together. When all fields in a group are hidden (due to dependencies), the group is also hidden.
line string added in version 4.0.3	The field line name Free text With this attribute you can group fields in a single line together. Use together with the width parameter to set the width, if not, the width is auto.
width string added in version 4.0.3	The field width A valid Bootstrap Column width With this attribute you can set the width of a field. Use together wit the line parameter to put fields on 1 line. see https://getbootstrap.com/ Choices: col-1 col-2 col-3 col-4 col-5 col-6 col-7 col-8 col-9 col-10 col-11 col-12
sticky boolean	Make a dropdown box permanently visible A enum field is by default a dropdown box. However, you can change that behavior by setting this property. The dropbox looses it reactivity and becomes a fixed table. Default: false
horizontal boolean added in version 4.0.3	Converts a dropdown box to a horizontal selector A enum field is by default a dropdown box. However, you can change that behavior by setting this property. The unselected values are on the left and the selected values on the right. This works in combiniation with sticky. PctColumns are disabled, due to the space it consumes horizontally. Default: false
columns array	The list of columns visible in the dropdown box By default all properties are show in an enum field. With this property you can choose which are visible.
pctColumns array	The list of columns that should visualized as a percentage-bar By default all properties are show with its regular value. With a percentage it can be nice to visualize it as a graphical bar. The assumption is that the value is an integer between 0 and 100.
previewColumn string	The column of the selected item(s) that is shown in the dropdown-preview When you select an item in an enum field, by default the first column is used as a preview. By setting this property you change the column to be used. Default: first column
name string / required / unique	Field name Alfanumeric + underscore + dash This attribute represents the name of the form field.
type string / required	Field type Other attributes might only be available for some field types. Choices: text textarea datetime html file number password checkbox radio enum expression table
label string	Field label Free text A friendly name/label for the field. Note: if not set, the field name is used as label, but not when type is html. Since 6.0.3: Supports placeholders for dynamic labels (e.g., Label: $(fieldname)).
placeholder string	In-field help value Free text Some form fields allow an in-field hint value. Since 6.0.3: Supports placeholders for dynamic hints (e.g., Enter password (min $(minLength) chars)).
help string	Field help message Free text Some fields require additional help information. This help message will be shown below the field. Since 6.0.3: Supports placeholders for dynamic help text (e.g., This field depends on $(fieldname)).
icon string	Field icon Free fontawesome 6 icon Some formfields can hold a nice looking icon. The icon name is a free fontawesome 6 icon. You can find more information at www.fontawesome.com
group string	The field group name Free text With this attribute you can group fields together. When all fields in a group are hidden (due to dependencies), the group is also hidden.
line string added in version 4.0.3	The field line name Free text With this attribute you can group fields in a single line together. Use together with the width parameter to set the width, if not, the width is auto.
width string added in version 4.0.3	The field width A valid Bootstrap Column width With this attribute you can set the width of a field. Use together wit the line parameter to put fields on 1 line. see https://getbootstrap.com/ Choices: col-1 col-2 col-3 col-4 col-5 col-6 col-7 col-8 col-9 col-10 col-11 col-12
dependencyFn string added in version 4.0.0	The dependency logical function This attribute represents the logical function between multiple dependencies. Choices: and (default) or
dependencies list / elements=object	Show/hide this field based on the values or other fields Reference to other formfields and their values Each dependency element is either an object with the following 2 attributes: name : holds the fieldname. values : a list of valid values for the referenced field. Or with the following 2 attributes: name : holds the fieldname. isValid : a boolean to check if the referenced is validated or not. Use in combination with attribute dependencyFn.
noLog boolean added in version 2.2.3	Disable backend logging Disables logging in the backend, to hide passwords for example. Default: false
multiple boolean	Enable multi select Enable multiple select with dropdown boxes. Default: false
values array	A list of values To manually populate an enum field
default many	Default value The type of the value depends on the field type. Can be string,boolean, number, array or object. When using multiple, the default must be an array. When using an enum field, you can use the following special values : __auto__ : select the first __none__ : select none __all__ : select all (if multiple is true)
evalDefault boolean added in version 4.0.5	Evaluates default value A default can be treated as javascript and can thus hold expressions like '$(other_field)'.toUpperCase() or Math.PI or Date.getDate.toISOString() Default: false
required boolean	Required field Makes the field required. Default: false
validIf object added in version 2.2.4	An field based validation (field must be true) Enforces a validation where a referencing (expression) field must be true. This field requires an object with 2 attributes: field : The name of the referencing field description : A validation message to show when the validation is not met. (Since 5.0.1: Supports placeholders for dynamic messages)
validIfNot object added in version 2.2.4	An field based validation (field must be false) Enforces a validation where a referencing (expression) field must be false. This field requires an object with 2 attributes: field : The name of the referencing field description : A validation message to show when the validation is not met. (Since 5.0.1: Supports placeholders for dynamic messages)
ignoreIncomplete boolean	Allow form submit on non-evaluated placeholders When an expression-based field has placeholders, the default form behaviour is not to allow form submit until all placeholders are resolved. When this attribute is true, the form does not wait for placeholder completion for this field. Default: false
noOutput boolean	Do not output as extravar Form fields are by default send as extravars. If you do not want a field to be sent as extravar, set this attribute to true. Default: false
model string or array	Extravar modelling An dot-based string notation of an object, or an array of these By default, a field is sent as a root-extravar. If you want model the output of the extravars, you can specify a dot-notation of how this field should be modelled.
asCredential boolean	Send credential as extravar Use the value of this field to search for a credential with the same name and send that credential (with user and password) hidden to the playbook as extravar. Since 4.0.16, you can use this in combination with the credentials form-property. Default: false
outputObject boolean	Output the selection of a enum-field as a full object. When selecting from an enum-field (dropdown), either the first column or the column defined in valueColumn is sent as an extravar. If you want the full selected record, use the property. New in v4.0.20 : valueColumn: “*” has the same behavior, and will output all columns Default: false
expression string	A javascript expression. Valid javascript By default this javascript is evaluated on the server side and limited to predefined functions (for security). However in combination with runLocal, the evaluation is ran in the browsers sandbox and allows the full javascript power. When used in an enum field, the expression must return a flat array or array of flat objects, to make it presentable in a dropdown box. An expression supports placeholders. Read more about placeholders here. [TODO] Click here to find out more about the predefined functions. [TODO] tip : use the alias local (type=’expression’,runLocal=true,hide=true,noOutput=true) tip : use the alias local_out (type=’expression’,runLocal=true,hide=true) tip : use the alias credential (type=’expression’,runLocal=true,hide=true,asCredential=true)
runLocal boolean	Run an expression locally When running expressions, by default they are run remotely on the server. But remote expressions are limited to predefined functions. To unleash more javascript power, use this property. The code will be evaluated in the sandbox of the browser, offloading the server, saving api-calls and making it more secure. Default: false
refresh boolean|string	Allow a manual or auto refresh A query or expression is by default run once (if it doesn’t contain any dependencies). Sometimes a refresh would be handy. Set this property to true to allow a refresh, or set 5s for example to allow auto refresh. Default: false
dbConfig string, array or object	A database connection When you want to query data from a database, you will need the proper connection information. We use a credential name to lookup the connection details. Legacy was to pass an object (name and type). Since version 5.0.2 you can just specify the name of the credential. The type is fetched from the credential itself (mysql, mssql, postgres, oracle or mongodb). In case of no type set, mysql is assumed. Additionally you can set an array of credential names, to use multiple databases with a single query. The result will be a join of the results. Doubles will not be removed automatically.
query string	The query to select data from a database A valid sql query This is typically a classic SELECT statement. However, in the case of mongodb, the query is slightly different. See the examples. An expression supports placeholders. Read more about placeholders here. [TODO]
multiple boolean	Allow multiple selection When you want to select multiple items from a dropdown box, set this property to true. horizontal: true will automatically trigger multiple. Default: false
sticky boolean	Make a dropdown box permanently visible A enum field is by default a dropdown box. However, you can change that behavior by setting this property. The dropbox looses it reactivity and becomes a fixed table. Default: false
horizontal boolean added in version 4.0.3	Converts a dropdown box to a horizontal selector A enum field is by default a dropdown box. However, you can change that behavior by setting this property. The unselected values are on the left and the selected values on the right. This works in combiniation with sticky. PctColumns are disabled, due to the space it consumes horizontally. Default: false
columns array	The list of columns visible in the dropdown box By default all properties are show in an enum field. With this property you can choose which are visible.
pctColumns array	The list of columns that should visualized as a percentage-bar By default all properties are show with its regular value. With a percentage it can be nice to visualize it as a graphical bar. The assumption is that the value is an integer between 0 and 100.
filterColumns array	The list of columns that you can filter on By default the previewColumn or first visible column is used to filter on. With this property you can filter on the columns you want.
valueColumn string	The column of a selected item that needs to exported as extravar When you select an item in an enum field, by default the first column is used to send as extravar. By setting this property, you can change it to another field. This setting is ignored when outputObject is true. new in v4.0.20 : setting valueColumn to “*” will export all columns Default: first column
placeholderColumn string	The column of a selected item that is used in a placeholder When you select an item in an enum field and later on you use this field as a placeholder, by default the first column is used as a value. By setting this property you change the column to be used. NOTE : this property is somewhat out-of-date since the introduction of the dot-notation. See examples below. New in v4.0.20 : setting placeholderColumn to “*” will output the entire record, instead of a single column. Default: first column
previewColumn string	The column of the selected item(s) that is shown in the dropdown-preview When you select an item in an enum field, by default the first column is used as a preview. By setting this property you change the column to be used. Default: first column

Examples

Queries

since queries are so diverse, there is a separate section on queries with examples.