You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/_guide/actions.md
+18-3Lines changed: 18 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,7 +3,23 @@ chapter: 6
3
3
subtitle: Binding Events
4
4
---
5
5
6
-
Catalyst Components, upon creation, will search for any children with the `data-action` attribute, and bind events based on the value of this attribute. Any _public method_ on a Controller can be bound to via `data-action`.
6
+
Catalyst Components automatically bind actions upon instantiation. Automatically as part of the `connectedCallback`, a component will search for any children with the `data-action` attribute, and bind events based on the value of this attribute. Any _public method_ on a Controller can be bound to via `data-action`.
Copy file name to clipboardExpand all lines: docs/_guide/decorators.md
+71-1Lines changed: 71 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,4 +3,74 @@ chapter: 3
3
3
subtitle: Using TypeScript for ergonomics
4
4
---
5
5
6
-
This is decorators
6
+
Decorators are used heavily in Catalyst, because they provide really clean ergonomics and makes using the library a lot easier. Decorators are a special, (currently) non standard, feature of TypeScript. You'll need to turn the `experimentalDecorators` option on inside of your TypeScript project to use them.
7
+
8
+
You can read more about [decorators in the TypeScript handbook](https://www.typescriptlang.org/docs/handbook/decorators.html), but here's quick guide:
9
+
10
+
Decorators can be used three ways:
11
+
12
+
### Class Decorators
13
+
14
+
Catalyst comes with the `@controller` decorator. This gets put on top of the class, like so:
15
+
16
+
```js
17
+
@controller
18
+
classMyControllerextendsHTMLElement {}
19
+
```
20
+
21
+
### Class Field Decorators
22
+
23
+
Catalyst comes with the `@target` and `@targets` decorators for more [read about Targets](/guide/targets). These get added on top or to the left of the field name, like so:
24
+
25
+
```js
26
+
classMyControllerextendsHTMLElement {
27
+
28
+
@target something
29
+
30
+
// Alternative style
31
+
@targets
32
+
others
33
+
34
+
}
35
+
```
36
+
<br>
37
+
38
+
Class Field decorators get given the class and the field name so they can add custom functionality to the field. Because they operate on the fields, they must be put on top of or to the left of the field.
39
+
40
+
### Method Decorators
41
+
42
+
Catalyst doesn't currently ship with any method decorators, but you might see them in code. They work just like Field Decorators (in fact they're the same thing). Put them on top or on the left of the method, like so:
43
+
44
+
45
+
```js
46
+
classMyControllerextendsHTMLElement {
47
+
48
+
@log
49
+
submit() {
50
+
// ...
51
+
}
52
+
53
+
// Alternative style
54
+
55
+
@log load() {
56
+
// ...
57
+
}
58
+
59
+
}
60
+
```
61
+
62
+
### Function Call Decorators
63
+
64
+
Some decorators are customisable - they get called with additional arguments, just like a function call. An example of this is the `@debounce` decorator in the [`@github/mini-throttle`](https://github.com/github/mini-throttle) package:
Copy file name to clipboardExpand all lines: docs/_guide/introduction.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,7 +19,7 @@ The Web Systems team at GitHub explored other tools that adopt these set of patt
19
19
20
20
Catalyst takes these three core concepts and delivers them in the lightest possible way they can be delivered.
21
21
22
-
-**Observabiliy** Catalyst solves observability by leveraging [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements). Custom Elements are given unique names within a system, and the browser will automatically use the Custom Element registry to observe these Elements entering and leaving the DOM. Read more about this in the Guide Section entitled [Custom Elements](/guide/custom-elements).
22
+
-**Observability** Catalyst solves observability by leveraging [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements). Custom Elements are given unique names within a system, and the browser will automatically use the Custom Element registry to observe these Elements entering and leaving the DOM. Read more about this in the Guide Section entitled [Custom Elements](/guide/custom-elements).
23
23
24
24
-**Listening** Event Delegation makes a great deal of sense when observing events "high up the tree" - registering global event listeners on the Window element - but Custom Elements sit much closer to their children within the tree, and so Direct Event binding is preferred. Catalyst solves this by binding event listeners to any descendants with `data-action` attributes. Read more about this in the Guide Section entitled [Actions](/guide/actions).
Copy file name to clipboardExpand all lines: docs/_guide/targets.md
+47-11Lines changed: 47 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,12 +3,16 @@ chapter: 5
3
3
subtitle: Querying Descendants
4
4
---
5
5
6
-
Catalyst Components are just Web Components, and so you can simply use `querySelector` or `querySelectorAll` to select descendants of the element. Targets, however, provide a more consistent interface for accessing descendants.
6
+
One of the three [core patterns](/guide/introduction#three-core-concepts-observe-listen-query) is Querying. In Catalyst, Targets are the preferred way to query. Target use `querySelectorAll` under the hood, but make it a lot simpler to work with.
7
+
8
+
Catalyst Components are really just Web Components, so you could simply use `querySelector` or `querySelectorAll` to select descendants of the element. Targets avoid some of the problems of `querySelector`; they provide a more consistent interface and handle nesting intuitively. Targets are also a little more ergonomic to reuse in a class. We'd recommend using Targets over `querySelector` wherever you can.
9
+
10
+
To create a Target, use the `@target` decorator on a class field, and add the matching `data-target` attribute to your HTML, like so:
7
11
8
12
### Example
9
13
10
14
<divclass="d-flex my-4">
11
-
<divclass="">
15
+
<div>
12
16
13
17
```html
14
18
<hello-controller>
@@ -22,10 +26,11 @@ Catalyst Components are just Web Components, and so you can simply use `querySel
Remember! There are two decorators available, `@target` which fetches only one element, and `@targets` which fetches multiple. This is the only difference, but it's an important one.
65
+
66
+
</div>
67
+
</div>
68
+
69
+
The `@target` decorator will only ever return _one_ element, just like `querySelector`. If you want to get multiple Targets, you need the `@targets` decorator which works almost identically, but it'll return an _array_ of _N_ elements.
70
+
48
71
Elements can be referenced as multiple targets, and targets may be referenced multiple times within the HTML:
There are two decorators available, `@target` which fetches only one element, and `@targets` which fetches multiple. It is important to distinguish between the two.
Copy file name to clipboardExpand all lines: docs/_guide/your-first-component.md
+54-1Lines changed: 54 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,4 +3,57 @@ subtitle: Building an HTMLElement
3
3
chapter: 2
4
4
---
5
5
6
-
Your first component
6
+
Custom Elements allow you to create reusable components that you can declare in HTML, and [progressively enhance](https://en.wikipedia.org/wiki/Progressive_enhancement) within JavaScript. Custom Elements must named with a `-` in the HTML name, and the JS class must `extend HTMLElement`. When the browser connects each element class instance to the DOM node, `connectedCallback` is fired - this is where you can change parts of the element. Here's a basic example:
-`connectedCallback` can be used as a life-cycle hook for when the element and class are connected.
27
+
28
+
### Catalyst
29
+
30
+
Catalyst saves you writing some of this boilerplate, by automatically calling the `customElements.register` code, and by adding ["Actions"](/guide/actions) and ["Targets"](/guide/targets) features described later. If you're using TypeScript with `decorators` support, simply add `@controller` to the top of your class:
0 commit comments