2 |
3 | # Capsule v0.6.1
4 |
5 | [](https://github.com/capsidjs/capsule/actions/workflows/ci.yml)
6 |
7 | > Event-driven DOM programming in a new style
8 |
9 | # Features
10 |
11 | - Supports **event-driven** style of frontend programming in a **new way**.
12 | - Supports **event delegation** and **outside events** out of the box.
13 | - **Lightweight** library.
14 | [**1.25 kiB**](https://raw.githubusercontent.com/capsidjs/capsule/v0.6.1/dist.min.js)
15 | gzipped. **No dependencies**. **No build** steps.
16 | - Uses **plain JavaScript** and **plain HTML**, requires **No special syntax**.
17 | - **TypeScript** friendly.
18 |
19 | [See live examples](https://capsule.deno.dev/)
20 |
21 | # Motivation
22 |
23 | Virtual DOM frameworks are good for many use cases, but sometimes they are
24 | overkill for the use cases where you only need a little bit of event handlers
25 | and dom modifications.
26 |
27 | This `capsule` library explores the new way of simple event-driven DOM
28 | programming without virtual dom.
29 |
30 | # Slogans
31 |
32 | - Local query is good. Global query is bad.
33 | - Define behaviors based on HTML classes.
34 | - Use pubsub when making remote effect.
35 |
36 | ## Local query is good. Global query is bad
37 |
38 | When people use jQuery, they often do:
39 |
40 | ```js
41 | $(".some-class").each(function () {
42 | $(this).on("some-event", () => {
43 | $(".some-target").each(function () {
44 | // some effects on this element
45 | });
46 | });
47 | });
48 | ```
49 |
50 | This is very common pattern, and this is very bad.
51 |
52 | The above code can been seen as a behavior of `.some-class` elements, and they
53 | use global query `$(".some-target")`. Because they use global query here, they
54 | depend on the entire DOM tree of the page. If the page change anything in it,
55 | the behavior of the above code can potentially be changed.
56 |
57 | This is so unpredictable because any change in the page can affect the behavior
58 | of the above class. You can predict what happens with the above code only when
59 | you understand every details of the entire application, and that's often
60 | impossible when the application is large size, and multiple people working on
61 | that app.
62 |
63 | So how to fix this? We recommend you should use **local** queries.
64 |
65 | Let's see this example:
66 |
67 | ```js
68 | $(".some-class").each(function () {
69 | $(this).on("some-event", () => {
70 | $(this).find(".some-target").each(function () {
71 | // some effects on this element
72 | });
73 | });
74 | });
75 | ```
76 |
77 | The difference is `$(this).find(".some-target")` part. This selects the elements
78 | only under each `.some-class` element. So this code only depends on the elements
79 | inside it, which means there is no global dependencies here.
80 |
81 | `capsule` enforces this pattern by providing `query` function to event handlers
82 | which only finds elements under the given element.
83 |
84 | ```js
85 | const { on } = component("some-class");
86 |
87 | on.click = ({ query }) => {
88 | query(".some-target").textContent = "clicked";
89 | };
90 | ```
91 |
92 | Here `query` is the alias of `el.querySelector` and it finds `.some-target` only
93 | under it. So the dependency is **local** here.
94 |
95 | ## Define behaviors based on HTML classes
96 |
97 | From our observation, skilled jQuery developers always define DOM behaviors
98 | based on HTML classes.
99 |
100 | We borrowed this pattern, and `capsule` allows you to define behavior only based
101 | on HTML classes, not random combination of query selectors.
102 |
103 | ```html
104 |
13 | 
14 | Capsule examples
15 |
16 |
17 | 18 | This page shows the examples of 19 | capsule 20 | frontend library.
21 |Mirroring example
23 |The example of mirroring the input value to another dom.
24 |JS
25 |const { on } = component("mirroring");
26 |
27 | on.input = ({ query }) => {
28 | query(".dest").textContent = query(".src").value;
29 | };
30 | HTML
31 | 32 | 33 |Result
39 | 40 |43 | 44 |
Mount hook example
46 |When you assign a function to "on.__mount__", it's called when the component is mounted.
47 |JS
48 |const { on } = component("hello");
49 |
50 | on.__mount__ = ({ el }) => {
51 | el.textContent = `Hello, I'm ${el.textContent}! 👋`;
52 | };
53 | HTML
54 | 55 | 56 |Result
59 | 60 |63 | 64 |
Pubsub example
66 |67 | capsule 68 | supports pubsub pattern with "pub" and "sub" methods. 69 |
70 |JS
71 |const EVENT = "my-event";
72 |
73 | {
74 | const { on } = component("pub-element");
75 |
76 | on.click = ({ pub }) => {
77 | pub(EVENT, { hello: "clicked!" });
78 | };
79 | }
80 |
81 | {
82 | const { on, sub } = component("sub-element");
83 |
84 | sub(EVENT);
85 |
86 | on[EVENT] = ({ e, el }) => {
87 | el.textContent += " " + e.detail.hello;
88 | };
89 | }
90 |
91 |
92 | HTML
95 | 96 |Result
97 | 98 |101 | 102 |
Event delegation example
104 |105 | Capsule supports 106 | Event delegation 107 | pattern. 108 |
109 | 110 |113 | The event handler is bound to wrapper div (.delegation-example), but the handler is 114 | only triggered when the event targeted to '.btn' element. 115 |
116 |117 | 118 |
JS
121 |const { on } = component("delegation-example");
122 |
123 | on(".btn").click = ({ query }) => {
124 | query(".result").textContent += " .btn clicked!";
125 | };
126 |
127 | HTML
128 | 129 |Result
130 | 131 |134 | 135 |
Outside event example
137 |138 | When you're creating floating UI patterns such as tooltips or modal dialogs, you often need to handle the events "outside" of the target dom. 139 | Capsule supports this pattern with "on.outside[eventName]". 140 |
141 | 142 |JS
145 |const { on } = component("outside-example");
146 |
147 | on.outside.click = ({ el }) => {
148 | el.textContent += " outside clicked!";
149 | }
150 | HTML
151 | 152 |Result
153 | 154 |157 | 158 |
Prevent default example
160 |If you need to preventDefault or stopPropagation, you can access it via '.e' prop.
161 | 162 | Link 163 | 164 |JS
165 |const { on } = component("prevent-example");
166 |
167 | on.click = ({ e }) => {
168 | e.preventDefault();
169 | alert("A link is clicked, but the page doesn't move to the target url because the default behavior is prevented ;)");
170 | };
171 | HTML
172 | 173 |Result
174 | 175 |177 | More details about capsule library is available in 178 | the github repository. 179 |
180 |