Google Git
Sign in
chromium / chromium / src / 4b7f2d40ed547f844c3b42b712f035e90357e1e5 / . / third_party / WebKit / Source / core / html / custom
tree: 78e98eb305b7f7d9c9ab79d0b144b46a77e7d4d7 [path history] [tgz]
  1. CEReactionsScope.cpp
  2. CEReactionsScope.h
  3. CustomElement.cpp
  4. CustomElement.h
  5. CustomElementAdoptedCallbackReaction.cpp
  6. CustomElementAdoptedCallbackReaction.h
  7. CustomElementAttributeChangedCallbackReaction.cpp
  8. CustomElementAttributeChangedCallbackReaction.h
  9. CustomElementConnectedCallbackReaction.cpp
  10. CustomElementConnectedCallbackReaction.h
  11. CustomElementDefinition.cpp
  12. CustomElementDefinition.h
  13. CustomElementDefinitionBuilder.h
  14. CustomElementDefinitionTest.cpp
  15. CustomElementDescriptor.h
  16. CustomElementDescriptorHash.h
  17. CustomElementDescriptorTest.cpp
  18. CustomElementDisconnectedCallbackReaction.cpp
  19. CustomElementDisconnectedCallbackReaction.h
  20. CustomElementReaction.cpp
  21. CustomElementReaction.h
  22. CustomElementReactionQueue.cpp
  23. CustomElementReactionQueue.h
  24. CustomElementReactionQueueTest.cpp
  25. CustomElementReactionStack.cpp
  26. CustomElementReactionStack.h
  27. CustomElementReactionStackTest.cpp
  28. CustomElementReactionTestHelpers.h
  29. CustomElementRegistry.cpp
  30. CustomElementRegistry.h
  31. CustomElementRegistry.idl
  32. CustomElementRegistryTest.cpp
  33. CustomElementTest.cpp
  34. CustomElementTestHelpers.cpp
  35. CustomElementTestHelpers.h
  36. CustomElementUpgradeReaction.cpp
  37. CustomElementUpgradeReaction.h
  38. CustomElementUpgradeSorter.cpp
  39. CustomElementUpgradeSorter.h
  40. CustomElementUpgradeSorterTest.cpp
  41. README.md
  42. V0CustomElement.cpp
  43. V0CustomElement.h
  44. V0CustomElementAsyncImportMicrotaskQueue.cpp
  45. V0CustomElementAsyncImportMicrotaskQueue.h
  46. V0CustomElementCallbackInvocation.cpp
  47. V0CustomElementCallbackInvocation.h
  48. V0CustomElementCallbackQueue.cpp
  49. V0CustomElementCallbackQueue.h
  50. V0CustomElementDefinition.cpp
  51. V0CustomElementDefinition.h
  52. V0CustomElementDescriptor.h
  53. V0CustomElementDescriptorHash.h
  54. V0CustomElementException.cpp
  55. V0CustomElementException.h
  56. V0CustomElementLifecycleCallbacks.h
  57. V0CustomElementMicrotaskDispatcher.cpp
  58. V0CustomElementMicrotaskDispatcher.h
  59. V0CustomElementMicrotaskImportStep.cpp
  60. V0CustomElementMicrotaskImportStep.h
  61. V0CustomElementMicrotaskQueueBase.cpp
  62. V0CustomElementMicrotaskQueueBase.h
  63. V0CustomElementMicrotaskResolutionStep.cpp
  64. V0CustomElementMicrotaskResolutionStep.h
  65. V0CustomElementMicrotaskRunQueue.cpp
  66. V0CustomElementMicrotaskRunQueue.h
  67. V0CustomElementMicrotaskStep.h
  68. V0CustomElementObserver.cpp
  69. V0CustomElementObserver.h
  70. V0CustomElementProcessingStack.cpp
  71. V0CustomElementProcessingStack.h
  72. V0CustomElementProcessingStep.h
  73. V0CustomElementRegistrationContext.cpp
  74. V0CustomElementRegistrationContext.h
  75. V0CustomElementRegistry.cpp
  76. V0CustomElementRegistry.h
  77. V0CustomElementScheduler.cpp
  78. V0CustomElementScheduler.h
  79. V0CustomElementSyncMicrotaskQueue.cpp
  80. V0CustomElementSyncMicrotaskQueue.h
  81. V0CustomElementUpgradeCandidateMap.cpp
  82. V0CustomElementUpgradeCandidateMap.h
third_party/WebKit/Source/core/html/custom/README.md

Custom Elements

Custom elements let authors create their own elements, with their own methods, behavior, and attribute handling. Custom elements shipped in M33. We colloquially refer to that version as “v0.”

Contact Dominic Cooney (dominicc@chromium.org) with questions.

Code Location

The custom elements implementation is split between core/dom and bindings/core/v8.

Design

Some Important Classes

CustomElementDefinition

The definition of one ‘class’ of element. This type is abstract to permit different kinds of definitions, although at the moment there is only one: ScriptCustomElementDefinition.

ScriptCustomElementDefinition is linked to its constructor by an ID number. The ID number is stored in a map, keyed by constructor, in a hidden value of the CustomElementRegistry wrapper. The ID is an index into a list of definitions stored in V8PerContextData.

CustomElementDescriptor

A tuple of local name, and custom element name. For autonomous custom elements, these strings are the same; for customized built-in elements these strings will be different. In that case, the local name is the element's tag name and the custom element name is related to the value of the “is” attribute.

CustomElementRegistry

Implements the window.customElements property. This maintains the set of registered names. The wrapper of this object is used by ScriptCustomElementDefinition to cache state in V8.

V8HTMLElement Constructor

The HTMLElement interface constructor. When a custom element is created from JavaScript all we have to go on is the constructor (in new.target); this uses ScriptCustomElementDefinition's state to find the definition to use.

Memory Management

Once defined, custom element constructors and prototypes have to be kept around indefinitely because they could be created in future by the parser. On the other hand, we must not leak when a window can no longer run script.

We use a V8HiddenValue on the CustomElementRegistry wrapper which points to a map that keeps constructors and prototypes alive. See ScriptCustomElementDefinition.

Style Guide

In comments and prose, write custom elements, not Custom Elements, to match the HTML standard.

Prefix type names with CustomElement (singular).

Testing

Custom elements have small C++ unit tests and medium “layout” tests.

C++ Unit Tests

These are in third_party/WebKit/Source/core/dom/*Test.cpp and are built as part of the webkit_unit_tests target. The test names start with CustomElement so you can run them with:

$ out/Debug/webkit_unit_tests --gtest_filter=CustomElement*
Layout Tests

The custom element layout tests are generally in third_party/WebKit/LayoutTests/custom-elements.

All custom elements layout tests use the W3C web-platform-tests harness and follow its style. The W3C is not very prescriptive, so be consistent with other custom elements tests.

When naming tests, use short names describing what the test is doing. Avoid articles. For example, “HTMLElement constructor, invoke”. When writing assertion messages, start with a lowercase letter (unless the word is a proper noun), use normal grammar and articles, and include the word “should” to leave no doubt whate the expected behavior is.

Spec Tests

These will be upstreamed to the W3C, replacing the tests for registerElement we contributed earlier. To facilitate that, follow these guidelines:

  • Keep the tests together in the spec directory.
  • Only test things required in a spec. The test should permit other possible reasonable implementations.
  • Avoid using Blink-specific test mechanisms. Don't use window.internals for example.
Implementation Tests

These are for testing Blink-specific details like object lifetimes, crash regressions, interaction with registerElement and HTML Imports, and so on.

These tests can use Blink-specific testing hooks like window.internals and testRunner.

Web Exposed Tests

Finally there are /TODO(dominicc): should be/ tests in webexposed/custom-elements which assert that we HAVE NOT shipped window.customElements.define yet. These tests need to be updated when we ship window.customElements.define or remove registerElement.

“V0” Deprecation

The plan is to:

  1. Implement the ‘new’ kind of custom elements separately from the existing implementation. We have renamed all of old implementation so that the type names start with V0; it should be easy to tell whether you are looking at the old or new implementation.
  2. When we ship window.customElements.define, add a deprecation warning to document.registerElement directing authors to use the new API.
  3. Change the ‘web’ API to use the new kind of custom elements. That API is used by extensions to implement the webview tag and things like that.
  4. When the use counter for registerElement drops below 0.03% of page loads, remove the old implementation. We may remove it even sooner, if we have evidence that sites are using feature detection correctly.

References

These have links to the parts of the DOM and HTML specs which define custom elements: