?Custom made Factors
Abstract
This specification describes the method for enabling the author to define and use new forms of DOM things inside of a document. It is known as a copy from the relevant parts of [ HTML ] up through commit 81ee034f316f4366aeb315d16ea21521c83ab427 and [ WHATWG-DOM ] through commit cb85ac4c35baa1345f2b71e2dd3d57b098ddf2d1. Section titles are prefixed with "HTML:" or "DOM:" to indicate which spec they copy from.
Status of This Document
This section describes the status of this document within the time of its publication. Other documents may supersede this document. A list of active W3C publications additionally, the latest revision of this technical report could in fact be found during the W3C technical reports index at https://www.w3.org/TR/.
This document was published by the Word wide web System Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you want to make comments regarding this document, please send them to public-webapps@w3.org (subscribe. archives ) with [custom-elements] within the get started with of your email's subject. All comments are welcome.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is regarded as a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than function in progress.
This document was produced by a group operating beneath the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in link with the deliverables in the group; that web site also consists of instructions for disclosing a patent. An individual who has actual knowledge of the patent which the individual believes possesses Essential Claim(s) must disclose the info in accordance with section 6 with the W3C Patent Policy.
This document is governed by the 1 September 2015 W3C Practice Document.
Table of Contents
1. Conformance
Likewise as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes within this specification are non-normative. Everything else during this specification is normative.
Any point, at which a conforming UA must make decisions about the state or reaction to the state in the conceptual product, is captured as algorithm. The algorithms are defined in terms of processing equivalence. The processing equivalence is mostly a constraint imposed around the algorithm implementors, requiring the output of your each UA-implemented as well as the specified algorithm to be exactly the same for all inputs.
The IDL fragments in this particular specification must be interpreted as required for conforming IDL fragments, as described with the Word wide web IDL specification [ WEBIDL ].
two. HTML: Custom made parts
two.1 Introduction
This section is non-normative.
Tailor made things deliver a way for authors to construct their private fully-featured DOM components. Although authors could always use non-standard factors in their documents, with application-specific behaviour extra after the fact by scripting or similar, this kind of factors have historically been non-conforming and not very functional. By defining a personalized element, authors can inform the parser how to properly construct an element and how aspects of that class should react to changes.
Personalized parts are part of the larger effort to "rationalise the platform", by explaining present system benefits (like the aspects of HTML) in terms of lower-level author-exposed extensibility points (like custom made element definition). Although today there are nearly all limitations in the abilities of tailor made elements-both functionally and semantically-that prevent them from fully explaining the behaviours of HTML's current parts, we hope to shrink this gap over time.
two.1.1 Setting up an autonomous customized element
This section is non-normative.
For your purposes of illustrating how to build an autonomous custom made element. let's define a customized element that encapsulates rendering a smallish icon for a country flag. Our goal is to be able to try it like so:
To do this, we to begin with declare a class with the custom made element, extending HTMLElement :
We then really need to employ this class to define the element:
At this point, our higher than code will job! The parser, whenever it sees the flag-icon tag, will construct a new instance of our FlagIcon class, and tell our code about its new country attribute, which we then use to established the element's internal state and update its rendering (when acceptable).
It is possible to also generate flag-icon things choosing the DOM API:
Finally, we could also utilize the tailor made element constructor itself. That is definitely, the higher than code is equivalent to:
two.1.two Constructing a customized built-in element
This section is non-normative.
Customized built-in features are a distinct kind of tailor made element. which are defined slightly differently and made use of very differently compared to autonomous customized aspects. They exist to allow for reuse of behaviours from the current factors of HTML, by extending those parts with new custom made performance. This is important since a variety of on the present behaviours of HTML factors can unfortunately not be duplicated by utilising purely autonomous personalized aspects. Instead, customized built-in features make it easy for the installation of customized construction behaviour, lifecycle hooks, and prototype chain onto current parts, essentially "mixing in" these abilities on top within the already-existing element.
Customized built-in features require a distinct syntax from autonomous tailor made components since consumer agents and other software key off an element's local name in order to identify the element's semantics and behaviour. That is definitely, the concept of customized built-in factors generating on top of current behaviour is dependent crucially in the extended components retaining their original local name.
In this particular example, we'll be crafting a customized built-in element named plastic-button. which behaves like a normal button but gets fancy animation effects extra whenever you click on it. We get started with by defining a class, just like before, although this time we lengthen HTMLButtonElement instead of HTMLElement :
When defining our tailor made element, we need to also specify the extends option:
In general, the name from the element being extended cannot be determined simply by hunting at what element interface it extends, as quite a few components share the same interface (this sort of as q and blockquote each sharing HTMLQuoteElement ).
Trying to try a customized built-in element as an autonomous tailor made element will not deliver the results; that's, <plastic-button>Click me?</plastic-button> will simply construct an HTMLElement with no special behaviour.
In the event you desire to produce a type-extended element programmatically, you can still utilize the following type of createElement() :
And as before, the constructor will also deliver the results:
Notably, all the of your ways in which button is special apply to this kind of "plastic buttons" in addition: their focus behaviour, ability to participate in kind submission. the disabled attribute, and so on.
two.1.3 Negatives of autonomous customized features
This section is non-normative.
As specified below, and alluded to previously mentioned, simply defining and by using an element called taco-button does not mean that like aspects represent buttons. That's, resources these types of as Word wide web browsers, search engines, or accessibility technological innovation will not quickly treat the resulting element as a button just according to its defined name.
To convey the desired button semantics into a assortment of buyers, even when continue to by making use of an autonomous personalized element. quite a few techniques would desire to be employed:
The addition on the tabindex attribute would make the taco-button interactive content. thus making it focusable. Note that if the taco-button were being to become logically disabled, the tabindex attribute would must have to be removed.
The addition of unique ARIA attributes helps convey semantics to accessibility engineering. For example, setting the role attribute to " button " will convey the semantics that this really is a button, enabling customers to successfully interact with the control making use of usual button-like interactions in their accessibility engineering. Setting the aria-label attribute is necessary to give the button an accessible name. instead of having accessibility technological know-how traverse its child textual content nodes and announce them. And setting aria-disabled to " true " once the button is logically disabled conveys to accessibility technological know-how the button's disabled state.
The addition of event handlers to handle commonly-expected button behaviours helps convey the semantics in the button to Net browser people. Within this case, one of the most relevant event handler would be one particular that proxies ideal keydown events to become click events, so that you simply can activate the button the two with keyboard and by clicking.
Moreover to any default visible styling provided for taco-button factors, the visible styling will also require to be updated to reflect changes in rational state, these kinds of as becoming disabled; that's, whatever stylesheet has rules for taco-button will also might need to have rules for taco-button[disabled] .
With these points in mind, a full-featured taco-button that took around the responsibility of conveying button semantics (such as the ability to be disabled) would probably search something like this:
Even with this rather-complicated element definition, the element is not really a pleasure to employ for consumers: it will be continually "sprouting" tabindex and aria-* attributes of its have volition. This is when you consider that as of now there isn't any way to specify default accessibility semantics or focus behaviour for custom made aspects, forcing the use of these attributes to do so (even though they are usually reserved for allowing the consumer to override default behaviour).
In contrast, a common customized built-in element. as proven during the previous section, would immediately inherit the semantics and behaviour for the button element, with no need to have to implement these behaviours manually. In general, for any components with nontrivial behaviour and semantics that grow on top of current components of HTML, customized built-in factors will be easier to create, retain, and consume.
two.1.four Upgrading factors after their generation
This section is non-normative.
As a result of element definition can occur at any time, a non-custom element could be created. and then later become a custom made element after an ideal definition is registered. We call this procedure "upgrading" the element, from the normal element into a customized element.
Upgrades help scenarios where it may be preferable for tailor made element definitions to be registered after relevant things has actually been initially created, these kinds of as by the parser. They make it possible for progressive enhancement belonging to the content from the tailor made element. For example, around the following HTML document the element definition for img-viewer is loaded asynchronously:
The definition for your img-viewer element below is loaded employing a script element marked with the async attribute, placed after the <img-viewer> tag inside the markup. Even while the script is loading, the img-viewer element will be treated as an undefined element, similar to the span. Once the script loads, it will define the img-viewer element, plus the current img-viewer element about the web page will be upgraded, applying the custom made element's definition (which presumably consists of applying an image filter identified by the string "Kelvin", enhancing the image's visible appearance).
Note that upgrades only apply to features while in the document tree. (Formally, components that are connected .) An element that may be not inserted into a document will stay un-upgraded. An example illustrates this point:
two.two Prerequisites for custom made element constructors
When authoring personalized element constructors. authors are bound by the following conformance necessities:
A parameter-less call to super() must be the number one statement inside the constructor body, to establish the correct prototype chain and this value before any further code is run.
A return statement must not appear wherever inside the constructor body, unless it is often a uncomplicated early-return ( return or return this ).
The element's attributes and children must not be inspected, as inside non-upgrade case none will be current, and relying on upgrades makes the element less usable.
The element must not gain any attributes or children, as this violates the expectations of consumers who utilize the createElement or createElementNS methods.
In general, perform should be deferred to connectedCallback as a lot of as possible-especially function involving fetching resources or rendering. However, note that connectedCallback is often called much more than once, so any initialization job which is truly one-time will must have a guard to prevent it from managing twice.
In general, the constructor should be utilised to create initial state and default values, and to create event listeners and possibly a shadow root .
Several of these standards are checked during element generation. either directly or indirectly, and failing to follow them will result within a tailor made element that cannot be instantiated by the parser or DOM APIs.
two.3 Core concepts
A personalized element is surely an element that may be personalized. Informally, this will mean that its constructor and prototype are defined by the author, instead of by the consumer agent. This author-supplied constructor operate is called the customized element constructor .
Two distinct sorts of personalized things might be defined:
An autonomous tailor made element. which is defined with no extends option. These kinds of custom made parts have a local name equal to their defined name .
A customized built-in element. which is defined with the extends option. These varieties of custom made things have local name equal to the value passed in their extends option, and their defined name is employed because the value with the is attribute.
After a personalized element is created. changing the value in the is attribute does not change the element's behaviour, as it is saved relating to the element as its is value .
Autonomous custom made things have the following element definition:
An autonomous tailor made element does not have any special meaning: it represents its children. A customized built-in element inherits the semantics belonging to the element that it extends.
Any namespace-less attribute that is definitely relevant to the element's functioning, as determined by the element's author, may be specified on an autonomous customized element. so very long given that the attribute name is XML-compatible and possesses no uppercase ASCII letters. The exception is the is attribute, which must not be specified on an autonomous personalized element (and that can have no effect if it is).
Customized built-in aspects follow the normal prerequisites for attributes, determined by the things they increase. To incorporate personalized attribute-based behavior, use data-* attributes.
A valid personalized element name serves as a sequence of characters name that meets all of your following prerequisites:
PotentialCustomElementName. = [a-z] (PCENChar )* '-' (PCENChar )* PCENChar. = "-" | "." | [0-9] | "_" | [a-z] | #xB7 | [#xC0-#xD6] | [#xD8-#xF6] | [#xF8-#x37D] | [#x37F-#x1FFF] | [#x200C-#x200D] | [#x203F-#x2040] | [#x2070-#x218F] | [#x2C00-#x2FEF] | [#x3001-#xD7FF] | [#xF900-#xFDCF] | [#xFDF0-#xFFFD] | [#x10000-#xEFFFF]
This makes use of the EBNF notation from the XML specification. [ XML ]
name must not be any for the following:
annotation-xml
color-profile
font-face
font-face-src
font-face-uri
font-face-format
font-face-name
missing-glyph
The list of names earlier mentioned is the summary of all hyphen-containing element names from the applicable specifications. namely SVG and MathML. [ SVG ] [ MATHML ]
These conditions ensure quite a few goals for valid personalized element names :
They get started with that has a lowercase ASCII letter. ensuring that the HTML parser will treat them as tags instead of as textual content.
They do not contain any uppercase ASCII letters. ensuring that the consumer agent can always treat HTML components ASCII-case-insensitively.
They contain a hyphen, useful for namespacing and to ensure forward compatibility (since no aspects will be included to HTML, SVG, or MathML with hyphen-containing local names during the foreseeable future).
They can always be created with createElement() and createElementNS(). which have restrictions that go beyond the parser's.
Apart from these restrictions, a big number of names is allowed, to give maximum flexibility for use cases like <math-?> or <emotion-??> .
A custom made element definition describes a personalized element and consists of:
A name A valid personalized element name A local name A local name A constructor A customized element constructor A prototype A JavaScript object A list of observed attributes A sequence<DOMString> A collection of lifecycle callbacks A map, whose four keys are the strings " connectedCallback ", " disconnectedCallback ", " adoptedCallback ", and " attributeChangedCallback ". The corresponding values are either an online IDL Perform callback perform type value, or null. By default the value of each and every entry is null. A construction stack A list, initially empty, that may be manipulated by the upgrade an element algorithm and also the HTML element constructors. Each individual entry during the list will be either an element or an previously constructed marker.
To appear up a personalized element definition. given a document. namespace. localName. and is. perform the following steps. They will return either a personalized element definition or null:
If namespace will not be the HTML namespace. return null.
If document does not have a browsing context. return null.
two.four The CustomElementRegistry interface
Every single Window object is associated by using a unique instance of the CustomElementRegistry object, allocated if the Window object is created.
Custom made element registries are associated with Window objects, instead of Document objects, since every custom made element constructor inherits from the HTMLElement interface, and you will find exactly one particular HTMLElement interface for each Window object.
The customElements attribute belonging to the Window interface must return the CustomElementRegistry object for that Window object.
Every CustomElementRegistry has a list of customized element definitions. initially empty. In general, algorithms in this particular specification appearance up things inside of the registry by any of name. local name. or constructor .
Every CustomElementRegistry also has an element definition is jogging flag which is employed to prevent reentrant invocations of element definition. It is initially unset.
Every CustomElementRegistry also has a when-defined promise map. mapping valid customized element names to claims. It is utilised to implement the whenDefined() method.
window. customElements. define ( name. constructor ) Defines a new custom made element. mapping the given name to the given constructor as an autonomous customized element. window. customElements. define ( name. constructor. ) Defines a new customized element. mapping the given name to the given constructor as a customized built-in element for your element type identified by the supplied baseLocalName. A " NotSupportedError " DOMException will be thrown upon trying to increase a tailor made element or an unknown element. window. customElements. get ( name ) Retrieves the personalized element constructor defined with the given name. Returns undefined if there isn't a tailor made element definition with the given name. window. customElements. whenDefined ( name ) Returns a promise that will be fulfilled when a tailor made element becomes defined with the given name. (If these a tailor made element is by now defined, the returned promise will be immediately fulfilled.) Returns a promise rejected that has a " SyntaxError " DOMException if not given a valid tailor made element name.
Element definition is mostly a course of action of adding a customized element definition to the CustomElementRegistry. This is accomplished by the define() method. When invoked, the define( name. constructor. solutions ) method must run these steps:
If IsConstructor ( constructor ) is false, then throw a TypeError and abort these steps.
Let interface be the element interface for localName and namespace .
Established result to the new element that implements interface. with no attributes, namespace established to namespace. namespace prefix established to prefix. local name established to localName. customized element state established to " uncustomized ", custom made element definition established to null, is value established to is. and node document established to document .
If namespace is the HTML namespace. and either localName may be a valid customized element name or is is non-null, then established result ’s tailor made element state to " undefined ".
To change an attribute attribute from an element element to value. run these steps:
Queue a mutation record of " attributes " for element with name attribute ’s local name. namespace attribute ’s namespace. and oldValue attribute ’s value.
If element is tailor made. then enqueue a customized element callback reaction with element. callback name " attributeChangedCallback ", and an argument list containing attribute ’s local name. attribute ’s value. value. and attribute ’s namespace.
To append an attribute attribute to an element element. run these steps:
Queue a mutation record of " attributes " for element with name attribute ’s local name. namespace attribute ’s namespace. and oldValue null.
If element is custom made. then enqueue a custom made element callback reaction with element. callback name " attributeChangedCallback ", and an argument list containing attribute ’s local name. null, attribute ’s value. and attribute ’s namespace.
To remove an attribute attribute from an element element. run these steps:
Queue a mutation record of " attributes " for element with name attribute ’s local name. namespace attribute ’s namespace. and oldValue attribute ’s value.
If element is personalized. then enqueue a custom made element callback reaction with element. callback name " attributeChangedCallback ", and an argument list containing attribute ’s local name. attribute ’s value. null, and attribute ’s namespace.
To replace an attribute oldAttr by an attribute newAttr in an element element. run these steps:
Queue a mutation record of " attributes " for element with name oldAttr ’s local name. namespace oldAttr ’s namespace. and oldValue oldAttr ’s value .
Replace oldAttr by newAttr around the element ’s attribute list .
Established oldAttr ’s element to null.
Established newAttr ’s element to element .
four.8 DOM: Cloning
To clone a node. using an optional document and clone children flag . run these steps:
If document isn't really given, let document be node ’s node document .
If node can be an element. then:
Let copy be the result of forming an element. given document. node ’s local name. node ’s namespace. node ’s namespace prefix. together with the value of node ’s is attribute if current (or null if not). The synchronous custom made aspects flag should be unset.
For just about every attribute in node ’s attribute list. in order, run these substeps:
Let copyAttribute be a clone of attribute .
Append copyAttribute to copy .
Otherwise, let copy be a node that implements the same interfaces as node. and fulfills these extra prerequisites, switching on node :
Established copy ’s node document and document to copy. if copy is often a document. and established copy ’s node document to document otherwise.
Run any cloning steps defined for node in other applicable specifications and pass copy. node. document and then the clone children flag if established, as parameters.
If the clone children flag is established, clone all the children of node and append them to copy. with document as specified in addition to the clone children flag being established.
Return copy .
four.9 DOM: Mutation algorithms
To insert a node into a parent before a child. with the optional suppress observers flag . run these steps:
This step intentionally does not shell out attention to the suppress observers flag .
For every node in nodes. in tree order. run these substeps:
Insert node into parent before child or on the close of parent if child is null.
Run the insertion steps with inclusiveDescendant .
If inclusiveDescendant is connected. then:
If inclusiveDescendant is custom made. then enqueue a tailor made element callback reaction with inclusiveDescendant. callback name " connectedCallback ", and an empty argument list.
If this successfully upgrades inclusiveDescendant. its connectedCallback will be enqueued immediately during the upgrade an element algorithm. where to buy a research paper