Expression 字段

由 JavaScript 计算得出的值，可在浏览器中，也可在服务器上计算

属性

expression 字段可用的属性，按用途分组：

属性 说明
basic
name
string / 必填 / 唯一

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.
type
string / 必填

Field type

Other attributes might only be available for some field types.

值：
expression
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
value
any
在版本 4.0.17 中添加

A fixed value (any type) for the expression

To manually populate an expression field (dictionary, array, number, boolean, string).
runLocal will be ignored.
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)

For yaml fields, the default can be any valid YAML structure (object or array). For list fields, the default must be an array of objects matching the referenced subform’s fields. Use it to pre-populate the list with existing rows on form load.
evalDefault
boolean
在版本 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 new Date().toISOString()

默认值：
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. An html field always evaluates its expression in the browser, as with runLocal: true: it never runs on the server. 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: $(fieldname) is replaced by the value of that field before the expression runs.
On the server, the predefined functions are called as fn.<name>(...), for example fn.fnTime().

tip: use the alias local (type=’expression’,runLocal=true,hide=true,output=false)
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.

默认值：
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.

默认值：
false
editable
boolean

Makes an expression editable

An expression is by default readonly.
By setting this property, you can flip the expression field to a regular text field.

默认值：
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.
Name a database of Connections > Databases : it connects with the credential of type database it names (the database type, server, database and login).
Since 7.5.0 : a name that is no database is looked up as a credential of type database, as older forms do, so they keep working unchanged.
Legacy was to pass an object (name and type) ; it still works, its name a database or a credential.
Since version 5.0.2 you can just specify the name. The type is fetched from the credential (mysql, mssql, postgres, oracle or mongodb). In case of no type set, mysql is assumed.
Additionally you can set an array of 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.
A query supports placeholders: $(fieldname) is replaced by the value of that field before the query runs.

Every $(...) value is escaped for the database engine before it is pasted into the query: single quotes are doubled, backslashes are doubled too on mysql (postgres, mssql and oracle keep them as they are), and on mongodb the value is escaped as the body of a JSON string. An object or array value is pasted as json, escaped the same way.
This protects a quoted placeholder (where name='$(name)') only: an unquoted one (limit $(n)) is pasted as plain text, so quote your placeholders.
jq
string
在版本 6.1.4 中添加

Transform database query results with jq
A valid jq expression

Apply a jq expression to transform the result of a query (with dbConfig).
jq is a post-processor applied server-side, after the query returns, to filter, map or reshape the result.
It only applies to query results: on an expression, server-side or local (runLocal: true), jq is ignored.
interaction
dependencyFn
string
在版本 4.0.0 中添加

The dependency logical function

This attribute represents the logical function between multiple dependencies.

选项：
  • and（默认）
  • or
  • nand
  • nor
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.
output
output
boolean
在版本 6.2.0 中添加

Include field value as extravar

Form fields are by default sent as extravars.
Set to false to exclude a field from the extravar output.

默认值：
true
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.

默认值：
false
security
noLog
boolean
在版本 2.2.3 中添加

Disable backend logging

Disables logging in the backend, to hide passwords for example.

默认值：
false
validation
required
boolean

Required field

Makes the field required.

默认值：
false
minLength
number

Field minimum length
Integer > 0

Forces a string-field to be at least x long.

Since 6.0.3: Supports placeholders for dynamic validation (e.g., minLength: "$(minPasswordLength)").
maxLength
number

Field maximum length
Integer > 0

Forces a string-field to be maximum x long.

Since 6.0.3: Supports placeholders for dynamic validation (e.g., maxLength: "$(maxPasswordLength)").
regex
object

A regular expression validation

Enforces a validation where the current field must match a regular expression. This field requires an object with 2 attributes:

  • expression: The regular expression
  • description: A validation message to show when the regex is not matched. (Since 6.0.3: Supports placeholders for dynamic messages)
notIn
object
在版本 2.2.4 中添加

A list validation (can not be in list)

Enforces a validation where the current field can not be one of the values in a list (referencing another field). This field requires an object with 2 attributes:

  • field: The name of the field that holds the list
  • description: A validation message to show when the validation is not met. (Since 5.0.1: Supports placeholders for dynamic messages)
in
object
在版本 2.2.4 中添加

A list validation (must be in list)

Enforces a validation where the current field must be one of the values in a list (referencing another field). This field requires an object with 2 attributes:

  • field: The name of the field that holds the list
  • description: A validation message to show when the validation is not met. (Since 5.0.1: Supports placeholders for dynamic messages)
validIf
object
在版本 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
在版本 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)
sameAs
string

An field based validation (field must be same as other field)
The name of another existing field

Enables a validation where the value of this field must match the value of another field. Perfect for password entry, for example.
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.

默认值：
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
在版本 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
在版本 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/

选项：
  • col-1
  • col-2
  • col-3
  • col-4
  • col-5
  • col-6
  • col-7
  • col-8
  • col-9
  • col-10
  • col-11
  • col-12
isHtml
boolean

Renders text as html

If an expression value has html tags (for example ), it will render the value as such. The html is sanitized before it is rendered: <script>, event handlers (onclick, onerror, …) and javascript: links are always removed. A link may carry target="_blank" to open in a new tab ; rel="noopener noreferrer" is added automatically.

默认值：
false
hide
boolean

Hides an expression field

Set to true if you want your expression hidden.

默认值：
false

示例

expression 字段示例（YAML）：

Expressions

字段定义（YAML）：

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