?Customized Factors
Abstract
This specification describes the method for enabling the author to define and use new variations of DOM features inside of a document. It is really a copy in 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 existing W3C publications as well as latest revision of this technical report is found from the W3C technical reports index at https://www.w3.org/TR/.
This document was published by the Net 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] with the begin of your email's subject. All comments are welcome.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This serves 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 succeed in progress.
This document was produced by a group operating underneath the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in link with the deliverables with the group; that website page also contains instructions for disclosing a patent. An individual who has actual knowledge of the patent which the individual believes consists of Essential Claim(s) must disclose the data in accordance with section 6 with the W3C Patent Policy.
This document is governed by the 1 September 2015 W3C Procedure Document.
Table of Contents
1. Conformance
Likewise as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes on this specification are non-normative. Everything else in this particular specification is normative.
Any point, at which a conforming UA must make decisions about the state or reaction to the state from the conceptual design, is captured as algorithm. The algorithms are defined in terms of processing equivalence. The processing equivalence is actually a constraint imposed relating to the algorithm implementors, requiring the output with the both equally UA-implemented additionally, 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 Web site IDL specification [ WEBIDL ].
two. HTML: Custom made things
two.1 Introduction
This section is non-normative.
Personalized factors offer you a way for authors to make their have fully-featured DOM aspects. Although authors could always use non-standard components in their documents, with application-specific behaviour included after the fact by scripting or similar, like 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 parts of that class should react to changes.
Personalized parts are part of the larger effort to "rationalise the platform", by explaining present system functionality (like the things of HTML) in terms of lower-level author-exposed extensibility points (like customized element definition). Although today there are a good number of limitations about the abilities of custom made elements-both functionally and semantically-that prevent them from fully explaining the behaviours of HTML's current components, we hope to shrink this gap over time.
two.1.1 Setting up an autonomous personalized element
This section is non-normative.
For your purposes of illustrating how to generate an autonomous personalized element. let's define a personalized element that encapsulates rendering a little icon for a country flag. Our goal is to be able to apply it like so:
To do this, we initial declare a class to the customized element, extending HTMLElement :
We then absolutely need to utilise this class to define the element:
At this point, our earlier mentioned code will deliver the results! 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 proper).
You’re able to also make flag-icon components utilizing the DOM API:
Finally, we also can utilize the personalized element constructor itself. That could be, the previously mentioned code is equivalent to:
two.1.two Producing 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 tailor made components. They exist to enable reuse of behaviours from the current parts of HTML, by extending those things with new tailor made performance. This is important since plenty of on the current behaviours of HTML features can unfortunately not be duplicated by choosing purely autonomous tailor made things. Instead, customized built-in factors permit the installation of customized construction behaviour, lifecycle hooks, and prototype chain onto present parts, essentially "mixing in" these abilities on top in the already-existing element.
Customized built-in things require a distinct syntax from autonomous tailor made factors due to the fact 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 components producing on top of present behaviour is dependent crucially over the extended parts retaining their original local name.
With this example, we'll be crafting a customized built-in element named plastic-button. which behaves like a normal button but gets fancy animation effects additional whenever you click on it. We commence by defining a class, just like before, although this time we increase HTMLButtonElement instead of HTMLElement :
When defining our personalized element, we really need to also specify the extends option:
In general, the name belonging to the element being extended cannot be determined simply by exploring at what element interface it extends, as so many parts share the same interface (these types of as q and blockquote the two sharing HTMLQuoteElement ).
Trying to employ a customized built-in element as an autonomous customized element will not perform; that is certainly, <plastic-button>Click me?</plastic-button> will simply design an HTMLElement with no special behaviour.
When you desire to make a type-extended element programmatically, you are able to make use of the following variety of createElement() :
And as before, the constructor will also succeed:
Notably, all the from the ways in which button is special apply to this sort of "plastic buttons" also: their focus behaviour, ability to participate in kind submission. the disabled attribute, and so on.
two.1.3 Disadvantages of autonomous personalized factors
This section is non-normative.
As specified below, and alluded to over, simply defining and by making use of an element called taco-button does not mean that these types of things represent buttons. That could be, resources these kinds of as Web site browsers, search engines, or accessibility know-how will not robotically treat the resulting element as a button just in accordance with its defined name.
To convey the desired button semantics to your selection of buyers, even while nonetheless choosing an autonomous customized element. a lot of techniques would desire to be employed:
The addition within the tabindex attribute would make the taco-button interactive content. thus making it focusable. Note that if the taco-button have been to become logically disabled, the tabindex attribute would have to be removed.
The addition of an assortment of ARIA attributes helps convey semantics to accessibility engineering. For example, setting the role attribute to " button " will convey the semantics that this serves as a button, enabling people to successfully interact with the control employing usual button-like interactions in their accessibility technologies. Setting the aria-label attribute is necessary to give the button an accessible name. instead of having accessibility 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 innovation the button's disabled state.
The addition of event handlers to handle commonly-expected button behaviours helps convey the semantics of your button to World-wide-web browser customers. In such a case, some of the most relevant event handler would be a single that proxies best suited keydown events to become click events, so which you can activate the button each with keyboard and by clicking.
Also to any default visible styling provided for taco-button features, the visible styling will also really want to be updated to reflect changes in rational state, this kind of as becoming disabled; that is certainly, whatever stylesheet has rules for taco-button will also really need to have rules for taco-button[disabled] .
With these points in mind, a full-featured taco-button that took about the responsibility of conveying button semantics (such as the ability to be disabled) would probably take a look something like this:
Even with this rather-complicated element definition, the element will not be a pleasure make use of for consumers: it will be continually "sprouting" tabindex and aria-* attributes of its possess volition. This is simply because as of now there isn't a way to specify default accessibility semantics or focus behaviour for personalized components, 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 effortless customized built-in element. as revealed inside the previous section, would mechanically inherit the semantics and behaviour for the button element, with no might need to implement these behaviours manually. In general, for any components with nontrivial behaviour and semantics that design on top of present factors of HTML, customized built-in things will be easier to produce, take care of, and consume.
two.1.four Upgrading aspects after their development
This section is non-normative.
On the grounds that element definition can occur at any time, a non-custom element could be created. and then later become a tailor made element after an best suited definition is registered. We call this course of action "upgrading" the element, from the normal element into a personalized element.
Upgrades allow scenarios where it may be preferable for tailor made element definitions to be registered after relevant things continues to be initially created, these kinds of as by the parser. They make it possible for progressive enhancement with the content inside tailor made element. For example, inside following HTML document the element definition for img-viewer is loaded asynchronously:
The definition with the img-viewer element right here is loaded utilising a script element marked with the async attribute, placed after the <img-viewer> tag within the markup. Even as the script is loading, the img-viewer element will be treated as an undefined element, similar into a span. Once the script loads, it will define the img-viewer element, together with the present img-viewer element around the web page will be upgraded, applying the customized element's definition (which presumably contains applying an image filter identified by the string "Kelvin", enhancing the image's visible appearance).
Note that upgrades only apply to parts during the document tree. (Formally, features that are connected .) An element that may be not inserted into a document will stay un-upgraded. An example illustrates this point:
two.two Demands for tailor made element constructors
When authoring customized element constructors. authors are bound by the following conformance specifications:
A parameter-less call to super() must be the first of all statement with the constructor body, to establish the correct prototype chain and this value before any further code is run.
A return statement must not appear just about anywhere 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 with the non-upgrade case none will be existing, 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, give good results should be deferred to connectedCallback as a whole lot as possible-especially show results involving fetching resources or rendering. However, note that connectedCallback are generally called a lot more than once, so any initialization get the job done that is definitely truly one-time will really want a guard to prevent it from working twice.
In general, the constructor should be employed to put in place initial state and default values, and to established event listeners and possibly a shadow root .
Several of these standards are checked during element development. either directly or indirectly, and failing to follow them will result in the personalized element that cannot be instantiated by the parser or DOM APIs.
two.3 Core concepts
A custom made element is undoubtedly an element which is personalized. Informally, this suggests that its constructor and prototype are defined by the author, instead of by the person agent. This author-supplied constructor operate is called the custom made element constructor .
Two distinct forms of custom made things are often defined:
An autonomous custom made element. which is defined with no extends option. These variations of customized factors have a local name equal to their defined name .
A customized built-in element. which is defined by having an extends option. These forms of personalized features have local name equal to the value passed in their extends option, and their defined name is applied since the value of your is attribute.
After a custom made element is created. changing the value of your is attribute does not change the element's behaviour, as it is saved about the element as its is value .
Autonomous personalized things have the following element definition:
An autonomous personalized element does not have any special meaning: it represents its children. A customized built-in element inherits the semantics with the element that it extends.
Any namespace-less attribute that could be relevant to the element's functioning, as determined by the element's author, may be specified on an autonomous personalized element. so lengthy because the attribute name is XML-compatible and accommodates no uppercase ASCII letters. The exception is the is attribute, which must not be specified on an autonomous custom made element (and that can have no effect if it is).
Customized built-in features follow the normal prerequisites for attributes, dependant on the features they lengthen. To increase tailor made attribute-based behavior, use data-* attributes.
A valid custom made element name is actually a sequence of characters name that meets all belonging to the following standards:
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 employs the EBNF notation from the XML specification. [ XML ]
name must not be any within 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 necessities ensure a variety of goals for valid custom made element names :
They start off by using 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 parts ASCII-case-insensitively.
They contain a hyphen, employed for namespacing and to ensure forward compatibility (since no things will be extra to HTML, SVG, or MathML with hyphen-containing local names within 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 considerable a number of names is allowed, to give maximum flexibility for use cases like <math-?> or <emotion-??> .
A tailor made element definition describes a personalized element and consists of:
A name A valid custom made 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 Purpose callback purpose type value, or null. By default the value of every entry is null. A construction stack A list, initially empty, which is manipulated by the upgrade an element algorithm in addition to the HTML element constructors. Every single entry with the list will be either an element or an currently constructed marker.
To start looking up a custom made element definition. given a document. namespace. localName. and is. perform the following steps. They will return either a custom made element definition or null:
If namespace isn't the HTML namespace. return null.
If document does not have a browsing context. return null.
two.four The CustomElementRegistry interface
Just about every Window object is associated which includes a unique instance of the CustomElementRegistry object, allocated in the event the Window object is created.
Customized element registries are associated with Window objects, instead of Document objects, since every single personalized element constructor inherits from the HTMLElement interface, and there is certainly exactly a single HTMLElement interface for each Window object.
The customElements attribute on the Window interface must return the CustomElementRegistry object for that Window object.
Every CustomElementRegistry has a list of personalized element definitions. initially empty. In general, algorithms during this specification glimpse up parts on the registry by any of name. local name. or constructor .
Every CustomElementRegistry also has an element definition is functioning flag which is utilised to prevent reentrant invocations of element definition. It is initially unset.
Every CustomElementRegistry also has a when-defined promise map. mapping valid personalized element names to guarantees. It is chosen to implement the whenDefined() method.
window. customElements. define ( name. constructor ) Defines a new tailor made element. mapping the given name to the given constructor as an autonomous personalized 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 to the element type identified by the supplied baseLocalName. A " NotSupportedError " DOMException will be thrown upon trying to increase a custom made element or an unknown element. window. customElements. get ( name ) Retrieves the custom made element constructor defined with the given name. Returns undefined if there isn't any 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 this kind of a custom made element is currently defined, the returned promise will be immediately fulfilled.) Returns a promise rejected which has a " SyntaxError " DOMException if not given a valid custom made element name.
Element definition is often a routine of adding a custom made element definition to the CustomElementRegistry. This is accomplished by the define() method. When invoked, the define( name. constructor. methods ) 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 your new element that implements interface. with no attributes, namespace established to namespace. namespace prefix established to prefix. local name established to localName. custom made 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 is actually a valid customized element name or is is non-null, then established result ’s customized 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 custom made. then enqueue a tailor made 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 custom made. then enqueue a tailor 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 from 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. having an optional document and clone children flag . run these steps:
If document isn't given, let document be node ’s node document .
If node is surely an element. then:
Let copy be the result of establishing an element. given document. node ’s local name. node ’s namespace. node ’s namespace prefix. and also value of node ’s is attribute if current (or null if not). The synchronous customized features flag should be unset.
For each and 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 more specifications, 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 plus 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 together with the clone children flag being established.
Return copy .
four.9 DOM: Mutation algorithms
To insert a node into a parent before a child. by having an optional suppress observers flag . run these steps:
This step intentionally does not fork out attention to the suppress observers flag .
For every single node in nodes. in tree order. run these substeps:
Insert node into parent before child or on the conclude of parent if child is null.
Run the insertion steps with inclusiveDescendant .
If inclusiveDescendant is connected. then:
If inclusiveDescendant is customized. then enqueue a personalized element callback reaction with inclusiveDescendant. callback name " connectedCallback ", and an empty argument list.
If this successfully upgrades inclusiveDescendant. its connectedCallback will be enqueued instantly during the upgrade an element algorithm. professional college essay writers