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