Show Sidebar Menu

KoiFormFieldDate WebComponent for Modifying Date Values

The article explains the KoiFormFieldDate component, which allows users to select and edit date values. It covers how the component initializes, validates input, and triggers events like koi-form-field-change.

Component for Editing Calendar Values.

The purpose of the KoiFormFieldDate component is the same as that of the KoiFormFieldString component: to provide the user with a tool for modifying a specific dataset. In the case of KoiFormFieldDate, this tool is an input field. The KoiFormFieldDate component sets the initial value for the input field, receives a new value from the user, and transmits this value via the koi-form-field-change event.

The key difference between KoiFormFieldDate and KoiFormFieldString lies in the type of data they handle. While KoiFormFieldString operates with string values, KoiFormFieldDate handles values of the Date type. The component stores these Date type values in its internal data and passes them as Date type values in the koi-form-field-change event.

The koi-form-field-change event has the property bubbles set to true, allowing the event to propagate up the DOM tree. This enables input fields to be placed inside composite components, typically referred to as input forms. These composite components automatically process incoming data and act as controllers.

In the example below, the panel acts as such a controller component. It contains the input field and a KoiLabel component. Using the KoiFormFieldChangesInterceptable behavior, the panel reacts to the koi-form-field-change event triggered by the KoiFormFieldDate component and passes the value received in the event to the KoiLabel component.

Like KoiFormFieldString, the KoiFormFieldDate component can also display notifications to the user regarding the completeness and validity of the entered values. Additionally, the component validates the input value against boundary conditions.

Class

The initialization process for the KoiFormFieldDate component is as follows:

  1. _onConstructed() KoiDataCapable
    • _constructState() KoiStateCapable
    • _constructData() KoiFormFieldDateDataCapable
    • _constructSocket() KoiFormFieldDateNativeInputSocketConnectable
    • _constructInnerNativeComponentData() KoiNativeInputDataCapable
  2. _onBeforeConnected() KoiDataCapable
    • _constructFormFieldChangedEvent() KoiFormFieldChangedEventDispatchable
    • _prepareDefaultDataValuesFromAttributes() KoiFormFieldMinMaxableDataCapable
    • _prepareSocket() KoiSocketConnectable
      • socket.getTemplate() KoiFormFieldBaseSocket
        • socket._getTemplateForInput() KoiFormFieldDateNativeInputSocket
        • socket._getLabelTemplate() KoiFormFieldBaseSocket
        • socket._getErrorHolderTemplate() KoiFormFieldBaseSocket
  3. _onConnected() KoiElementStencil
    • _updateSomethingWhenConnected() KoiElementStencil
      • _updateOwnDataWhenConnected() KoiElementStencil
      • _updateStateCodeWhenConnected() KoiStateCapable
  4. _onAfterConnected() KoiElementStencil
    • isSomethingChanged() KoiDataCapable
    • _handleSomethingChangedWhenAfterConnected() KoiBaseControl
      • _updateAppearance() KoiBaseControl
    • _setNothingChanged()KoiDataCapable
    • _subscribeToEvents() KoiOperationsInterceptable
      • _subscribeToOperateEvent() KoiOperationsInterceptable

The KoiFormFieldDate component is a subclass of KoiFormFieldStencil and implements the behaviors KoiFormFieldDateDataCapable, KoiNativeInputDataCapable, and KoiFormFieldDateNativeInputSocketConnectable.

The KoiFormFieldDateDataCapable behavior extends KoiFormFieldMinMaxableDataCapable and defines the data object type for the component as KoiFormFieldDateData. Through the KoiFormFieldMinMaxableDataCapable behavior, KoiFormFieldDate shares many similarities with KoiFormFieldInteger.

For example, the KoiFormFieldDate component allows setting upper and lower boundaries for the input value, validates the entered value against these boundaries, and can restrict user input using the properties of the native input[type="date"] component.

In other respects, KoiFormFieldDate functions similarly to other input fields: it accepts user input, stores it in its internal data object, and transmits it via the koi-form-field-change event. This behavior is defined by the KoiFormFieldStencil class.

Like other input fields, the KoiFormFieldDate component includes a socket that connects to the native input component for data entry and reacts to changes in its value. This is facilitated by the KoiNativeInputDataCapable and KoiFormFieldDateNativeInputSocketConnectable behaviors.

For more detailed information on working with sockets containing native input fields, refer to the documentation for KoiFormFieldString and KoiFormFieldInteger. Here, I’ll summarize the key points.

Since KoiFormFieldDate specializes in working with Date type values, and native input fields do not propagate their values in events, the component uses the KoiNativeInputDataCapable behavior to simulate a process where the native input field triggers a command in the koi-form-field-change event. This command is executed by the KoiFormFieldDate component, which updates its internal data based on the user-entered value.

Additionally, the value of the native input field is of type string, while the KoiFormFieldDate component operates with Date type values. As a result, the component must perform bidirectional type conversions.

Conversion from Date to String is required when the component sets initial values for the socket. This process is handled by the _convertDataToInitialSocketSettings method.

Conversion from String to Date is needed when the component receives a command from the socket and updates its internal data. This process occurs in the _applyOperationToOwnData method, with the conversion handled by the KoiDataElementDate data element.

Data

The internal data for the KoiFormFieldDate component is of the type KoiFormFieldDateData and is defined by the following schema:

Working with this data object does not require any special behavior that provides additional methods. Implementing the KoiFormFieldDateDataCapable behavior is sufficient.

This behavior does not provide public methods for retrieving or setting values. However, such methods can be implemented in subclasses using the methods of the KoiFormFieldData class.

That said, directly working with the data of the KoiFormFieldDate component is not recommended. The component's primary role is to receive data entered by the user and pass it on through events. In other words, the data values are set during the initialization of the component and are subsequently modified by the user, rather than programmatically.

The only additional operation the component performs on user-entered values is checking for boundary conditions, validity, and completeness. This validation is carried out by the methods of the KoiDataElementDate class. You can define the data requirements in the data schema through the constructor arguments, for example, by setting allow_empty to false or specifying boundaries using min and max.

Attributes

id The identifier of the component.
field_name The name of the data field whose value is modified by the user.
field_value The initial value displayed in the input field.
placeholder A hint or placeholder text for the user.
min_value The lower boundary for acceptable values.
max_value The upper boundary for acceptable values.

In addition to the attributes described in the documentation for KoiFormFieldString, the KoiFormFieldDate component includes the min_value and max_value attributes, which restrict the range of values that can be entered in the input field. Once these properties are assigned, the component passes them to the socket connected to the input field. Thus, the boundaries for user-entered values are set when the component is integrated into the DOM and remain unchanged afterward.

If runtime modification of these boundaries is required, a descendant of the KoiFormFieldDate component can be created, where the boundaries are set using a pair of setters and immediately passed to the input field.

The component also validates user-entered data not only at the socket level but also within the internal data object. For this reason, the component retrieves the min_value and max_value attributes and passes them to the internal data object, extending the _prepareDefaultDataValuesFromAttributes method.

A key distinguishing feature of the KoiFormFieldDate component is that it stores a value of the Date type in its internal data, whereas the attributes of the tag must be provided as strings. Therefore, the values of the field_value, min_value, and max_value attributes must be strings formatted as 'YYYY-MM-DD'. The data object automatically converts these string values into the Date type using the applyTypeToAttributeValue method of the data element.

Component State

The KoiFormFieldDate component, like other input fields, can display error notifications. These notifications can represent errors in data validity and completeness, which are handled by the internal data object, or errors related to the overall form submission, which should be managed by the form acting as the controller component. However, in the base KoiFormFieldDate implementation, error display methods are not provided, as such errors are almost always reducible to data validity errors, which should be handled at the data object level.

Since the KoiFormFieldDate component uses an input element as its native component, it can control the user's ability to modify its value by providing the methods disable, enable, setReadonly, and removeReadonly through the KoiSocketInputEnablementToggleable behavior.

Event

The KoiFormFieldDate component triggers the koi-form-field-change event whenever its internal data changes.

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

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

An example of interception you can find above, where a controller component (a panel) captures changes to the input field's value using the _updateOwnDataWhenSocketChanged method.

Important: When retrieving values from the event, remember that modifying the received Date type values will also modify the component's internal data. If you intend to change the retrieved value, make a copy before proceeding.

Usage

The native date input component used by KoiFormFieldDate is often neither user-friendly nor implemented consistently across browsers. This limitation has led to the creation of numerous alternative components designed to replace it.

However, the purpose of the KoiFormFieldDate component is not to provide a convenient input method. Instead, its primary role is to demonstrate how an input component that encapsulates a specific input method should function.

The behaviors implemented in KoiFormFieldDate illustrate how the component initializes the input field, processes user commands to modify data, and executes those commands to pass the updated values to a controller component, typically represented by a form.