mdn
Issue with "CustomElementRegistry.define()": Documentation needs more concise text and examples.
MDN URL: https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define
What information was incorrect, unhelpful, or incomplete?
The discussions of the class for a web-component custom element, in particular the examples, is chaotic. Some examples illustrate a class without a constructor() method. Others place all the class action inside the constructor() method. Still others place the action in the connectedCallback() method. The existing examples are inconsistent and full of extraneous code trying to construct goofy giant shadow HTML DOMs.
connectedCallback() is not consistently and well described to show that the custom element may be constructed but not fully parsed to make its innerHTML available. The solution to this is difficult to find; it's in the lifecycle discussion, but nowhere is it explained how this is useful, or why this exists in contrast to constructor().
It is further not explained why element.innerHTML, element.innerText, and element.textContent sometimes exist and sometimes don't within the web-component class constructor.
Are we supposed to use customElements or CustomElementRegistry?
CustomElementRegistry.define() ... Parameters
The second parameter of the define() method needs explanation and examples which are less random. Answer these questions for autonomous elements: is a constructor() containing super() required? What parts of the HTML environment are available in the constructor? Is connectedCallback() required to access the HTML? When is it useful? If parsing is delayed after connection, what is the correct way to wait for it to be done? Are we supposed to await a Promise returned by CustomElementRegistry.whenDefined() ? Its definition is difficult to find and it's not easy to see how it should be used.
What did you expect to see?
I expect to find a web-component spec that states the names and purposes of all the methods and all the callbacks of CustomElementRegistry, in one chapter of the MDN API.
I expect to find short examples that show the correct (i.e., as intended by web-component designers) class definition of new elements, so I don't have to figure this out by trial, error, and stackoverflow.
Thanks.
MDN Content page report details
- Folder:
en-us/web/api/customelementregistry/define - MDN URL: https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define
- GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/api/customelementregistry/define/index.md
- Last commit: https://github.com/mdn/content/commit/d3c38334923570ada25766f77212b2e808fdebc5
- Document last modified: 2021-10-15T17:04:17.000Z
FWIW, I arrived at this issue out of my confusion surrounding connectedCallback after reading the MDN "Using Custom Elements" - specifically, the PopUpInfo example.
https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements
The doc says "Inside the method connectedCallback, we define all the functionality the element will have when the element is connected to the DOM... We don't use constructor() because an element's attributes are unavailable until connected to the DOM.".
'connectedCallback' isn't mentioned again until well later in the document, but if you look at the PopUpInfo example and its implementation (where connectedCallback is mentioned for the first time), all of the functionality of the element IS defined in the constructor: https://mdn.github.io/web-components-examples/popup-info-box-web-component/main.js
I'm sure as I learn more, this will click / make more sense, but as someone just getting started with vanilla web components, this reads as if it's contradicting itself (e.g. "Here's a method that must be used to accomplish XYZ - and if you try to do XYZ in the constructor it won't work. Here's an example of us doing it in the constructor - look it works!".)
Agreed. If the component class has a constructor, all necessary element setup should be available in that constructor.
If that's not the intention, then the UA should hold off calling it until conditions are met.
As an aside, explain why a component must extend only HTMLElement and not some other extension like div or span. But a component can extend another component; I tried it.
dave mausner. +1-312-925-3694. Rem tene, verba sequentur. (Cato) Just show me the code. (Dave)
On Tue, Aug 9, 2022, 06:00 Matt Ezell @.***> wrote:
FWIW, I arrived at this issue out of my confusion surrounding connectedCallback after reading the MDN "Using Custom Elements" - specifically, the PopUpInfo example.
https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements
The doc says "Inside the method connectedCallback, we define all the functionality the element will have when the element is connected to the DOM... We don't use constructor() because an element's attributes are unavailable until connected to the DOM.".
'connectedCallback' isn't mentioned again until well later in the document, but if you look at the PopUpInfo example and its implementation (where connectedCallback is mentioned for the first time), all of the functionality of the element IS defined in the constructor: https://mdn.github.io/web-components-examples/popup-info-box-web-component/main.js
I'm sure as I learn more, this will click / make more sense, but as someone just getting started with vanilla web components, this reads as if it's contradicting itself (e.g. "Here's a method that must be used to accomplish XYZ - and if you try to do XYZ in the constructor it won't work. Here's an example of us doing it in the constructor - look it works!".)
— Reply to this email directly, view it on GitHub https://github.com/mdn/content/issues/11225#issuecomment-1209232483, or unsubscribe https://github.com/notifications/unsubscribe-auth/AB7KS5HBPIE4B67EN3H7DUDVYI25NANCNFSM5KCVTBFQ . You are receiving this because you authored the thread.Message ID: @.***>