3.7 KiB
FormatMixin
The FormatMixin keeps track of the modelValue, formattedValue and serializedValue.
It is designed to work in conjunction with LionField.
Concepts of different values
model value
The model value is the result of the parser function. It will be stored as .modelValue
and should be considered the internal value used for validation and reasoning/logic.
The model value is 'ready for consumption' by the outside world (think of a Date object
or a float). It can(and is recommended to) be used as both input value and
output value of the LionField.
Examples:
- For a date input: a String '20/01/1999' will be converted to
new Date('1999/01/20') - For a number input: a formatted String '1.234,56' will be converted to a Number:
1234.56
view value
The view value is the result of the formatter function.
It will be stored as .formattedValue and synchronized to .value (a viewValue setter that
allows to synchronize to .inputElement).
Synchronization happens conditionally and is (by default) the result of a blur. Other conditions
(like error state/validity and whether the a model value was set programatically) also play a role.
Examples:
- For a date input, this would be '20/01/1999' (dependent on locale).
- For a number input, this could be '1,234.56' (a String representation of modelValue 1234.56)
serialized value
This is the serialized version of the model value. It exists for maximal compatibility with the platform API. The serialized value can be an interface in context where data binding is not supported and a serialized string needs to be set.
Examples:
- For a date input, this would be the iso format of a date, e.g. '1999-01-20'.
- For a number input this would be the String representation of a float ('1234.56' instead of 1234.56)
When no parser is available, the value is usually the same as the formattedValue (being inputElement.value)
Formatters, parsers and (de)serializers
In order to create advanced user experiences (automatically formatting a user input or an input set imperatively by an Application Developer).
Below some concrete examples can be found of implementations of formatters and parsers, extrapolating the example of a date input.
Formatters
A formatter should return a formattedValue:
function formatDate(modelValue, options) {
if (!(modelValue instanceof Date)) {
return options.formattedValue;
}
return formatDateLocalized(modelValue, options);
}
Notice the options object, which holds a fallback value that shows what should be presented on screen when the user input resulted in an invalid modelValue
Parsers
A parser should return a modelValue:
function parseDate(formattedValue, options) {
return formattedValue === '' ? undefined : parseDateLocalized(formattedValue);
}
Notice that when it's not possible to create a valid modelValue based on the formattedValue,
one should return undefined.
Serializers and deserializers
A serializer should return a serializedValue:
function serializeDate(modelValue, options) {
return modelValue.toISOString();
}
A deserializer should return a modelValue:
function deserializeDate(serializeValue, options) {
return new Date(serializeValue);
}
FieldCustomMixin
When creating your own custom input, please use FieldCustomMixin as a basis for this.
Concrete examples can be found at <lion-input-date> and
<lion-input-amount>.
Flow diagram
The following flow diagram is based on both end user input and interaction programmed by the developer. It shows how the 'computation loop' for modelValue, formattedValue and serializedValue is triggered.
