KoiFormFieldInteger - Input Field for Handling Integer Data

Component for Editing Integer Values.

The task of KoiFormFieldInteger is the same as that of KoiFormFieldString, namely to provide the user with a tool for modifying a set of data. In the case of KoiFormFieldInteger, this tool is an input field. The KoiFormFieldInteger component sets the initial value for the input field, receives a new value from the user, and passes this value in the koi-form-field-change event.

The difference between KoiFormFieldInteger and KoiFormFieldString is that it allows the user to enter, contains in its own data, and, accordingly, transmits an integer value in the event, not a string value.

There is another variant of KoiFormFieldInteger, built in the same way but working with floating-point numeric values. This is the KoiFormFieldFloat component.

The koi-form-field-change event has the property bubbles set to true, meaning the event propagates up the DOM tree. This allows for the creation of input fields within a composite component, typically called a form, and the composite component will automatically process the incoming data, acting as the controller.

In the example below, the panel acts as such a controller component. The panel contains an input field and a KoiLabel component. Using the KoiFormFieldChangesInterceptable behavior, the panel responds to the koi-form-field-change event from the KoiFormFieldInteger component, retrieves the user-entered value from the event data, and passes this value to the KoiLabel component.

Like KoiFormFieldString, this component is also capable of displaying notifications to the user about the completeness and validity of the entered values. Additionally, the component checks the entered value against boundary conditions. Try entering a value outside the range from 5 to 10 in the input field in the previous example. The component will react to the attempt with an error notification.

Class

The initialization process of the component looks as follows:

The KoiFormFieldInteger component is a direct subclass of KoiNativeNumericInput, which is the base class for numeric input fields. Both KoiFormFieldInteger and the previously mentioned KoiFormFieldFloat inherit from KoiNativeNumericInput.

KoiFormFieldInteger and KoiFormFieldFloat are quite similar to each other. Their main difference is that KoiFormFieldInteger handles integer values, while KoiFormFieldFloat deals with floating-point values. Consequently, KoiFormFieldInteger has its own data class, KoiFormFieldIntegerData, whereas KoiFormFieldFloat uses KoiFormFieldFloatData. Since they behave almost identically in all other aspects, let's explore their ancestor, KoiNativeNumericInput.

Like KoiFormFieldString, KoiNativeNumericInput inherits from KoiFormFieldStencil. Additionally, like KoiFormFieldString, it implements the KoiNativeInputDataCapable behavior.

This means that the component has a socket connected to a native input component and responds to changes in the value within the native component by triggering the koi-form-field-change event. For more details, refer to the KoiFormFieldString documentation.

However, besides the methods shared between KoiNativeNumericInput and KoiFormFieldString, the KoiNativeNumericInput class is specifically designed for handling numeric values. To accomplish this, KoiNativeNumericInput extends basic methods and adds several methods specific to numeric input fields.

For instance, KoiNativeNumericInput restricts the user's input and processes keyboard input and mouse wheel events.

There are two ways to limit the value received from the user to integers. One method is to accept all possible values, validate them, and notify the user if the value is not an integer. The second method leverages the properties of integer values, namely that integer values consist of a limited set of characters—digits and the minus sign. This method prevents any other characters from being entered in the field.

There is a native input[type="number"] component, which is wrapped by the KoiNativeNumericInput component. By implementing the KoiNumericInputWheelAndKeyEventsInterceptable behavior, the KoiNativeNumericInput component restricts the input of characters into the native component.

In addition to limiting the entered values, the KoiNativeNumericInput component restricts the range of input values. To achieve this, it implements the KoiFormFieldMinMaxableDataCapable behavior, which provides methods to set the upper and lower numeric boundaries for the data object values.

For these boundaries to be applied during the user's interaction with the native component, the KoiNativeNumericInput component must pass the boundary values to the socket as the initial socket settings. For this purpose, the KoiNativeNumericInput component implements the method _convertDataToInitialSocketSettings.

However, since in some cases the component receives values not only from the user, the boundaries must automatically apply to values received by the data object in all cases. If incoming values violate the boundaries, the data object should transition into a state reflecting the invalidity of the values during validation. This behavior is implemented in the data elements of the KoiFormFieldIntegerData class, specifically in the KoiDataElementNumeric class, from which the data elements are inherited.

In addition to limiting values, working with numeric values also implies that the component will transmit numeric values in the event. This is an intuitive expectation from the component, but native components behave quite differently.

First, as mentioned with KoiFormFieldString, native components do not transmit their values in events. Therefore, components interacting with native components must retrieve the values by accessing the socket using the method _getInputValueFromSocket.

Second, native components return string-type values. That is, although input[type="number"] works with numbers, its value attribute returns a string.

The KoiNativeNumericInput component must address these issues and return a number. In other words, interaction with the socket, based on native components, requires data conversion.

Such data conversion must occur when setting the initial values for the socket and when receiving data from the socket, as seen in the methods _convertDataToInitialSocketSettings and _applyOperationToOwnData. In the first method, when passing a value to the socket, the component converts the value to a string without using methods from the data object, while in the second case, the conversion happens automatically within the data object. Generally, these conversions should be executed based on the component's logic, taking into account the values used by the data object and the values used by the socket. For example, the socket may interact with the user, prompting them to enter a percentage of some value, while the data object may store the final result.

Data

The internal data of the KoiFormFieldInteger component has the type KoiFormFieldIntegerData and is defined by the following schema:

No special behavior is required to work with this data object that would provide additional methods. It is sufficient to implement the KoiFormFieldMinMaxableDataCapable or KoiFormFieldDataCapable behaviors.

These behaviors do not provide public methods for getting or setting values, but such methods can be implemented in subclasses using the methods from the KoiFormFieldData class.

However, direct interaction with the KoiFormFieldInteger component's data is not recommended, since the component's task is to receive data entered by the user and transmit it in an event. In other words, the data values are set during the component's initialization and then changed by the user, not programmatically.

The only additional action the component performs with the values entered by the user is checking for boundaries, validity, and completeness. This check is performed by methods in the KoiDataElementInteger class, and you can define data requirements in the data schema's constructor arguments, for example, by setting allow_empty to false or defining boundaries using min and max.

Attributes

In addition to the attributes described in the documentation for KoiFormFieldString, the KoiFormFieldInteger component has min_value and max_value attributes, which limit the range of values entered in the input field. After receiving the property values, the component passes them to the input field. Thus, the boundaries for the value entered by the user are set when the component is injected into the DOM and are not changed thereafter.

If the boundaries for the input value need to be modified at runtime, a subclass of the KoiFormFieldInteger component can be created, where the boundaries are set using a pair of setters and immediately passed to the input field.

The component retrieves the min_value and max_value from the attributes and passes them to the data object, extending the _prepareDefaultDataValuesFromAttributes method.

If either of the min_value or max_value attributes is not set, the value will not be restricted.

Component State

As with any input field component, the KoiFormFieldInteger component implements methods to control user access to data modification and methods for displaying error notifications. More details on this can be found in the documentation for the KoiFormFieldString component.

The notification can reflect either a data validity and completeness error, handled by the data object, or a form completion error, which should be managed by the form acting as the controller component. However, in the base KoiFormFieldInteger, error display methods are not implemented because, in most cases, such errors can be reduced to data validity errors, which should be handled at the data object level.

Since the KoiFormFieldInteger component uses the input element as its native component, it can control whether the user can modify the component's value, providing methods such as disable, enable, setReadonly, and removeReadonly through the KoiSocketInputEnablementToggleable behavior.

Event

The KoiFormFieldInteger component triggers the koi-form-field-change event when the value of its data object changes.

The koi-form-field-change event has a bubbles property set to true, meaning it propagates up the DOM tree. This allows for the creation of composite components, such as input forms with multiple fields and internal data validation logic based on events.

To intercept the koi-form-field-change event, the controller component must implement the KoiFormFieldChangesInterceptable behavior. The controller can then use the methods of the KoiFormFieldData object, such as getFieldName and getFieldValue, to retrieve the name of the data field associated with the input field and the value of the input field.

An interception example can be seen in the previous example, where the controller component (the panel) intercepts the input field value changes using the _updateOwnDataWhenSocketChanged method.

Usage

Like KoiFormFieldString, the KoiFormFieldInteger component is designed to be used within data input forms, where the form manages the initial value of the field, receives the entered values via events, and commands the component to display notifications for the user.

In principle, KoiFormFieldString can be used instead of KoiFormFieldInteger to receive values, but KoiFormFieldInteger, unlike KoiFormFieldString, provides primary protection against incorrect input by specializing in numeric values.

Moreover, and perhaps more importantly, KoiFormFieldInteger passes a final numeric value in the event, while KoiFormFieldString passes string values. This means that when working with KoiFormFieldInteger, you can expect a numeric value and not worry about validation or conversion.

Additionally, it can be said that a wide variety of user input components can be implemented based on KoiFormFieldInteger, such as sliders and toggles that involve numeric input.

Val Koi