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: doc/dom_reg/_Reg.md
+28-6Lines changed: 28 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,21 +1,43 @@
1
1
Registry for custom DOM element classes. Automatically derives tag name from class name, using salting when necessary to avoid collisions. Supports idempotent registration which can be safely called in an element constructor. Allows immediate registration, deferred registration, or a mix of those.
2
2
3
-
By default, this registry has **no global side effects**. To enable global registration, provide a "definer" to the registry.
3
+
By default, the main registry uses `globalThis.customElements`, which exists only in browser environments. In non-browser environments, by default it has no global side effects, but does still modify registered classes by deriving their `.customName`, for rendering to HTML.
4
+
5
+
For browser-only code, prefer the mixin `MixReg` from the same module which is easier to use. See examples in the {{featLink dom_reg readme}}.
6
+
7
+
Simple usage:
4
8
5
9
```js
6
10
import*asdrfrom'{{featUrl dom_reg}}'
7
11
8
12
classBtnextendsHTMLButtonElement {
9
-
// Optional. If omitted, `dr.reg` autogenerates
10
-
// this from the name of the class.
11
-
static customName =`some-btn`
13
+
/*
14
+
Optional. If omitted, `dr.reg` autogenerates
15
+
this from the name of the class.
16
+
17
+
static customName = `some-btn`
18
+
*/
19
+
20
+
// Automatically derives the name `a-btn` and registers the class.
21
+
static {dr.reg(this)}
22
+
}
23
+
24
+
document.body.append(newBtn())
25
+
```
26
+
27
+
You can unset the default definer to defer registration:
12
28
29
+
```js
30
+
import*asdrfrom'{{featUrl dom_reg}}'
31
+
32
+
dr.Reg.main.setDefiner()
33
+
34
+
classBtnextendsHTMLButtonElement {
13
35
// Registers `Btn` in `dr.Reg.main`,
14
-
// but NOT in `window.customElements`.
36
+
// but not in `window.customElements` quite yet.
15
37
static {dr.reg(this)}
16
38
}
17
39
18
-
// The element is NOT yet upgraded to our custom class.
40
+
// The element is not yet upgraded to our custom class.
Apps which use server-side rendering and client-side upgrading of custom elements need a slightly different approach. `MixReg` registers an element class at construction time, when the class is invoked with `new`. Custom elements described in HTML markup are initially not associated with any class, and so the browser wouldn't know what to `new`.
63
+
64
+
Instead, use `dr.reg`, which is also used internally by `MixReg`. This is simply a shortcut for using the {{link dom_reg Reg default registry}} provided by this module.
65
+
66
+
```js
67
+
import*asdrfrom'{{featUrl dom_reg}}'
68
+
69
+
classBtnextendsHTMLButtonElement {
70
+
/*
71
+
Optional. If omitted, `dr.reg` autogenerates
72
+
this from the name of the class.
73
+
74
+
static customName = `some-btn`
75
+
*/
76
+
77
+
// Automatically derives the name `a-btn` and registers the class.
Variant of [#`Bmap`](#class-bmap) with support for key and value checks. Subclasses must override methods `.reqKey` and `.reqVal`. These methods are automatically called by `.set`. Method `.reqKey` must validate and return the given key, and method `.reqVal` must validate and return the given value. Use type assertions provided by [`lang`](lang_readme.md).
Apps which use server-side rendering and client-side upgrading of custom elements need a slightly different approach. `MixReg` registers an element class at construction time, when the class is invoked with `new`. Custom elements described in HTML markup are initially not associated with any class, and so the browser wouldn't know what to `new`.
65
+
66
+
Instead, use `dr.reg`, which is also used internally by `MixReg`. This is simply a shortcut for using the [#default](#class-reg) provided by this module.
Registry for custom DOM element classes. Automatically derives tag name from class name, using salting when necessary to avoid collisions. Supports idempotent registration which can be safely called in an element constructor. Allows immediate registration, deferred registration, or a mix of those.
78
101
79
-
By default, this registry has **no global side effects**. To enable global registration, provide a "definer" to the registry.
102
+
By default, the main registry uses `globalThis.customElements`, which exists only in browser environments. In non-browser environments, by default it has no global side effects, but does still modify registered classes by deriving their `.customName`, for rendering to HTML.
103
+
104
+
For browser-only code, prefer the mixin `MixReg` from the same module which is easier to use. See examples in the [readme](dom_reg_readme.md).
0 commit comments