The prefill feature makes form filling a lot easier, by prefilling inputs with values derived from either:
- bindings to other field values
- or, fields with an already known value when the page is loaded; for example a default value or a value that is sent from the server.
The prefilled values need to be explicitly confirmed, and it is also possible to change the appearance of an input to further illustrate that it is in a "prefill" state by setting the appropriate skin variables.
In the example shown below the "prefill" text is gray and when focus is given to a field displaying a prefill value the value is confirmed and the text becomes black.
In this animation, when a user fills in the first segment for a trip, all the following segments are updated. For example, when the date of the first segment is set, the date of all the following segments is set to the date of the first one. Another automatically filled field is the origin of the second segment, which has the same value of the destination field of the first segment.
Note that, in the example, the pre-filled value of any unconfirmed date is the value of the first confirmed date before that line. For example, if the user changes the date in the second line (not shown in the animation), the pre-filled date of the following lines changes and contains the date of the second line, and the value in the second line is confirmed. If, after that, the date in the first line is changed by the user, the date in the second line will not change, as it is already confirmed. If the user types something wrong in the first field, the other fields are not automatically pre-filled with that value.
Any text input widget that extends the TextInput base class will provide the Prefill feature through a bindable property called prefill.
The following input widgets all currently support Prefill:
TextInput-based widgets are endowed with a
prefill state and a
prefill bindable property. The
prefill state is triggered by setting a value in the portion of the data model to which the prefill property is bound, on condition that the
value of the widget is not set.
Consider the following example:
data.value2 is not set (
`), whenever the value data.value1
is set (different from 
), the widget will be in prefill
state and the displayed text will correspond to the value contained in data.value1`.
When the widget is focused, it automatically exits the prefill state because the focus handler will update the
value property, hence another state (
normalFocused) will be triggered.
data.value2 are not set, then the widget is in
normal state and a helptext is displayed if specified in the widget configuration.
Consider the following typical scenario:
The value bound to the
prefill for widgetA (
data.value1) is also bound to the
value property of widgetB. Typing an "incorrect" value in widgetB will not trigger the prefilling of widgetA. In particular, the following behaviour occurs:
- when the value fails native widget validation (for example the string "aaa" in the NumberField widgetB), then the value is not propagated to the data model, so that the prefill on widgetA will not be triggered. Whenever errors are reported in the validation process, widgetA will be automatically notified and will hence exit the prefill state.
No validation is performed on the prefill value. If for some reason the prefill of NumberField ends up being a string like "aaa", then no error is raised. The validation occurs, for example, when focusing on the field.
It is important to remark that the prefill behaviour is slightly different depending on the widget. In particular:
SelectBox: the prefill will not be displayed if the value does not belong to the
optionsavailable to the widget.
MultiSelect: the items that do not belong to the
itemsavailable will not be displayed in the list of selected values.
AutoComplete: the prefill value will be displayed only if it corresponds to one of the suggestions recognized by the resource handler.
DatePicker: the date/time pattern of the prefill is the same as the one specified in the widget configuration. It is not possible to specify a different pattern for the prefill value.
When a widget is in prefill state it is possible to confirm the displayed value either by focusing on the field or by explicitly setting the portion of the data model to which its
value property is bound. Considering the example
it is possible to confirm a prefill value by
in a script (or module controller).
Once the state is confirmed, changing
data.value1 will not have any impact on the widget, until
data.value2 is not set to
Like any other state, the
prefill state can be skinned by setting the desired variables in the
aria.templates.TextInput.std.states.prefill.color=gray aria.templates.SelectBox.std.states.prefill.color=gray aria.templates.DatePicker.std.states.prefill.color=gray aria.templates.MultiSelect.std.states.prefill.color=gray aria.templates.AutoComplete.std.states.prefill.color=gray
In this sample it is possible to find some examples of the above-mentioned features including all
In this sample it is possible to find an example that realizes one of the scenarios that triggered the implementation of this feature.