Initializing help system before first use

# vdl-field

Represents an input field in a form. The input type is derived from the data type of the entity but can be overridden via the "type" attribute. Validation is performed on initialization and on value change and the input is highlighted with a red border when validation fails. The input field can be used without binding to an entity or parameter, in which case the "value" attribute can be used to supply an initial value.

since 4.8

### Example

    <vdl-action-group name="displayValue">
      <vdl-action-message text="=value"></vdl-action-message>
    </vdl-action-group>

    <vdl-var name="selectedFilter" value="">
    <vdl-action-group name="updateFilter">
      <vdl-action-set-var var="selectedFilter"></vdl-action-set-var>
    </vdl-action-group>

    <vdl-form>
      <!-- Field bound to a Scalar model entity -->
      <vdl-field entity="MyScalar"></vdl-field>
      <!-- Field not bound to the model and no initial value -->
      <vdl-field vdl-event="change: actions.displayValue"></vdl-field>
      <!-- Field not bound to the model with an initial value from an expression -->
      <vdl-field label="Select filter" value="=scenario.entities.SelectedOrigin" options-set="Countries" vdl-event="change: actions.updateFilter"></vdl-field>
    </vdl-form>

### Attributes

checked-value | For checkboxes, the value to use to indicate it should be checked. | since 4.8 |  |
enabled | A boolean expression or a string ("true"/"false") which indicates whether the field is enabled. | since 4.8 | accepts expression |
entity | Model entity to bind to. This can be a scalar or array type (as long as you also provide the indices to bind to a single array element). When bound to an entity the field will take it's value from that entity and update the field whenever the entity changes remotely. Any changes a user makes to the field will be validated and saved to the model. | since 4.8 |  |
indices | The index tuple to use if the entity bound to this field is an array. | since 4.8 | accepts expression |
inline | Whether to use inline layout for the field. | since 4.8 |  |
label | Custom label for the input. If not specified then the entity alias or parameter name will be used. | since 4.8 | accepts expression |
label-size | The number of column units for the label. | since 4.8 |  |
multiple | Set this to "true" to enable multiple select list. Multiple select lists can only be used with unbound fields. | since 4.8 |  |
options | An expression that results in an array of values to use for the select options or a map object of values (in the form [{value: 'underlying_value', label: 'Display Text'}]) to display text. This will transform the input into a select box. Note, if the Field is bound to an Array entity, an empty string value in the options will result in the array element being deleted when they user selects it. | since 4.8 | requires expression |
options-include-empty | Allow a string entity to be cleared or an array element to be removed using the select input. Setting this to true will add a blank item to the top of the select list. Can only be used on a string entity, an array entity or a parameter. Cannot be used on a radio input type. Note, if the Field is bound to an Array entity, an empty value in the options will result in the array element being deleted when they user selects it. | since 4.8 |  |
options-set | Name of a set entity (or index entity from Python) from the model to use for select options. This will transform the input into a select box. Note, if the Field is bound to an Array entity, an empty string value in the options will result in the array element being deleted when they user selects it. | since 4.8 |  |
parameter | Model parameter to bind to. When bound to a parameter the field will take it's value from that parameter and update the field whenever the parameter changes remotely. Any changes a user makes to the field will be validated and saved to the model. | since 4.8 |  |
post-save | An expression or a function, which is executed after a successful save.It can return a boolean or a promise, which can then resolved or rejected. If a promise is rejected, it will display an error with a rejection message. This is not triggered if the field is not bound to an entity or parameter.
Variable | Type | Description
--- | --- | ---
oldValue | string | The old value before save
newValue | string | The saved value
entityName | string | The name of the entity modified
indices | Array.<(string|boolean|number)> | Data for the index columns of the row
| since 4.8 | requires expression |
pre-save | An expression or a function, which is used to determine whether to save or not new value. Can return a truthy value or a Promise, which can be resolved with a truthy value or can be rejected with an error message and error name. This is not triggered if the field is not bound to an entity or parameter.
Variable | Type | Description
--- | --- | ---
oldValue | string | The old value before save
newValue | string | The new value to save
entityName | string | The name of the entity to be modified
indices | Array.<(string|boolean|number)> | Data for the index columns of the row
| since 4.8 | requires expression |
pre-save-error-message | A string or an expression, which is used to display an error message, when pre-save fails. If pre-save returns a rejected promise, it will use rejection message instead. | since 4.8 | accepts expression |
preserve-selection-order | Preserve the order in which options are selected. | since 5.2 |  |
preserve-user-input | Preserve user input if value expression changes. When set to "true" the value expression will no longer update the field. | since 4.8 |  |
scenario | Scenario id/index of this field | since 4.8 | accepts expression |
show-clear-option | Whether a clear button is displayed when multiple items can be selected. | since 5.3 |  |
size | The number of column units for the input element. | since 4.8 |  |
type | Specify an alternative HTML input type, for example: radio, textarea, range | since 4.8 |  |
unchecked-value | For checkboxes, the value to use to indicate it should be unchecked. | since 4.8 |  |
value | Provide the value for the field. If the field is not bound to an entity or parameter then this attribute can be used to provide the initial value of the input field. If it is an expression then the field will be updated if the expression value changes. You cannot use this attribute with the entity or parameter attributes. | since 4.8 | accepts expression |

Parent Topic VDL 5 Reference

© 2001-2026 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac Corporation (“FICO”). Receipt or possession of this documentation does not convey rights to disclose, reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation purposes to determine whether to purchase a license to the software described in this documentation, or as otherwise set forth in a written software license agreement between you and FICO (or a FICO affiliate). Use of this documentation and the software described in it must conform strictly to the foregoing permitted uses, and no other use is permitted.