A component that manages a set of internal components.
The KoiExpansionPanel component serves as a template. To use KoiExpansionPanel, you must create a subclass of the KoiExpansionPanel class. This necessity is indicated by the absence of the getTagName and getTag methods in the component.
The main purpose of KoiExpansionPanel is to enable the creation of components that offer methods for adding and removing internal components. In doing so, KoiExpansionPanel handles storing references to these components and automates their tracking, naming, and ordering.
The core of KoiExpansionPanel is a socket of type KoiEnumeratedCompositeSocket. This socket implements the KoiSocketEnumerable behavior, which provides the expandSocket method. The attemptExpandSocket method of the KoiExpansionPanel class is based on this behavior. The attemptExpandSocket method creates another component within the component's tag, and its tag is defined in the _getTagForNewComponent method.
Therefore, by implementing the _getTagForNewComponent method in a subclass of KoiExpansionPanel and calling the attemptExpandSocket method, you can add an internal component and interact with it.
The reverse method, i.e., the method for removing internal components, is not present in the base KoiExpansionPanel, but can be implemented through the _removeComponent method of the socket.
The attemptExpandSocket method includes a component_settings parameter. If the order property is provided in this parameter, the KoiExpansionPanel component will attempt to insert the new internal component not after the existing components, but at the position specified by order.
If the component_settings parameter matches one of the settings of an already existing internal component, the new component will not be inserted. However, this behavior can be modified in a subclass of KoiExpansionPanel.
The socket of the KoiExpansionPanel component implements the KoiSocketActiveItemCapable behavior, which highlights one of the internal components as active. The newly added internal component automatically becomes active. If adding an internal component fails, the active component does not change. When a component is removed, the last remaining component becomes active.
This KoiSocketActiveItemCapable behavior enables the creation of toggleable tabs and panels with switchable content, where one tab (or panel) is activated while the others are deactivated.
Class
The component initialization process is as follows:
-
_onConstructed() KoiStateCapable
- _constructState() KoiStateCapable
-
_onBeforeConnected() KoiElementStencil
-
_onConnected() KoiElementStencil
- _updateSomethingWhenConnected() KoiElementStencil
-
- _updateOwnDataWhenConnected() KoiElementStencil
- _updateStateCodeWhenConnected() KoiStateCapable
-
_onAfterConnected() KoiElementStencil
- isSomethingChanged() KoiStateCapable
- _handleSomethingChangedWhenAfterConnected() KoiBaseControl
-
- _updateAppearance() KoiBaseControl
- _setNothingChanged() KoiStateCapable
- _subscribeToEvents() KoiElementStencil
As seen, the initialization process for the KoiExpansionPanel component is identical to that of the KoiPanel panel. The core of the KoiExpansionPanel component resides in its KoiEnumeratedCompositeSocket socket.
The KoiEnumeratedCompositeSocket socket does not implement the KoiSocketTemplateCapable behavior, meaning it lacks a template. This socket is designed to directly place internal components inside the component's tag.
For interaction with the socket, the KoiExpansionPanel component implements the KoiEnumeratedCompositeSocketConnectable behavior, which provides the attemptExpandSocket method. This method allows the socket to create internal components.
The attemptExpandSocket method takes a single parameter, component_settings, which is passed unchanged to the socket. Since the socket’s role is to automate the tracking of internal components, it automatically generates an element identifier (the id attribute content for the component's tag), determines the order number for the added component using the KoiEnumeration class, and creates an identifier using the _generateNewKey method, which can be used to access the component in the socket's methods. These three values are appended to component_settings, resulting in an array of component_params, which can be used to generate the HTML tag for the internal component using the _getTagForNewComponent method.
Next, the socket, using the KoiEnumeration class, determines how the component with a specific order number should be placed in the list of internal components. It searches for an already existing component with a smaller order number, and the new component is inserted immediately after the found one. This is handled by the _insertComponentToDOM method.
The KoiEnumeration class plays a crucial role here. In the base socket, it is implemented in the simplest way, allowing components to be inserted sequentially when their order numbers are not specified, and in a given order when they are. However, some tasks may require different insertion algorithms, such as sorting based on specific characteristics. In such cases, a subclass of KoiEnumeratedCompositeSocket can be created to use a different method for ordering components.
Data
The KoiExpansionPanel component does not have its own data, but its subclasses can have their own data if they implement the appropriate behaviors.
Custom data is often needed when the KoiExpansionPanel component must display a list and tools to modify it. In such cases, the custom data will have a list type, enabling modification both of the data items and the composition of the list. A CRUD table is an example of this.
The example with the CRUD table is discussed in detail in the theoretical part of the documentation.
Connector
Since the KoiExpansionPanel component can add and remove internal components, there may be a need to link the set of components to external data.
External data, particularly list-structured data, can determine the initial set of internal components, and controller events can trigger the removal and addition of internal components.
This requires linking data element identifiers to specific internal components. The easiest way to do this is to use these identifiers as keys for the _ids structure in the component’s socket.
Attributes
| id | Component identifier |
|---|
The KoiExpansionPanel component has only one attribute — the component identifier.
Component State
The KoiExpansionPanel component does not have any additional visible states other than those defined in the base KoiBaseControl class. These states are controlled by the show and hide methods.
Additionally, although the KoiExpansionPanel component does not have a template, it has a component state defined by the KoiStateCapable behavior. Therefore, subclasses of KoiExpansionPanel can implement responses to changes in this state.
Event
The KoiExpansionPanel component does not trigger any events.
Usage
The KoiExpansionPanel component is used to create switchable tabs and panels with dynamic content.
While tabs can be implemented in many other, simpler ways, this method has a distinct advantage. By using KoiExpansionPanel, tab content is loaded as it is created, which is particularly useful when the content involves large amounts of data or complex client-side computations.
Another application of the KoiExpansionPanel component is creating sets of similar components, the number of which is not known in advance.
Components can include labels, buttons, and any complex components, such as rows in a CRUD table. A detailed example of a CRUD table is provided in the corresponding section of the documentation.