To briefly demonstrate how to use the KoiCom library, let's insert the simplest component onto a page. All other components are inserted in exactly the same way, and if you are familiar with web components, you will probably not be surprised.
As you can see, it’s very simple. Inserting a component from the KoiCom library is no different from inserting web components according to the standard. This is one of the advantages of the KoiCom library – compared to the standard that describes working with web components, nothing has been complicated.
Why Web Components?
Above, we inserted the KoiLabel component. Its task is simply to display some text or a number within a nice border. That’s its essence and purpose. How it looks is not as important. There might not even be a border.
In fact, the component for displaying text is not strictly necessary. You can easily use a regular span tag. But then, what's the reason for creating a display component? I’ll tell you right away – it’s not to have the same style for fragments of text in different parts of the page. CSS or Bootstrap can handle that just fine.
The purpose of the KoiLabel component is to transform certain input data into the data we want to display. Here’s a simple example: let’s say the component receives two numbers as input. You want it to display a formula illustrating their multiplication.
Yes, this can be achieved with other methods as well. But the key is the principle itself. You can embed anything you want into the data transformation process. You could display a smiling face if true is passed, and a sad face if false is passed. A component inherited from KoiLabel could take a function as input and display its integral. The essence of the KoiLabel component is in data transformation.
Data transformation is a behavior that makes sense to encapsulate within a component. When using a simple span, the code responsible for this behavior is external to the span. With web components, you gain the ability to hide the behavior. This is essentially the main purpose of web components.
You can read more about the KoiLabel component in the Controls section. Now, let’s explore how to include components on a page.
Simple Integration
The first thing you need to do is declare the component. This is done with the following code:
This code specifies which file the component's code should be loaded from, and which HTML tag will be responsible for the component.
Next, insert the following into the appropriate place in the HTML:
Essentially, this is all you need, and it will work. However, if you’re building a large system, you’ll encounter a number of problems. First, you will have a large number of components and thus, a large number of tags. Eventually, you will get confused about which tag corresponds to which component. Second, at some point, you might discover that you’ve declared the same component multiple times. Therefore, components should be connected in a different way.
Uniqueness of Tags
I haven’t encountered a project where there’s a need to use multiple tags for the same component. Typically, each component is rendered in HTML with a single tag. Therefore, I decided that the component’s code should include a static method getTagName, which ensures each component has its unique tag.
With this method, the component declaration code becomes as follows:
At the same time, the method itself looks like this:
In this way, I addressed two problems:
- Each component has a unique tag, and it became easier to ensure that two components do not share the same tag.
- When declaring a component, there is no need to remember which tag it is associated with.
Tag Naming Guidelines
When declaring a component, you are focused on solving a specific task. If you’re required to invent a tag name at that moment, it will either reflect the task’s context or fail to capture the component’s true essence.
| Suggested Name | Analysis |
|---|---|
| item-card-for-filtered-stock-list | Context-specific and task-dependent, making it unsuitable for broader use. |
| item-card | Too generic; it fails to convey the component’s distinct purpose or behavior. |
To address this, assigning tag names within the component’s getTagName method provides a more coherent naming strategy. This ensures that names are decided based on the component itself rather than the immediate task context.
Best Practices for Naming Tags
Use Library-Specific Prefixes Group components into libraries and prefix their tags with a library identifier. For example, I use the prefix koi to distinguish my components from others. Additionally, I employ task-specific prefixes like docs for components designed exclusively for documentation purposes. This approach ensures clarity and avoids naming conflicts.
Highlight the Component’s Purpose Choose a name that reflects the component's role. Ask yourself: what function does this component serve? Common names like table or button work well when the purpose is straightforward. For more specific use cases, names like stock-item-card-with-photo-and-price can provide adequate clarity, even if verbose.
Since the tag name resides in the getTagName method, it can be updated anytime without disrupting the application.
Ensuring Unique Declarations
Attempting to declare the same component more than once will result in an error.
In large systems, it's common for the same component to be declared multiple times — for instance, as part of a panel, embedded within a table, used independently, or included within a product card.
To prevent such issues, a simple and effective approach can be applied:
The import statement, when called in various places, generally does not cause problems. The imported file is typically loaded once and cached, minimizing additional requests on subsequent imports.
Wrap the define method with a check to ensure that if a component is already declared, any repeated declarations are bypassed.
Component Placement
To place a component, you embed it as an HTML tag.
This approach, while straightforward, has some downsides:
- Remembering the Tag: You must recall which tag corresponds to the component.
- Attribute Recall: You need to know which attributes are used by the component.
- Programmatic Tag Creation: Generating a tag programmatically can result in messy and error-prone concatenated strings.
While these challenges are inherent to the approach, they can be mitigated by encapsulating this logic in a method. This keeps the complexities hidden and simplifies usage.
The placement of the component then looks like this:
In this example:
- The id attribute is mandatory for all KoiCom components.
- The value attribute is specific to KoiLabel and is not required by many other components.
Refer to the documentation for each component or the getTag method's implementation to understand the full list of attributes and their functions.
Component Declaration and Placement Order
The order of declaring and placing a component is flexible. You can first declare the component and then insert the corresponding tag, or you can reverse the process—insert the tag and declare the component later, even at the bottom of the page. This flexibility makes the process both universal and convenient.
It is also technically possible to declare a component conditionally within complex logic. For instance, based on a specific condition, you could set a tag to transform into one component in one scenario and into another component in a different scenario.
However, this approach is not recommended. It adds unnecessary complexity to your program. The same outcomes can usually be achieved using alternative methods that are more straightforward and easier to understand.
Interacting with Components
Once a component is declared and added to the page, you can access its instance from your code, such as through the browser console. With a reference to the instance, you can inspect the data it holds and even modify its displayed content. The scope of operations is limited by the component’s designed functionality.
For instance, after calling the attemptChangeValue method, you’ll notice the component’s displayed text updates immediately. This is expected and reflects the default behavior of the KoiLabel component, which automatically updates its display whenever its data is modified via attemptChangeValue.
The process is simple. A component is just an HTML element with a custom tag. It functions similarly to standard HTML elements like div or span. Components are embedded in your page using specific tags.
Components can display content, respond to user interactions, adapt to data changes, or react to context shifts. Each component is defined by its unique behavior, setting it apart from others.
You can fully control the visual styling of components through CSS, just as you do with standard HTML elements like div or p. The library imposes no restrictions on styling.
Important: Avoid directly inserting components from the library’s libs directory into your page. Although this practice is occasionally used in the documentation for illustrative purposes, it is discouraged in real-world projects. Instead, use components from the js directory. More details on this approach will be covered in the Inheritance section.