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
Here are a few common anti-patterns which we've discovered as developers have used Catalyst. We consider these anti-patterns as they're best avoided, because of surprising edge-cases, or simply because there are easier ways to achieve the same goals.
11
12
@@ -111,6 +112,59 @@ class UserSettingsElement extends HTMLElement {
111
112
</div>
112
113
</div>
113
114
115
+
### Avoid shadowing method names
116
+
117
+
When naming a method, you should avoid naming it something that already exists on the `HTMLElement` prototype; as doing so can lead to surprising behaviors. Test out the form below to see what method names are allowed or not:
### Avoid naming methods after events, e.g. `onClick`
115
169
116
170
When you have a method which is only called as an event, it is tempting to name that method based off of the event, e.g. `onClick`, `onInputFocus`, and so on. This name implies a coupling between the event and method, which later refactorings may break. Also names like `onClick` are very close to `onclick` which is already [part of the Element's API](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onclick). Instead we recommend naming the method after what it does, not how it is called, for example `resetForm`:
Copy file name to clipboardExpand all lines: docs/_guide/conventions.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,7 +16,7 @@ class UserListElement extends HTMLElement {}
16
16
17
17
### The best class-names are two word descriptions
18
18
19
-
Custom elements are required to have a `-` inside the tag name. Catalyst's `@controller` will derive the tag name from the class name - and so as such the class name needs to have at least two capital letters, or to put it another way, it needs to consist of two words. The element name should describe what it does succinctly in two words. Some examples:
19
+
Custom elements are required to have a `-` inside the tag name. Catalyst's `@controller` will derive the tag name from the class name - and so as such the class name needs to have at least two capital letters, or to put it another way, it needs to consist of at least two CamelCased words. The element name should describe what it does succinctly in two words. Some examples:
@@ -34,8 +34,8 @@ Be careful not to go too short! We'd recommend avoiding contracting words such a
34
34
35
35
### Method names should describe what they do
36
36
37
-
A good method name, much like a good class name, describes what it does, not how it was invoked. While methods can be given any name, names like `onClick` are best avoided, overly generic names like `toggle` should also be avoided. Just like class names it is a good idea to ask "how" and "what", so for example `showAdmins`, `filterUsers`, `updateURL`.
37
+
A good method name, much like a good class name, describes what it does, not how it was invoked. While methods can be given most names, you should avoid names that conflict with existing methods on the `HTMLElement` prototype (more on that in [anti-patterns](/guide/anti-patterns#avoid-shadowing-method-names)). Names like `onClick` are best avoided, overly generic names like `toggle` should also be avoided. Just like class names it is a good idea to ask "how" and "what", so for example `showAdmins`, `filterUsers`, `updateURL`.
38
38
39
39
### `@target` should use singular naming, while `@targets` should use plural
40
40
41
-
To help differentiate the two `@target`/`@targets` decorators, the properties should be named with respective to their cardinality. That is to say, if you're using an `@target` decorator, then the name should be singular (e.g. `user`, `field`) while the `@targets` decorator should be coupled with plural property names (e.g. `users`, `fields`).
41
+
To help differentiate the two `@target`/`@targets` decorators, the properties should be named with respective to their cardinality. That is to say, if you're using an `@target` decorator, then the name should be singular (e.g. `user`, `field`) while the `@targets` decorator should be coupled with plural property names (e.g. `users`, `fields`).
Copy file name to clipboardExpand all lines: docs/_guide/your-first-component.md
+35-22Lines changed: 35 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,51 +3,64 @@ subtitle: Building an HTMLElement
3
3
chapter: 2
4
4
---
5
5
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:
6
+
### Catalyst's `@controller` decorator
7
7
8
-
```html
9
-
<hello-world></hello-world>
10
-
<script>
8
+
Catalyst's `@controller` decorator lets you create Custom Elements with virtually no boilerplate, by automatically calling `customElements.register`, and by adding ["Actions"](/guide/actions) and ["Targets"](/guide/targets) features described later. Using TypeScript (with `decorators` support enabled), simply add `@controller` to the top of your class:
Catalyst will automatically convert the classes name; removing the trailing `Element` suffix and lowercasing all capital letters, separating them with a dash.
21
23
22
-
Here are the three key elements to remember:
24
+
By convention, Catalyst controllers end in `Element`, and Catalyst will strip this for the tag name, but the `Element` suffix is not required - just convention. All examples in this guide use `Element` suffixed names.
23
25
24
-
- Custom Elements must have a dash in the name.
25
-
- The JS class must `extend HTMLElement`
26
-
-`connectedCallback` can be used as a life-cycle hook for when the element and class are connected.
Remember! A class name _must_ include at least two CamelCased words (not including the `Element` suffix). One-word elements will raise exceptions. Example of good names: `UserListElement`, `SubTaskElement`, `PagerContainerElement`
27
38
28
-
### Catalyst
39
+
</div>
40
+
</div>
29
41
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:
31
42
32
-
```js
33
-
@controller
43
+
### What does `@controller` do?
44
+
45
+
Catalyst components are really just "Custom Elements", they're doing all the heavy lifting. 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:
Catalyst will automatically convert the classes name; removing the trailing `Element` suffix and lowercasing all capital letters, separating them with a dash.
45
58
46
-
By convention, Catalyst controllers end in `Element`, and Catalyst will strip this for the tag name, but suffixing `Element` is not required. All examples in this guide use `Element` suffixed names.
59
+
The Catalyst version isn't all that different, it's just that we have the `@controller` decorator to save on some of the boilerplate.
47
60
48
-
####What about without Decorators?
61
+
### What about without TypeScript Decorators?
49
62
50
-
If you don't want to use decorators, you can simply wrap the class in a call to `controller`:
63
+
If you don't want to use TypeScript decorators, you can use `controller` as a regular function, and just pass it your class:
0 commit comments