396deb2e3b
Co-authored-by: Alex Ghiu <alex.ghiu@ing.com> Co-authored-by: Gerjan van Geest <Gerjan.van.Geest@ing.com> Co-authored-by: Thijs Louisse <Thijs.Louisse@ing.com> Co-authored-by: Joren Broekema <joren.broekema@ing.com> Co-authored-by: Erik Kroes <erik.kroes@ing.com>
69 lines
2.5 KiB
Markdown
69 lines
2.5 KiB
Markdown
# ModelValue
|
||
|
||
The modelValue or model can be considered as the ‘aorta’ of our form system.
|
||
It is the single source of truth; not only for the current state
|
||
of the form, also for all derived states: interaction, validation, visibility and other states are
|
||
computed from a modelValue change.
|
||
|
||
## Single source of truth
|
||
|
||
ModelValues are designed to provide the Application Developer a single way of programmatical
|
||
interaction with the form for an Application Developer.
|
||
|
||
### One single concept for Application Developers
|
||
|
||
Application Developers need to only care about interacting with the modelValue on a form control
|
||
level, via:
|
||
|
||
- `.modelValue`
|
||
- `@model-value-changed`
|
||
|
||
> Internal/private concepts like viewValue, formattedValue, serializedValue are therefore not
|
||
> recommended as a means of interaction.
|
||
|
||
### One single concept for internals
|
||
|
||
Internally, all derived states are computed from model-value-changed events.
|
||
Since the modelValue is computed 'realtime' and reflects all user interaction, visibility and
|
||
validation states, we can guarantee a system that enables the best User Experience
|
||
(see Interaction States).
|
||
|
||
## Unparseable modelValues
|
||
|
||
A modelValue can demand a certain type (Date, Number, Iban etc.). A correct type will always be
|
||
translatable into a String representation (the value presented to the end user) via the `formatter`.
|
||
When the type is not valid (usually as a consequence of a user typing in an invalid or incomplete
|
||
viewValue), the current truth is captured in the `Unparseable` type.
|
||
For example: a viewValue can't be parsed (for instance 'foo' when the type should be Number).
|
||
|
||
The model(value) concept as implemented in lion-web is conceptually comparable to those found in
|
||
popular frameworks like Angular and Vue.
|
||
|
||
The Unparseable type is an addition on top of this that mainly is added for the following two
|
||
purposes:
|
||
|
||
- restoring user sessions
|
||
- realtime updated with all value changes
|
||
|
||
### Restoring user sessions
|
||
|
||
As a modelValue is always a single source of truth
|
||
|
||
### Realtime updated with all value changes
|
||
|
||
As an Application Developer, you will be notified when a user tries to write the correct type of
|
||
a value. This might be handy for giving feedback to the user.
|
||
|
||
In order to check whether the input is correct, an Application Developer can do the following:
|
||
|
||
```html
|
||
<lion-input @model-value-changed="${handleChange}"></lion-input>
|
||
```
|
||
|
||
```js
|
||
function handleChange({ target: { modelValue, hasFeedbackFor } }) {
|
||
if (!(modelValue instanceof Unparseable) && !(hasFeedbackFor.include('error))) {
|
||
// do my thing
|
||
}
|
||
}
|
||
```
|