The purpose of the KoiDialogString component is to provide the user with an interface to input a string value and accompany it with one of two commands.
The KoiDialogString component is a panel featuring an input field for the string value and two buttons. By clicking one of the buttons, the user issues the corresponding command. Along with the command, the value entered in the input field is passed.
The role of KoiDialogString is not simply to modify a value. For that, an input field alone would suffice. The presence of two command options implies that the user can decide what to do with the entered string value. Additionally, depending on the value entered, the set of options may change.
For instance, if the entered value is invalid, one of the buttons might be disabled. This illustrates how the set of options can change based on the value entered.
In the example above, the KoiDialogString component intercepts the event triggered when the value of the input field changes. The entered value is then converted into the component’s internal data. The presence of errors in the internal data is determined, and the display in the socket is updated. If an error exists, one of the dialog buttons is set to a disabled state.
It’s important to note that the absence of an error code in the data does not automatically mean the button should be enabled. An error code may also be absent if the data has not yet been validated. For this reason, the component includes a method to determine whether the data has been validated.
This example demonstrates not only the ability to control command options based on the entered value but also the use of internal data to enable the component's functionality.
Internal data is required so that the component can store and transmit, as part of an event, a combination of the command, the string value, and the identifier of the element to which the command and value should be applied. This is particularly useful when KoiDialogString is used to manage a list of elements.
In principle, internal data could be avoided by attaching the value to the event triggered by the buttons as it propagates up the DOM tree. However, the value obtained from the input field does not always match the value passed in the dialog event. Generally, when an event is received from the input field, a transformation method is applied. This method must be called every time the input field triggers an event, allowing KoiDialogString to respond to the new transformed value. Consequently, between the moment the input field event is received and the moment a command is issued by the buttons, the transformed value must be stored. This is why internal data is necessary.
The event emitted by KoiDialogString itself can be intercepted by an external component containing the KoiDialogString component within it.
To allow the external component to determine which of the two commands the user selected, it must compare the command code included in the event with the codes defined in the static methods getApplyActionCode and getCancelActionCode of the component.
Class
The initialization process for the component looks as follows:
-
_onConstructed() KoiDataCapable
- _constructState() KoiStateCapable
- _constructSocket() KoiDialogString
- _constructData() KoiOperationDataCapable
-
_onBeforeConnected() KoiDataCapable
- _prepareSocket() KoiSocketConnectable
-
- socket.getTemplate() KoiDialogQuestionSocket
- _constructOperationEvent() KoiOperationEventDispatchable
- _prepareDefaultDataValuesFromAttributes() KoiDataCapable
-
_onConnected() KoiElementStencil
- _updateSomethingWhenConnected() KoiElementStencil
-
- _updateOwnDataWhenConnected() KoiElementStencil
- _updateStateCodeWhenConnected() KoiStateCapable
-
_onAfterConnected() KoiElementStencil
- isSomethingChanged() KoiDataCapable
- _handleSomethingChangedWhenAfterConnected() KoiBaseControl
-
- updateAppearance() KoiBaseControl
- _setNothingChanged() KoiDataCapable
- _subscribeToEvents() KoiFormFieldChangesInterceptable
-
- _subscribeToChangeEvent() KoiFormFieldChangesInterceptable
- _subscribeToOperateEvent() KoiOperationsInterceptable
The KoiDialogString component is a subclass of KoiDialogQuestion and implements the behaviors KoiOperationDataCapable, KoiFormFieldChangesInterceptable, and KoiOperationEventDispatchable.
The KoiDialogQuestion class is used as the base class for dialogs. It provides a socket of type KoiDialogQuestionSocket with two buttons and a control panel where labels and input fields can be placed. The KoiDialogQuestion class implements the KoiOperationsInterceptable behavior, which allows it to intercept events from the buttons placed within the socket and respond to them.
Unlike the KoiDialogQuestion component, the KoiDialogString component does not pass events from the buttons through to the parent but instead intercepts them and stops the propagation, as it uses the KoiOperationEventDispatchable behavior to trigger its own events.
The KoiOperationDataCapable behavior allows the component to form a command consisting of an identifier for some element, a value, and a command code. This command is the component's internal data and is passed externally when the event is triggered.
The KoiFormFieldChangesInterceptable behavior enables the component to respond to changes in the input field value and modify its internal data based on the value entered by the user.
The KoiOperationEventDispatchable behavior allows the component to trigger the koi-operated event. In the default KoiDialogString component, this event is triggered when the component intercepts events from the buttons located within its socket and processes them, modifying its internal data.
Note that if the same button is pressed again, the KoiDialogString component will not trigger the event a second time, as the component’s internal data have already taken a value after the first press and will not be modified again.
In other words, if a dialog is displayed to the user, where they enter a value, then press a button, and the dialog is hidden, the event will not be triggered again if the dialog is shown again, unless the user changes the value. If they press the same button without changing the value, the event will not be triggered.
Data
The internal data of the KoiDialogString component have the type KoiOperationData, which defines the data according to the following schema:
Most often, a dialog is used to change the value of some element. In this case, the dialog is similar to a button, and thus, the data used by the KoiDialogString component behave similarly to the data of the KoiIdLink component.
Attributes
| id | Component identifier |
|---|---|
| item_id | String identifier of the element |
| item_value | Value of the command parameter |
| message | String displayed in the component |
| apply_caption | Caption on the first button |
| cancel_caption | Caption on the second button |
| element_class | CSS class for the component |
The KoiDialogString component has three attributes that define the labels displayed in the socket: the main label (which represents a question to the user) and the captions for the buttons. In this case, the component's attributes replicate the attributes of the KoiDialogQuestion component.
Additionally, the KoiDialogString component has the attributes item_id and item_value, which allow for setting default values for the internal data. Their purpose is to specify the user's intent, that is, to communicate why the user used the dialog. More details about these attributes can be found in the description of the KoiIdLink component.
State
The KoiDialogString component does not have any additional visible states beyond those defined in the base class KoiBaseControl. These states are set by the show and hide methods.
Event
The KoiDialogString component has internal data but does not implement the KoiChangedEventDispatchable behavior, so it does not trigger the koi-change event when its data change. Instead, the component triggers the koi-operated event when the button is pressed, i.e., when the user interacts with the component's socket.
The koi-operated event object is of the CustomEvent type and is created at the onBeforeConnected moment in the _constructOperationEvent method to avoid creating a new object each time the event is triggered.
The koi-operated event has the bubbles property set to true, which means the event is propagated upwards through the DOM tree. This allows for creating buttons inside a composite component, and the composite component will automatically handle their clicks, acting as a controller.
The event passes the KoiDialogString component's internal data, which includes not only the command issued by the user but also the value entered by the user and the identifier of the element to which the command and value should be applied. An example of using the dialog to work with a list of elements can be found in the "Example" section, where the process of creating a CRUD panel is demonstrated.
Usage
If the component is used as a standard dialog, for example, a dialog that allows setting a global value such as the title of an editable document, this dialog can be created once when the document is opened and hidden until it is needed by the user.
If the component is used to edit elements from a list, dialogs can be created as needed, rather than creating one for each list element, assuming the user will not edit every single element one after another.
The display of the dialog, that is, the call to the show method, is performed by an external component. However, it is not advisable for the external component to also hide the dialog by calling the hide method. Instead, the dialog should hide itself.
There are two main reasons for the dialog to hide itself.
First, hiding the dialog means that the value entered by the user has been accepted. Otherwise, the user would have been presented with a notification asking them to change the value. Therefore, before the dialog is hidden, some method must process what the user entered and respond accordingly.
In the example where one of the buttons becomes disabled when the input field is empty, the situation is partially illustrated where the dialog's displayed state changes in response to the change in the input field value.
Since this reaction can affect the dialog’s display, the processing should be handled by the dialog, and one result of this processing is the decision to hide the dialog.
Second, the dialog does not trigger an event if its internal data has not been changed. This was mentioned in the "Event" section. That is, if the dialog is hidden by an external component, there could be a situation where the user clicks a button, but the external component does not receive the event and does not hide the dialog.