third_party/WebKit/Source/core/dom/custom/README.md - Issue 2277713002: Rename CustomElementsRegistry to CustomElementRegistry

Side by Side Diff: third_party/WebKit/Source/core/dom/custom/README.md

Issue 2277713002: Rename CustomElementsRegistry to CustomElementRegistry (Closed) Base URL: https://chromium.googlesource.com/chromium/src.git@master

Patch Set: rebase Created 4 years, 3 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View unified diff | Download patch

« no previous file with comments | « third_party/WebKit/Source/core/dom/custom/CustomElementsRegistryTest.cpp ('k') | third_party/WebKit/Source/core/dom/custom/V0CustomElementRegistrationContext.h » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Hide Comments ('s')

OLD	NEW
1 # Custom Elements	1 # Custom Elements

2	2

3 Custom elements let authors create their own elements, with their own	3 Custom elements let authors create their own elements, with their own

4 methods, behavior, and attribute handling. Custom elements shipped in	4 methods, behavior, and attribute handling. Custom elements shipped in

5 M33. We colloquially refer to that version as "v0."	5 M33. We colloquially refer to that version as "v0."

6	6

7 Contact Dominic Cooney	7 Contact Dominic Cooney

8 ([dominicc@chromium.org](mailto:dominicc@chromium.org)) with	8 ([dominicc@chromium.org](mailto:dominicc@chromium.org)) with

9 questions.	9 questions.

10	10

11 ### Code Location	11 ### Code Location

12	12

13 The custom elements implementation is split between core/dom and	13 The custom elements implementation is split between core/dom and

14 bindings/core/v8.	14 bindings/core/v8.

15	15

16 ## Design	16 ## Design

17	17

18 ### Some Important Classes	18 ### Some Important Classes

19	19

20 ###### CustomElementDefinition	20 ###### CustomElementDefinition

21	21

22 The definition of one ‘class’ of element. This type is	22 The definition of one ‘class’ of element. This type is

23 abstract to permit different kinds of definitions, although at the	23 abstract to permit different kinds of definitions, although at the

24 moment there is only one: ScriptCustomElementDefinition.	24 moment there is only one: ScriptCustomElementDefinition.

25	25

26 ScriptCustomElementDefinition is linked to its constructor by an ID	26 ScriptCustomElementDefinition is linked to its constructor by an ID

27 number. The ID number is stored in a map, keyed by constructor, in a	27 number. The ID number is stored in a map, keyed by constructor, in a

28 hidden value of the CustomElementsRegistry wrapper. The ID is an index	28 hidden value of the CustomElementRegistry wrapper. The ID is an index

29 into a list of definitions stored in V8PerContextData.	29 into a list of definitions stored in V8PerContextData.

30	30

31 ###### CustomElementDescriptor	31 ###### CustomElementDescriptor

32	32

33 A tuple of local name, and custom element name. For autonomous custom	33 A tuple of local name, and custom element name. For autonomous custom

34 elements, these strings are the same; for customized built-in elements	34 elements, these strings are the same; for customized built-in elements

35 these strings will be different. In that case, the local name is the	35 these strings will be different. In that case, the local name is the

36 element's tag name and the custom element name is related to the value	36 element's tag name and the custom element name is related to the value

37 of the “is” attribute.	37 of the “is” attribute.

38	38

39 ###### CustomElementsRegistry	39 ###### CustomElementRegistry

40	40

41 Implements the `window.customElements` property. This maintains the	41 Implements the `window.customElements` property. This maintains the

42 set of registered names. The wrapper of this object is used by	42 set of registered names. The wrapper of this object is used by

43 ScriptCustomElementDefinition to cache state in V8.	43 ScriptCustomElementDefinition to cache state in V8.

44	44

45 ###### V8HTMLElement Constructor	45 ###### V8HTMLElement Constructor

46	46

47 The `HTMLElement` interface constructor. When a custom element is	47 The `HTMLElement` interface constructor. When a custom element is

48 created from JavaScript all we have to go on is the constructor (in	48 created from JavaScript all we have to go on is the constructor (in

49 `new.target`); this uses ScriptCustomElementDefinition's state to find	49 `new.target`); this uses ScriptCustomElementDefinition's state to find

50 the definition to use.	50 the definition to use.

51	51

52 ### Memory Management	52 ### Memory Management

53	53

54 Once defined, custom element constructors and prototypes have to be	54 Once defined, custom element constructors and prototypes have to be

55 kept around indefinitely because they could be created in future by	55 kept around indefinitely because they could be created in future by

56 the parser. On the other hand, we must not leak when a window can no	56 the parser. On the other hand, we must not leak when a window can no

57 longer run script.	57 longer run script.

58	58

59 We use a V8HiddenValue on the CustomElementsRegistry wrapper which	59 We use a V8HiddenValue on the CustomElementRegistry wrapper which

60 points to a map that keeps constructors and prototypes alive. See	60 points to a map that keeps constructors and prototypes alive. See

61 ScriptCustomElementDefinition.	61 ScriptCustomElementDefinition.

62	62

63 ## Style Guide	63 ## Style Guide

64	64

65 In comments and prose, write custom elements, not Custom Elements, to	65 In comments and prose, write custom elements, not Custom Elements, to

66 match the HTML standard.	66 match the HTML standard.

67	67

68 Prefix type names with CustomElement (singular). The one exception to	68 Prefix type names with CustomElement (singular).

69 this rule is CustomElementsRegistry, which uses a plural to match the

70 name of the interface in the specification.

71	69

72 ## Testing	70 ## Testing

73	71

74 Custom elements have small C++ unit tests and medium	72 Custom elements have small C++ unit tests and medium

75 “layout” tests.	73 “layout” tests.

76	74

77 ###### C++ Unit Tests	75 ###### C++ Unit Tests

78	76

79 These are in third_party/WebKit/Source/core/dom/*Test.cpp and are	77 These are in third_party/WebKit/Source/core/dom/*Test.cpp and are

80 built as part of the webkit_unit_tests target. The test names start	78 built as part of the webkit_unit_tests target. The test names start

(...skipping 68 matching lines...) Expand 10 before \| Expand all \| Expand 10 after Loading...
149 may remove it even sooner, if we have evidence that sites are using	147 may remove it even sooner, if we have evidence that sites are using

150 feature detection correctly.	148 feature detection correctly.

151	149

152 ## References	150 ## References

153	151

154 These have links to the parts of the DOM and HTML specs which define	152 These have links to the parts of the DOM and HTML specs which define

155 custom elements:	153 custom elements:

156	154

157 * [WHATWG DOM Wiki: Custom Elements](https://github.com/whatwg/dom/wiki#custom-e lements)	155 * [WHATWG DOM Wiki: Custom Elements](https://github.com/whatwg/dom/wiki#custom-e lements)

158 * [WHATWG HTML Wiki: Custom Elements](https://github.com/whatwg/html/wiki#custom -elements)	156 * [WHATWG HTML Wiki: Custom Elements](https://github.com/whatwg/html/wiki#custom -elements)

OLD	NEW