KoiFormFieldCheckBoxes Web Component for a List of Selectable Options

The KoiFormFieldCheckBoxes component is used to edit a list of values restricted to a set of options.

The role of KoiFormFieldCheckBoxes is the same as that of any other input field. The KoiFormFieldCheckBoxes component sets the initial value for the input field, receives new values from the user, and passes those values in the koi-form-field-change event.

However, while simple input fields (such as KoiFormFieldString, KoiFormFieldInteger, etc.) transmit string or integer values in the event, the KoiFormFieldCheckBoxes component sends an array of values selected by the user.

The user selects the values by interacting with internal components of type KoiSwitch. Each KoiSwitch component is responsible for one of the options. When the user clicks on a KoiSwitch, its value is passed to the KoiFormFieldCheckBoxes component, along with either an add or remove command. Upon receiving one of these commands, KoiFormFieldCheckBoxes either adds the value to the list of selected values or removes it from the list.

The set of options is finite and is defined by the options attribute. This is one method for defining the set of options. The second method involves obtaining the set of options from the data of an external component through a connector.

The KoiFormFieldCheckBoxes component, while providing the user with components for selecting values, can use either native checkbox components or a set of buttons that change color based on the selection.

Like any other input field, KoiFormFieldCheckBoxes is capable of displaying notifications to the user regarding the completeness and validity of the entered values.

Class

The initialization process for the component is as follows:

The KoiFormFieldCheckBoxes component is a subclass of KoiFormFieldSwitches, which serves as the foundation for building components that appear as a set of switches and have their own data of type KoiFormFieldOptionsData. Objects of this data type are based on the KoiCategorical behavior, meaning they represent lists with a fixed set of values.

When interacting with such a list, the user selects values from the predefined set of options. The set of options is defined by the KoiFormFieldCheckBoxes component during the _prepareDefaultDataValuesFromAttributes phase and can be modified during initialization, for example, if the component retrieves the options set from a connector.

Since the KoiFormFieldCheckBoxes component uses the KoiFormFieldCheckBoxesSocket as a socket, containing a set of KoiSwitch components, it subscribes to the koi-operated event, implementing the KoiOperationsInterceptable behavior.

When the user interacts with the KoiSwitch components, they send add and remove commands, along with the values to be added or removed from the component’s internal data. When the component executes these commands in the _applyOperationToOwnData handler, modifying its internal data, it triggers an event indicating the change in its data. Since the KoiFormFieldCheckBoxes component implements the KoiFormFieldChangedEventDispatchable behavior, it triggers the koi-form-field-change event. An external controller component, such as a form, can intercept the koi-form-field-change event and retrieve the set of options selected by the user from the data object passed in the event.

For the controller component to intercept the koi-form-field-change event, it must implement the KoiFormFieldChangesInterceptable behavior.

Data

The internal data of the KoiFormFieldCheckBoxes component is of type KoiFormFieldOptionsData and is defined by the following schema:

As with other input fields, the internal data of the KoiFormFieldCheckBoxes component contains information about which element should receive a new value and the new value itself.

The value is an array containing the options selected by the user. The set of options is restricted, and the array can contain only one instance of each option, as determined by the KoiCategorical behavior. This behavior provides two methods for managing the set of selected options: selectOption and deselectOption. Using these methods, the KoiFormFieldCheckBoxes component modifies the set of selected options in its internal data during the processing of the koi-operated event, which comes from the internal KoiSwitch components.

Since the basic KoiFormFieldCheckBoxes component uses KoiSwitch components, which can only handle string values, the set of options for the KoiFormFieldCheckBoxes component must contain only string values.

The initial set of selected options is obtained by the data object from the component’s tag attributes in the _prepareDefaultDataValuesFromAttributes method, which is called in the _onBeforeConnected handler of the KoiDataCapable behavior. The obtained values are processed in the KoiJSONable behavior within the applyTypeToAttributeValue method. This method converts the escaped, JSON-encoded value from the tag into an array.

If the set of options needs to be sourced from an external provider, such as a connector, the corresponding behavior should be implemented in the _updateOwnDataWhenConnected and _updateOwnDataWhenConnectorDataChanged handlers. The component first attempts to get the set of values from the attributes, then from the connector if it is ready to provide data, and when processing connector's data changes.

Similarly, from the value of the options tag, the component receives and passes the complete set of options to the internal data object. This occurs in the same _prepareDefaultDataValuesFromAttributes method, which is extended by the KoiFormFieldOptionsDataCapable behavior.

Connector

The component determines its initial value and set of options from the tag attributes.

Another method for setting initial values for the component’s data is to obtain them via a connector to a data provider. This requires using the KoiControlConnectorInteractable behavior and specifying the provider’s identifier in the provider_id parameter of the component.

Direct connections between a component and a provider for string or numeric values are infrequently used. Typically, the provider connects to a form that generates input fields and passes their initial values through attributes.

The purpose of a direct connection to a provider is to allow the component to retrieve both an initial value and additional configuration based on the provider’s data when a form is absent. In this context, the additional configuration includes the set of options.

It is expected that the set of options may not exactly match the values of the data provider’s elements. Additionally, the value entered by the user may not be utilized by the provider and might even have a different data type or purpose. For example, the provider might contain two data elements, each with its own value. The component retrieves these values and transforms them into a set of options.

By design, the component only retrieves the initial value from the provider. Changes to the value within the component do not affect the provider’s data, and changes to the provider’s data do not affect the component’s data. Furthermore, when validating its data, the component does not rely on the provider’s data settings.

This behavior can be modified if needed, for example, by implementing reinitialization of the component when the provider’s data changes. However, such functionality is not included in the basic component.

In the basic implementation, it is assumed that the provider transmits the initial value to the component once and does not influence its operation thereafter.

That said, the basic component has a side effect: it depends on the provider’s state. If the provider transitions to an error or loading state, the component will respond to it. While this functionality may be useful for certain tasks, it is likely unnecessary in many cases.

Attributes

The attributes of the KoiFormFieldCheckBoxes component largely mirror those of other input fields. They include field_name, field_value, and placeholder, along with an additional attribute, options, which defines the set of permissible values for the component.

The key difference between KoiFormFieldCheckBoxes and other input fields lies in its value, which is an array. This array can contain various elements, including those with HTML symbols. However, the component’s tag attributes must be provided as strings. As such, the values of the component’s attributes must be encoded as escaped JSON strings.

Component State

The KoiFormFieldCheckBoxes component inherits from KoiBaseControl, providing two methods for managing its visibility: show and hide.

Unlike many input field components, KoiFormFieldCheckBoxes uses a socket of type KoiCompositeSocket. Input fields are expected to support methods such as disable, enable, setReadonly, and removeReadonly, typically implemented via the KoiSocketInputEnablementToggleable behavior, which is compatible only with KoiSingleSocket. For KoiCompositeSocket, these methods are implemented separately using the KoiCompositeSocketInputEnablementToggleable behavior.

Since the base component uses KoiSwitch as its internal components, the setReadonly and removeReadonly methods are implemented but do not affect the user's ability to modify the component’s value.

Like other input fields, KoiFormFieldCheckBoxes can display error notifications. These notifications may indicate validation errors and issues with data completeness, handled by the component’s data object. They may also reflect form-level errors, which should be managed by the form acting as the controller component. However, the basic KoiFormFieldCheckBoxes component does not implement error display methods, as such errors are generally reduced to data validation issues that should be handled by the data object itself.

Similarly, the component does not include methods for directly managing its value, as this responsibility is delegated to the user. If direct value management is required, it can be implemented in derived components, as demonstrated in the KoiFormFieldString example.

Event

The KoiFormFieldCheckBoxes component has its own data but does not implement the KoiChangedEventDispatchable behavior, and therefore does not trigger the koi-changed event. Instead, it implements the KoiFormFieldChangedEventDispatchable behavior, allowing it to emit the koi-form-field-change event.

The koi-form-field-change event has a bubbles property set to true. This means the event propagates through the DOM tree, enabling the creation of composite components, such as forms with multiple input fields and internal validation logic based on these 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. These methods allow retrieval of the name of the data field associated with the input field and the current value of the input field.

Important: When accessing values from the event, modifying the retrieved values will also alter the data in the component itself. If you intend to modify the value, ensure you make a copy of it first.

An example of event interception can be seen in the previously described scenario where a controller component (e.g., a panel) intercepts input field actions using the _updateOwnDataWhenSocketChanged method.

Usage

Input fields are typically not used standalone but as part of a form. In this regard, everything stated about the KoiFormFieldString component also applies to KoiFormFieldCheckBoxes.

For a form to intercept the result of a user’s interaction with the component, it must implement the KoiFormFieldChangesInterceptable behavior.

Additionally, for a form to store the results, it must maintain its own data, including a data element of type KoiDataElementList, or it must pass the changes to another component that contains such a data element.

Val Koi