OLD | NEW |
(Empty) | |
| 1 # Custom Elements |
| 2 |
| 3 Custom elements let authors create their own elements, with their own |
| 4 methods, behavior, and attribute handling. Custom elements shipped in |
| 5 M33. We colloquially refer to that version as "v0." |
| 6 |
| 7 Contact Dominic Cooney |
| 8 ([dominicc@chromium.org](mailto:dominicc@chromium.org)) with |
| 9 questions. |
| 10 |
| 11 ## Design |
| 12 |
| 13 ### Some Important Classes |
| 14 |
| 15 ###### CustomElementDefinition |
| 16 |
| 17 The definition of one ‘class’ of element; it consists of a |
| 18 tag name, and a prototype. |
| 19 |
| 20 ###### CustomElementsRegistry |
| 21 |
| 22 Implements the `window.customElements` property. This maintains a list |
| 23 of definitions, and a mapping from constructors to an index in this |
| 24 list. The same map also has indexes as keys and prototypes as values. |
| 25 |
| 26 ###### V8HTMLElement Constructor |
| 27 |
| 28 The `HTMLElement` interface constructor. When a custom element is |
| 29 created from JavaScript all we have to go on is the constructor (in |
| 30 `new.target`); this uses CustomElementRegistry’s map to find |
| 31 which definition and prototype to use. |
| 32 |
| 33 ### Memory Management |
| 34 |
| 35 Once defined, custom element constructors and prototypes have to be |
| 36 kept around indefinitely because they could be created in future by |
| 37 the parser. On the other hand, we must not leak when a window can no |
| 38 longer run script. |
| 39 |
| 40 We use a V8HiddenValue on the CustomElementsRegistry wrapper which |
| 41 points to a map that keeps constructors and prototypes alive. |
| 42 |
| 43 ## Style Guide |
| 44 |
| 45 In comments and prose, write custom elements, not Custom Elements, to |
| 46 match the HTML standard. |
| 47 |
| 48 Prefix type names with CustomElement (singular). The one exception to |
| 49 this rule is CustomElementsRegistry, which uses a plural to match the |
| 50 name of the interface in the specification. |
| 51 |
| 52 ## Testing |
| 53 |
| 54 Custom elements have small C++ unit tests and medium |
| 55 “layout” tests. |
| 56 |
| 57 ###### C++ Unit Tests |
| 58 |
| 59 These are in third_party/WebKit/Source/core/dom/*Test.cpp and are |
| 60 built as part of the webkit_unit_tests target. The test names start |
| 61 with CustomElement so you can run them with: |
| 62 |
| 63 $ out/Debug/webkit_unit_tests --gtest_filter=CustomElement* |
| 64 |
| 65 ###### Layout Tests |
| 66 |
| 67 The custom element layout tests are generally in |
| 68 third_party/WebKit/LayoutTests/custom-elements. |
| 69 |
| 70 All custom elements layout tests use the [W3C web-platform-tests |
| 71 harness](http://testthewebforward.org/docs/) and follow its style. The |
| 72 W3C is not very prescriptive, so be consistent with other custom |
| 73 elements tests. |
| 74 |
| 75 When naming tests, use short names describing what the test is doing. |
| 76 Avoid articles. For example, "HTMLElement constructor, invoke". When |
| 77 writing assertion messages, start with a lowercase letter (unless the |
| 78 word is a proper noun), use normal grammar and articles, and include |
| 79 the word “should” to leave no doubt whate the expected |
| 80 behavior is. |
| 81 |
| 82 ###### Spec Tests |
| 83 |
| 84 These will be upstreamed to the W3C, replacing [the tests for |
| 85 registerElement](https://github.com/w3c/web-platform-tests/commits/master/custom
-elements) |
| 86 we contributed earlier. To facilitate that, follow these guidelines: |
| 87 |
| 88 * Keep the tests together in the `spec` directory. |
| 89 * Only test things required in a spec. The test should permit other |
| 90 possible reasonable implementations. |
| 91 * Avoid using Blink-specific test mechanisms. Don't use |
| 92 `window.internals` for example. |
| 93 |
| 94 ###### Implementation Tests |
| 95 |
| 96 These are for testing Blink-specific details like object lifetimes, |
| 97 crash regressions, interaction with registerElement and HTML Imports, |
| 98 and so on. |
| 99 |
| 100 These tests can use Blink-specific testing hooks like |
| 101 `window.internals` and `testRunner`. |
| 102 |
| 103 ###### Web Exposed Tests |
| 104 |
| 105 Finally there are /TODO(dominicc): should be/ tests in |
| 106 webexposed/custom-elements which assert that we HAVE NOT shipped |
| 107 `window.customElements.define` yet. These tests need to be updated |
| 108 when we ship `window.customElements.define` or remove |
| 109 `registerElement`. |
| 110 |
| 111 ## “V0” Deprecation |
| 112 |
| 113 The plan is to: |
| 114 |
| 115 1. Implement the ‘new’ kind of custom elements separately |
| 116 from the existing implementation. We have renamed all of old |
| 117 implementation so that the type names start with V0; it should be |
| 118 easy to tell whether you are looking at the old or new |
| 119 implementation. |
| 120 1. When we ship `window.customElements.define`, add a deprecation |
| 121 warning to `document.registerElement` directing authors to use the |
| 122 new API. |
| 123 1. Change the ‘web’ API to use the new kind of custom |
| 124 elements. That API is used by extensions to implement the webview |
| 125 tag and things like that. |
| 126 1. When [the use counter for |
| 127 registerElement](https://www.chromestatus.com/metrics/feature/timeline/popula
rity/457) |
| 128 drops below 0.03% of page loads, remove the old implementation. We |
| 129 may remove it even sooner, if we have evidence that sites are using |
| 130 feature detection correctly. |
| 131 |
| 132 ## References |
| 133 |
| 134 These have links to the parts of the DOM and HTML specs which define |
| 135 custom elements: |
| 136 |
| 137 * [WHATWG DOM Wiki: Custom Elements](https://github.com/whatwg/dom/wiki#custom-e
lements) |
| 138 * [WHATWG HTML Wiki: Custom Elements](https://github.com/whatwg/html/wiki#custom
-elements) |
OLD | NEW |