A component for selecting one value from a list limited to a set of options.
The KoiFormFieldSingleChoice component serves the same purpose as any input field. It sets the initial value for the input field, receives a new value from the user, and transmits this value through the koi-form-field-change event.
The koi-form-field-change event has its bubbles property set to true, allowing the event to propagate up the DOM tree. This enables the creation of input fields within composite components, typically referred to as input forms, where the composite component automatically processes incoming data and acts as the controller.
Like any other input field, KoiFormFieldSingleChoice can display notifications to the user regarding the completeness and validity of the entered values.
A distinguishing feature of KoiFormFieldSingleChoice is that it offers the user a limited set of options to choose from. This set of options is defined in the options attribute of the component's tag.
Since the set of options is an array and each option can contain any characters, including HTML symbols, the set of options must be encoded when passed through the component's tag attribute.
Another way to define the set of options is to obtain them from an external component's data using a connector.
Class
The initialization process of the component is as follows:
-
_onConstructed() KoiDataCapable
- _constructState() KoiStateCapable
- _constructData() KoiFormFieldSingleChoiceDataCapable
- _constructSocket() KoiFormFieldNativeSelectSocketConnectable
- _constructInnerNativeComponentData() KoiNativeInputDataCapable
-
_onBeforeConnected() KoiDataCapable
- _constructFormFieldChangedEvent() KoiFormFieldChangedEventDispatchable
- _prepareDefaultDataValuesFromAttributes() KoiFormFieldSingleChoiceDataCapable
-
- data.setDefaultValuesFromAttributes() KoiData
- _prepareDataOptionsFromAttributes() KoiFormFieldSingleChoiceDataCapable
- _prepareSocket() KoiSocketConnectable
-
- socket.getTemplate() KoiFormFieldBaseSocket
-
- socket._getTemplateForInput() KoiFormFieldNativeSelectSocket
- socket._getLabelTemplate() KoiFormFieldBaseSocket
- socket._getErrorHolderTemplate() KoiFormFieldBaseSocket
-
_onConnected() KoiElementStencil
- _updateSomethingWhenConnected() KoiElementStencil
-
- _updateOwnDataWhenConnected() KoiElementStencil
- _updateStateCodeWhenConnected() KoiStateCapable
-
_onAfterConnected() KoiElementStencil
- isSomethingChanged() KoiDataCapable
- _handleSomethingChangedWhenAfterConnected() KoiBaseControl
-
- _updateAppearance() KoiBaseControl
- _setNothingChanged() KoiDataCapable
- _subscribeToEvents() KoiOperationsInterceptable
-
- _subscribeToOperateEvent() KoiOperationsInterceptable
The KoiFormFieldSingleChoice component inherits from KoiNativeInput, but through the KoiFormFieldSingleChoiceDataCapable behavior, it has a specialized internal data object of type KoiFormFieldSingleChoiceData. This data object contains information about the user's intent, specifically which element the user wants to modify and the new value for that element. In the basic KoiFormFieldSingleChoice component, the element’s value is expected to be a string.
A unique feature of the internal data object is the KoiOptionable behavior of the data element responsible for the value. This behavior allows defining a limited set of options, among which the user's selected value must belong.
During the initialization of the KoiFormFieldSingleChoice component, the set of options, along with the initial value, is passed to the internal data object from the component's tag attributes using the _prepareDefaultDataValuesFromAttributes method. The component then initializes the socket by converting the set of options into the socket's initial settings through the _convertDataToInitialSocketSettings method.
The set of options and the initial value are established during the socket's initial preparation and do not change thereafter. If it becomes necessary to redefine the set of options or reassign the initial value, the component must be reinitialized.
At the end of the initialization process, the KoiFormFieldSingleChoice component subscribes to changes in its internal native components by implementing the KoiOperationsInterceptable behavior.
Each time the user modifies the value of an internal component, the KoiFormFieldSingleChoice component intercepts this event.
Because the KoiFormFieldSingleChoice component uses a native select element to interact with the user, the process of handling events from the internal native component has specific features. For instance, native components do not pass their own values in events, which requires the KoiFormFieldSingleChoice component to implement the KoiNativeInputDataCapable behavior.
The KoiNativeInputDataCapable behavior enables the component to form a command to modify its internal data based on the event received from the native component, obtaining the new value directly from the socket.
After modifying its internal data using this command, the component triggers the koi-form-field-change event.
Because the koi-form-field-change event has the bubbles property set to true, an external controller component, such as a form, can retrieve the value selected by the user from the KoiFormFieldSingleChoice component.
To enable this, the controller component must implement the KoiFormFieldChangesInterceptable behavior.
Data
The internal data of the KoiFormFieldSingleChoice component is of type KoiFormFieldSingleChoiceData, defined according to the following schema:
Like other input fields, the internal data of the KoiFormFieldSingleChoice component contains information about which element should receive a new value and the new value itself.
However, the key difference is that the value of the internal data object in the KoiFormFieldSingleChoice component is constrained by a predefined set of options, a restriction enforced by the KoiOptionable behavior.
The KoiOptionable behavior enables the data element to store a set of options and provides two methods to interact with this set: getOptions and setOptions. These methods allow the data object to implement its own versions of getOptions and setOptions.
The getOptions method of the internal data object is used by the KoiFormFieldSingleChoice component during the initialization phase to determine the set of options available for user selection. This set is then passed to the socket, enabling it to present the appropriate native component for selecting a value.
The setOptions method is invoked by the KoiFormFieldSingleChoice component within the _prepareDefaultDataValuesFromAttributes method at an earlier stage. This is when the component determines, based on its tag's attribute values, the set of options from which the user will choose.
If the options need to be defined by an external source, such as a connector, this behavior should be implemented in the _updateOwnDataWhenConnected and _updateOwnDataWhenConnectorDataChanged handlers. In this workflow, the component first attempts to retrieve the set of options from its attributes, then from the connector (if it is ready to supply the data), and finally during the processing of changes in the connector's data.
Connector
The initial value and selectable options for the component are determined from the tag’s attributes.
An alternative method for setting initial values for the component’s data is to obtain them through a connector to a data provider. To achieve this, the component must implement the KoiControlConnectorInteractable behavior, and the provider_id parameter should specify the data provider’s identifier.
Connecting a component directly to a provider for string or numeric values is rarely necessary. Typically, the provider is connected to a form, which then creates the input fields and populates their initial values through attributes.
The primary purpose of a direct connection to a provider is to enable the component to obtain both an initial value and additional settings—such as options—derived from the provider’s data, even in the absence of a form.
The options provided by the provider may not exactly match the values stored in its data elements. Additionally, user-entered values may not necessarily be utilized by the provider and might differ in type or purpose. For instance, in the provided example, the provider contains two data elements, each with a unique value. The component retrieves these values and transforms them into selectable options.
With this approach, the component only retrieves the initial value from the provider. Subsequent changes to the component’s data do not affect the provider, and changes to the provider’s data do not influence the component. Furthermore, when validating its own data, the component does not rely on the provider’s data settings.
If needed, this behavior can be modified—for example, by making the component reinitialize when the provider’s data changes. However, such functionality is not implemented in the base component.
In its default state, the base component assumes the provider transmits the initial value once and does not affect the component’s operation thereafter.
That said, the base component has a side effect: it depends on the provider's state. If the provider enters an error or loading state, the component will react to this. While this feature may be useful for certain scenarios, it is likely unnecessary in many cases.
Attributes
| id | The identifier of the component |
|---|---|
| field_name | The name of the data element whose value can be modified by the user |
| field_value | The initial displayed value of the component |
| options | A list of allowable values |
| placeholder | A user-facing hint or suggestion |
The KoiFormFieldSingleChoice component shares many attributes with other input fields, including field_name, field_value, and placeholder. However, it introduces an additional attribute, options, which specifies the permissible values for the component.
Unlike other input fields, the attributes of the KoiFormFieldSingleChoice component tag must be provided as strings, while the options attribute is an array. For this reason, the options attribute must be passed as an escaped JSONEncoded value.
Component State
The KoiFormFieldSingleChoice component extends KoiBaseControl, offering two basic methods for managing its visibility: show and hide.
Beyond these foundational methods, the component incorporates the behavior KoiSocketInputEnablementToggleableSocketConnectable, enabling additional input-specific methods: enable, disable, setReadonly, and removeReadonly. These methods control the user’s ability to interact with the component.
Due to the use of a native select element as the internal component, the setReadonly and removeReadonly methods are implemented but do not actually restrict the user from altering the component's value.
Additionally, the KoiFormFieldSingleChoice component, like any input field, can display error messages. These messages may indicate either issues with data validity or completeness, managed by the component’s internal data object, or form-level errors, which should be handled by the form acting as the controller. However, the base KoiFormFieldSingleChoice component does not include methods for displaying errors, as such functionality is generally tied to data validity and should be implemented at the data object level.
Similarly, the component does not include built-in methods for value management, as the user is expected to control the value directly. That said, direct value management can be implemented in derived components, as illustrated in the KoiFormFieldString example.
Event
The KoiFormFieldSingleChoice component manages its own data but does not implement the KoiChangedEventDispatchable behavior, meaning it does not trigger the koi-changed event. Instead, it implements the KoiFormFieldChangedEventDispatchable behavior, enabling it to emit the koi-form-field-change event.
The koi-form-field-change event has its bubbles property set to true, allowing the event to propagate through the DOM tree. This propagation supports the creation of composite components, such as input forms with multiple fields and internal validation logic for processing data received through events.
To handle the koi-form-field-change event, a controller component must implement the KoiFormFieldChangesInterceptable behavior. Once implemented, the controller can utilize the KoiFormFieldData object’s getFieldName and getFieldValue methods to retrieve the name of the data field tied to the input field and the field's current value.
A practical example of event interception is demonstrated earlier, where a controller component (panel) intercepts user interactions with an input field by employing the _updateOwnDataWhenSocketChanged method.
Usage
Input fields are generally not used standalone but as part of larger forms. In this regard, all principles applicable to the KoiFormFieldString component also apply to the KoiFormFieldSingleChoice component.
For a form to capture user interaction results from the component, it must implement the KoiFormFieldChangesInterceptable behavior.
To store these results, the form must either include its own data structure containing a KoiDataElementString data element or delegate the changes to another component equipped with such a data element.