This does not use the in a document check, as the <{script}> element could have been removed from the document prior to execution, and in that scenario {{Document/currentScript}} still needs to point to it.
2. Run the classic script given by the script's script."module"classic" and the script is
from an external file, fire a simple event named load
at the <{script}> element.
Otherwise queue a task to fire a simple event named load at the
<{script}> element.
Scripting languages
A JavaScript MIME type is a MIME type string that is one of the following and refers to JavaScript: [[!ECMA-262]]application/ecmascriptapplication/javascriptapplication/x-ecmascriptapplication/x-javascripttext/ecmascripttext/javascripttext/javascript1.0text/javascript1.1text/javascript1.2text/javascript1.3text/javascript1.4text/javascript1.5text/jscripttext/livescripttext/x-ecmascripttext/x-javascript
These types are explicitly listed here because they are poorly-defined types that are nonetheless likely to be used as formats for data blocks, and it would be problematic if they were suddenly to be interpreted as script by a user agent.
When examining types to determine if they represent supported languages, user agents must not ignore MIME parameters. Types are to be compared including all parameters.
For example, types that include the charset parameter will not be
recognized as referencing any of the scripting languages listed above.
Restrictions for contents of <{script}> elements
The easiest and safest way to avoid the rather strange restrictions described in this section is to always escape "`<!--`" as "`<\!--`", "`<script`" as "`<\script`", and "`</script`" as "`<\/script`" when these sequences appear in literals in scripts (e.g., in strings, regular expressions, or comments), and to avoid writing code that uses such constructs in expressions. Doing so avoids the pitfalls that the restrictions in this section are prone to triggering: namely, that, for historical reasons, parsing of <{script}> blocks in HTML is a strange and exotic practice that acts counter intuitively in the face of these sequences.
The {{Node/textContent}} of a <{script}> element must match thescript production in
the following ABNF, the character set for which is Unicode. [[!ABNF]]
script = outer *( comment-open inner comment-close outer )
outer = < any string that doesn't contain a substring that matches not-in-outer >
not-in-outer = comment-open
inner = < any string that doesn't contain a substring that matches not-in-inner >
not-in-inner = comment-close / script-open
comment-open = "<!--"
comment-close = "-->"
script-open = "<" s c r i p t tag-end
s = %x0053 ; U+0053 LATIN CAPITAL LETTER S
s =/ %x0073 ; U+0073 LATIN SMALL LETTER S
c = %x0043 ; U+0043 LATIN CAPITAL LETTER C
c =/ %x0063 ; U+0063 LATIN SMALL LETTER C
r = %x0052 ; U+0052 LATIN CAPITAL LETTER R
r =/ %x0072 ; U+0072 LATIN SMALL LETTER R
i = %x0049 ; U+0049 LATIN CAPITAL LETTER I
i =/ %x0069 ; U+0069 LATIN SMALL LETTER I
p = %x0050 ; U+0050 LATIN CAPITAL LETTER P
p =/ %x0070 ; U+0070 LATIN SMALL LETTER P
t = %x0054 ; U+0054 LATIN CAPITAL LETTER T
t =/ %x0074 ; U+0074 LATIN SMALL LETTER T
tag-end = %x0009 ; U+0009 CHARACTER TABULATION (tab)
tag-end =/ %x000A ; U+000A LINE FEED (LF)
tag-end =/ %x000C ; U+000C FORM FEED (FF)
tag-end =/ %x0020 ; U+0020 SPACE
tag-end =/ %x002F ; U+002F SOLIDUS (/)
tag-end =/ %x003E ; U+003E GREATER-THAN SIGN (>)
When a <{script}> element contains script documentation, there are further restrictions on
the contents of the element, as described in the section below.
The following script illustrates this issue. Suppose you have a script that contains a string,
as in:
var example = 'Consider this string: <!-- <script>';
console.log(example);
If one were to put this string directly in a <{script}> block, it would violate the
restrictions above:
<script>
var example = 'Consider this string: <!-- <script>';
console.log(example);
</script>;
The bigger problem, though, and the reason why it would violate those restrictions, is that
actually the script would get parsed weirdly:
the script block above is not terminated. That is, what looks like a
"
<script>
var example = 'Consider this string: <!-- <script>';
console.log(example);
</script>
<!-- despite appearances, this is actually part of the script still! -->
<script>
... // this is the same script block still...
</script>
What is going on here is that for legacy reasons, "
<script>
var example = 'Consider this string: <\!-- <\script>';
console.log(example);
</script>
<!-- this is just a comment between script blocks -->
<script>
... // this is a new script block
</script>
It is possible for these sequences to naturally occur in script expressions, as in the
following examples:
if (x<!--y) { ... }
if ( player<script ) { ... }
In such cases the characters cannot be escaped, but the expressions can be rewritten so that
the sequences don't occur, as in:
if (x < !--y) { ... }
if (!--y > x) { ... }
if (!(--y) > x) { ... }
if (player < script) { ... }
if (script > player) { ... }
Doing this also avoids a different pitfall as well: for related historical reasons, the string
"
</script>" end tag in this snippet is actually still part of the <{script}>
block. The script doesn't execute (since it's not terminated); if it somehow were to execute,
as it might if the markup looked as follows, it would fail because the script is not valid
JavaScript:
<!--" and
"<script" strings in <{script}> elements in HTML need to be balanced in
order for the parser to consider closing the block.
By escaping the problematic strings as mentioned at the top of this section, the problem is
avoided entirely:
<!--" in classic scripts is actually treated as a line comment start, just like
"`//`".
Inline documentation for external scripts
If a <{script}> element's <{script/src}> attribute is specified, then the contents of the <{script}> element, if any, must be such that the value of the {{HTMLScriptElement/text}} IDL attribute, which is derived from the element's contents, matches thedocumentation
production in the following ABNF, the character set for which is Unicode. [[!ABNF]]
documentation = *( *( space / tab / comment ) [ line-comment ] newline )
comment = slash star *( not-star / star not-slash ) 1*star slash
line-comment = slash slash *not-newline
; characters
tab = %x0009 ; U+0009 CHARACTER TABULATION (tab)
newline = %x000A ; U+000A LINE FEED (LF)
space = %x0020 ; U+0020 SPACE
star = %x002A ; U+002A ASTERISK (*)
slash = %x002F ; U+002F SOLIDUS (/)
not-newline = %x0000-0009 / %x000B-10FFFF
; a Unicode character other than U+000A LINE FEED (LF)
not-star = %x0000-0029 / %x002B-10FFFF
; a Unicode character other than U+002A ASTERISK (*)
not-slash = %x0000-002E / %x0030-10FFFF
; a Unicode character other than U+002F SOLIDUS (/)
This corresponds to putting the contents of the element in JavaScript comments.
This requirement is in addition to the earlier restrictions on the syntax of contents of <{script}> elements.
This allows authors to include documentation, such as license information or API information,
inside their documents while still referring to external script files. The syntax is
constrained so that authors don't accidentally include what looks like valid script while
also providing a <{script/src}> attribute.
<script src="cool-effects.js">
// create new instances using:
// var e = new Effect();
// start the effect using .play, stop using .stop:
// e.play();
// e.stop();
</script>
Interaction of <{script}> elements and XSLT
This section is non-normative. This specification does not define how XSLT interacts with the <{script}> element. However, in the absence of another specification actually defining this, here are some guidelines for implementors, based on existing implementations: * When an XSLT transformation program is triggered by an `<?xml-stylesheet?>` processing instruction and the browser implements a direct-to-DOM transformation, <{script}> elements created by the XSLT processor need to be marked "[=parser-inserted=]" and run in document order (modulo scripts marked <{script/defer}> or <{script/async}>), immediately, as the transformation is occurring. * TheXSLTProcessor.transformToDocument() method [[XSLTP]] adds elements to a
{{Document}} that is not in a browsing context, and, accordingly, any <{script}>
elements they create need to have their "[=already started=]" flag set in the
prepare a script algorithm and never get executed (scripting is disabled). Such
<{script}> elements still need to be marked "[=parser-inserted=]", though, such that their
{{HTMLScriptElement/async}} IDL attribute will return false in the absence of an
<{script/async}> content attribute.
* The XSLTProcessor.transformToFragment() method needs to create a fragment that is
equivalent to one built manually by creating the elements using
{{Document/createElementNS()|document.createElementNS()}}. For instance, it needs to create
<{script}> elements that aren't "[=parser-inserted=]" and that don't have their
"[=already started=]" flag set, so that they will execute when the fragment is
inserted into a document.
The main distinction between the first two cases and the last case is that the first two
operate on {{Document}}s and the last operates on a fragment.
The noscript element
- Categories:
- Metadata content.
- Flow content.
- Phrasing content.
- Contexts in which this element can be used:
- In a <{head}> element of an HTML document, if there are no ancestor <{noscript}> elements.
- Where phrasing content is expected in HTML documents, if there are no ancestor <{noscript}> elements.
- Content model:
- When scripting is disabled, in a <{head}> element: in any order, zero or more <{link}> elements, zero or more <{style}> elements, and zero or more <{meta}> elements.
- When scripting is disabled, not in a <{head}> element: transparent, but there must be no <{noscript}> element descendants.
- Otherwise: text that conforms to the requirements given in the prose.
- Tag omission in text/html:
- Neither tag is omissible
- Content attributes:
- Global attributes
- [=Allowed ARIA role attribute values=]:
- None
- [=Allowed ARIA state and property attributes=]:
- None
- DOM interface:
- Uses {{HTMLElement}}.
outerHTML attribute of the <{noscript}> element to the value of
s. (This, as a side-effect, causes the <{noscript}> element to be removed
from the document.) [[!DOM-PARSING]]
All these contortions are required because, for historical reasons, the <{noscript}> element is handled differently by the HTML parser based on whether [=scripting flag|scripting was enabled or not=] when the parser was invoked.
The <{noscript}> element must not be used in XML documents.The <{noscript}> element is only effective in the HTML syntax, it has no effect in the XHTML syntax. This is because the way it works is by essentially "turning off" the parser when scripts are enabled, so that the contents of the element are treated as pure text and not as real elements. XML does not define a mechanism by which to do this.
The <{noscript}> element has no other requirements. In particular, children of the <{noscript}> element are not exempt from [[#forms-form-submission]], scripting, and so forth, even when scripting is enabled for the element.
In the following example, a <{noscript}> element is used to provide fallback for a script.
<form action="calcSquare.php">
<p>
<label for="x">Number</label>:
<input id="x" name="x" type="number">
</p>
<script>
var x = document.getElementById('x');
var output = document.createElement('p');
output.textContent = 'Type a number; it will be squared right then!';
x.form.appendChild(output);
x.form.onsubmit = function() {
return false;
}
x.oninput = function() {
var v = x.valueAsNumber;
output.textContent = v + ' squared is ' + v * v;
};
</script>
<noscript>
<input type="submit" value="Calculate Square">
</noscript>
</form>
When script is disabled, a button appears to do the calculation on the server side. When
script is enabled, the value is computed on-the-fly instead.
The <{noscript}> element is a blunt instrument. Sometimes, scripts might be enabled, but
for some reason the page's script might fail. For this reason, it's generally better to avoid
using <{noscript}>, and to instead design the script to change the page from being a
scriptless page to a scripted page on the fly, as in the next example:
<form action="calcSquare.php">
<p>
<label for="x">Number</label>:
<input id="x" name="x" type="number">
</p>
<input id="submit" type=submit value="Calculate Square">
<script>
var x = document.getElementById('x');
var output = document.createElement('p');
output.textContent = 'Type a number; it will be squared right then!';
x.form.appendChild(output);
x.form.onsubmit = function() {
return false;
}
x.oninput = function() {
var v = x.valueAsNumber;
output.textContent = v + ' squared is ' + v * v;
};
var submit = document.getElementById('submit');
submit.parentNode.removeChild(submit);
</script>
</form>
The above technique is also useful in XHTML, since <{noscript}> is not supported in
the XHTML syntax.
The template element
- Categories:
- Metadata content.
- Flow content.
- Phrasing content.
- Script-supporting element.
- Contexts in which this element can be used:
- Where metadata content is expected.
- Where phrasing content is expected.
- Where script-supporting elements are expected.
- As a child of a <{colgroup}> element that doesn't have a
spanattribute. - Content model:
- Nothing (for clarification, see example).
- Tag omission in text/html:
- Neither tag is omissible.
- Content attributes:
- Global attributes
- [=Allowed ARIA role attribute values=]:
- None
- [=Allowed ARIA state and property attributes=]:
- None
- DOM interface:
-
[Exposed=Window, HTMLConstructor] interface HTMLTemplateElement : HTMLElement { readonly attribute DocumentFragment content; };
It is also possible, as a result of DOM manipulation, for a <{template}> element to contain {{Text}} nodes and element nodes; however, having any is a violation of the <{template}> element's content model, since its content model is defined as Nothing.
For example, consider the following document:
<!DOCTYPE html>
<html lang="en">
<head>
<title>Homework</title>
</head>
<body>
<template id="template">
<p>Smile!</p>
</template>
<script>
let num = 3;
const fragment = document.getElementById('template').content.cloneNode(true);
while (num-- > 1) {
fragment.firstChild.before(fragment.firstChild.cloneNode(true));
fragment.firstChild.textContent += fragment.lastChild.textContent;
}
document.body.appendChild(fragment);
</script>
</body>
</html>
The <{p}> element in the <{template}> is not a child of the <{template}> in the DOM;
it is a child of the {{DocumentFragment}} returned by the <{template}> element's
content IDL attribute.
If the script were to call appendChild() on the <{template}> element, that would
add a child to the <{template}> element (as for any other element); however, doing so is a
violation of the <{template}> element's content model.
- template .
content - Returns the template contents (a {{DocumentFragment}}).
- Let doc be the <{template}> element's node document's appropriate template contents owner document.
- Create a {{DocumentFragment}} object whose node document is doc and [=host-concept/host=] is the <{template}> element.
- Set the <{template}> element's template contents to the newly created {{DocumentFragment}} object.
-
If doc is not a {{Document}} created by this algorithm, then:
-
If doc does not yet have an
associated inert template document, then:
- Let new doc be a new {{Document}} (that does not have a browsing context). This is "a {{Document}} created by this algorithm" for the purposes of the step above.
- If doc is an HTML document, mark new doc as an HTML document also.
- Let doc's associated inert template document be new doc.
- Set doc to doc's associated inert template document.
Each
Documentnot created by this algorithm thus gets a singleDocumentto act as its proxy for owning the template contents of all its <{template}> elements, so that they aren't in a browsing context and thus remain inert (e.g., scripts do not run). Meanwhile, <{template}> elements insideDocumentobjects that are created by this algorithm just reuse the sameDocumentowner for their contents. -
If doc does not yet have an
associated inert template document, then:
- Return doc.
-
Let doc be node's node document's
appropriate template contents owner document.
node's node document is the
Documentobject that node was just adopted into. - Adopt node's
template contents (a
DocumentFragmentobject) into doc.
content IDL attribute must return
the <{template}> element's template contents.
The cloning steps for a
template element node being cloned to a
copy copy must run the following steps:
- If the clone children flag is not set in the calling clone algorithm, abort these steps.
- Let copied contents be the result of cloning all the children of node's template contents, with document set to copy's template contents's node document, and with the clone children flag set.
- Append copied contents to copy's template contents.
In this example, a script populates a table four-column with data from a data structure, using
a
<!DOCTYPE html>
<html lang="en">
<title>Cat data</title>
<script>
// Data is hard-coded here, but could come from the server
var data = [
{ name: 'Pillar', color: 'Tabby', sex: 'Female', legs: 3 },
{ name: 'Hedral', color: 'Tuxedo', sex: 'Male', legs: 4 },
];
</script>
<table>
<thead>
<tr>
<th>Name</th> <th>Color</th> <th>Sex</th> <th>Legs</th>
</tr>
</thead>
<tbody>
<template id="row">
<tr>
<td></td> <td></td> <td></td> <td></td>
</tr>
</template>
</tbody>
</table>
<script>
var template = document.querySelector('#row');
for (var i = 0; i < data.length; i += 1) {
var cat = data[i];
var clone = template.content.cloneNode(true);
var cells = clone.querySelectorAll('td');
cells[0].textContent = cat.name;
cells[1].textContent = cat.color;
cells[2].textContent = cat.sex;
cells[3].textContent = cat.legs;
template.parentNode.appendChild(clone);
}
</script>
This example uses
template to provide the element structure instead of manually generating the
structure from markup.
cloneNode() on the template's contents; it could
equivalently have used document.importNode(), which does the same thing. The only
difference between these two APIs is when the node document is updated: with
cloneNode() it is updated when the nodes are appended with
appendChild(), with document.importNode() it is updated when the
nodes are cloned.
Interaction of <{template}> elements with XSLT and XPath
This section is non-normative. This specification does not define how XSLT and XPath interact with thetemplate
element. However, in the absence of another specification actually defining this, here are some
guidelines for implementors, which are intended to be consistent with other processing described
in this specification:
- An XSLT processor based on an XML parser that acts as described in this specification needs to act as if <{template}> elements contain as descendants their template contents for the purposes of the transform.
- An XSLT processor that outputs a DOM needs to ensure that nodes that would go into a <{template}> element are instead placed into the element's template contents.
- XPath evaluation using the XPath DOM API when applied to a
Documentparsed using the HTML parser or the XML parser described in this specification needs to ignore template contents.
The canvas element
- Categories:
- Flow content.
- Phrasing content.
- Embedded content.
- Palpable content.
- Contexts in which this element can be used:
- Where embedded content is expected.
- Content model:
- Transparent.
- Tag omission in text/html:
- Neither tag is omissible
- Content attributes:
- Global attributes
width- Horizontal dimensionheight- Vertical dimension- [=Allowed ARIA role attribute values=]:
- Any role value.
- [=Allowed ARIA state and property attributes=]:
- Global aria-* attributes
- Any
aria-*attributes applicable to the allowed roles. - DOM interface:
-
typedef (CanvasRenderingContext2D or WebGLRenderingContext or WebGL2RenderingContext) RenderingContext; interface HTMLCanvasElement : HTMLElement { attribute unsigned long width; attribute unsigned long height; RenderingContext? getContext(DOMString contextId, any... arguments); boolean probablySupportsContext(DOMString contextId, any... arguments); DOMString toDataURL(optional DOMString type, any... arguments); void toBlob(BlobCallback _callback, optional DOMString type, any... arguments); }; callback BlobCallback = void (Blob? blob);
h1) and then styled using
CSS and supporting technologies such as Web Components.
When authors use the <{canvas}> element, they must also provide content that, when presented
to the user, conveys essentially the same function or purpose as the <{canvas}>'s bitmap.
This content may be placed as content of the <{canvas}> element. The contents of the <{canvas}>
element, if any, are the element's fallback content.
In interactive visual media, if scripting is enabled for the <{canvas}> element, and if support for <{canvas}> elements has been enabled, the <{canvas}> element represents embedded content consisting of a dynamically created image, the element's bitmap. In non-interactive, static, visual media, if the <{canvas}> element has been previously associated with a rendering context (e.g., if the page was viewed in an interactive visual medium and is now being printed, or if some script that ran during the page layout process painted on the element), then the <{canvas}> element represents embedded content with the element's current bitmap and size. Otherwise, the element represents its fallback content instead. In non-visual media, and in visual media if scripting is disabled for the <{canvas}> element or if support for <{canvas}> elements has been disabled, the <{canvas}> element represents its fallback content instead. When a <{canvas}> element represents embedded content, the user can still focus descendants of the <{canvas}> element (in the fallbackcontent). When an element is focused, it is the target of keyboard interaction events (even though the element itself is not visible). This allows authors to make an interactive canvas keyboard-accessible: authors should have a one-to-one mapping of interactive regions to focusable areas in the fallback content. (Focus has no effect on mouse interaction events.) [[!UIEVENTS]] An element whose nearest <{canvas}> element ancestor is being rendered and represents embedded content is an element that is being used as relevant canvas fallback content.
The <{canvas}> element has two attributes to control the size of the element's bitmap:
width and
height. These attributes, when specified,
must have values that are valid non-negative integers.
The rules for parsing non-negative integers must be used to obtain their numeric values.
If an attribute is missing, or if parsing its value returns an error, then the default value
must be used instead. The width attribute defaults to 300, and the
height attribute defaults to 150.
The intrinsic dimensions of the <{canvas}> element when it represents
embedded content are equal to the dimensions of the element's bitmap.
The user agent must use a square pixel density consisting of one pixel of image data per
coordinate space unit for the bitmaps of a canvas and its rendering contexts.
A <{canvas}> element can be sized arbitrarily by a style sheet, its bitmap is then subject to the 'object-fit' CSS property. [[!CSS3-IMAGES]]
The bitmaps of <{canvas}> elements, the bitmaps of
ImageBitmap objects,
as well as some of the bitmaps of rendering contexts, such as those described in the section on
the CanvasRenderingContext2D object below, have an
origin-clean flag, which can be set to true or false.
Initially, when the <{canvas}> element or ImageBitmap object is created,
its bitmap's origin-clean flag must be set to true.
A canvas bitmap can also have a hit region list, as described in the
CanvasRenderingContext2D section below.
A <{canvas}> element can have a rendering context bound to it. Initially, it does not
have a bound rendering context. To keep track of whether it has a rendering context or not, and
what kind of rendering context it is, a canvas also has a
canvas context mode,
which is initially none but can be changed to either
2d, webgl, webgl2 by algorithms defined in this specification.
When its canvas context mode is none,
a <{canvas}> element has no rendering context, and its bitmap must be fully transparent black
with an intrinsic width equal to the numeric value of the element's
width attribute and an intrinsic height equal to the numeric value
of the element's height attribute, those values being interpreted in CSS pixels,
and being updated as the attributes are set, changed, or removed.
When a <{canvas}> element represents embedded content, it provides
a paint source whose width is the element's intrinsic width, whose
height is the element's intrinsic height, and whose appearance is the
element's bitmap.
Whenever the width and height content attributes are set, removed,
changed, or redundantly set to the value they already have, if the
canvas context mode is 2d, the user agent
must set bitmap dimensions to the numeric values of the width and
height content attributes.
The width and
height IDL attributes must
reflect the respective content attributes of the same name, with the same defaults.
- context = canvas .
getContext(contextId [, ... ] ) -
Returns an object that exposes an API for drawing on the canvas. The first argument specifies
the desired API. Subsequent arguments are handled by that API.
Valid contexts are: "
2d" [[!CANVAS-2D]] or "webgl" [[!WEBGL-1]] or "webgl2" [[!webgl-2]]. Returns null if the given context ID is not supported or if the canvas has already been initialized with some other (incompatible) context type (e.g., trying to get a "2d" context after getting a "webgl" context). - supported = canvas .
probablySupportsContext(contextId [, ... ] ) -
Returns false if calling
getContext()with the same arguments would definitely return null, and true otherwise. This return value is not a guarantee thatgetContext()will or will not return an object, as conditions (e.g., availability of system resources) can vary over time.
getContext(contextId,
arguments...) method of the <{canvas}> element, when invoked,
must run the steps in the cell of the following table whose column header describes the
<{canvas}> element's canvas context mode
and whose row header describes the method's first argument.
| none | 2d | webgl | webgl2 | |
|---|---|---|---|---|
"2d" |
Set the <{canvas}> element's context mode to 2d, obtain a
CanvasRenderingContext2D object as
defined in the HTML Canvas 2D Context
specification [[!CANVAS-2D]], set the obtained
CanvasRenderingContext2D object's
context mode to
2d, and return the
CanvasRenderingContext2D object
|
Return the same object as was return the last time the method was invoked with this same first argument. | Return null. | Return null. |
"webgl", if the user agent supports the WebGL feature in its current configuration |
Follow the instructions given in the WebGL specification's Context Creation section to
obtain either a WebGLRenderingContext or null; if the returned value is null,
then return null and abort these steps, otherwise, set the <{canvas}> element's context mode to webgl, set the new
WebGLRenderingContext object's context mode to webgl, and return the WebGLRenderingContext
object‡ [[!WEBGL-1]]
|
Return null. | Return the same object as was return the last time the method was invoked with this same first argument. | Return null |
"webgl2", if the user agent supports the WebGL2 feature in its current configuration |
Follow the instructions given in the WebGL2 specification's Context Creation section to
obtain either a WebGL2RenderingContext or null; if the returned value is null,
then return null and abort these steps, otherwise, set the <{canvas}> element's context mode to webgl2, set the new
WebGL2RenderingContext object's context mode to webgl2, and return the WebGL2RenderingContext
object [[!webgl-2]]
|
Return null. | Return null. | Return the same object as was return the last time the method was invoked with this same first argument. |
| A vendor-specific extension* | Behave as defined for the extension. | Behave as defined for the extension. | Behave as defined for the extension. | Behave as defined for the extension. |
| An unsupported value† | Return null. | Return null. | Return null. | Return null. |
vendorname-context, for example, moz-3d.
† For example, the "webgl" value in the case of a user agent having
exhausted the graphics hardware's abilities and having no software fallback
implementation.
‡ The second (and subsequent) argument(s) to the method, if any, are ignored in all cases
except this one. See the WebGL specification for details.
The
probablySupportsContext(contextId,
arguments...) method of the <{canvas}> element, when invoked, must
return false if calling getContext() on the same object and with the same arguments
would definitely return null at this time, and true otherwise.
- url = canvas .
toDataURL( [ type, ... ] ) -
Returns a
data:URL for the image in the canvas. The first argument, if provided, controls the type of the image to be returned (e.g., PNG or JPEG). The default isimage/png; that type is also used if the given type isn't supported. The other arguments are specific to the type, and control the way that the image is generated, as given in the table below. When trying to use types other than "image/png", authors can check if the image was really returned in the requested format by checking to see if the returned string starts with one of the exact strings "data:image/png," or "data:image/png;". If it does, the image is PNG, and thus the requested type was not supported. (The one exception to this is if the canvas has either no height or no width, in which case the result might simply be "data:,".) - canvas .
toBlob(callback [, type, ... ] ) -
Creates a
Blobobject representing a file containing the image in the canvas, and invokes a callback with a handle to that object. The second argument, if provided, controls the type of the image to be returned (e.g., PNG or JPEG). The default isimage/png; that type is also used if the given type isn't supported. The other arguments are specific to the type, and control the way that the image is generated, as given in the table below.
toDataURL() method must run the
following steps:
- If the <{canvas}> element's bitmap's origin-clean flag is set to false, throw a "{{SecurityError}}" {{DOMException}} and abort these steps.
- If the <{canvas}> element's bitmap has no pixels (i.e., either its horizontal
dimension or its vertical dimension is zero) then return the string "
data:," and abort these steps. (This is the shortestdata:URL; it represents the empty string in atext/plainresource.) -
Let file be
a serialization of the
canvaselement's bitmap as a file, using the method's arguments (if any) as the arguments. - Return a
data:URL representing file. [[!RFC2397]]
- If the <{canvas}> element's bitmap's origin-clean flag is set to false, throw a "{{SecurityError}}" {{DOMException}} and abort these steps.
- Let callback be the first argument.
- Let arguments be the second and subsequent arguments to the method, if any.
-
If the <{canvas}> element's bitmap has no pixels (i.e., either its horizontal
dimension or its vertical dimension is zero) then let result be null.
Otherwise, let result be a
Blobobject representing a serialization of thecanvaselement's bitmap as a file, using arguments. [[!FILEAPI]] - Return, but continue running these steps in parallel.
-
Queue a task to invoke the
BlobCallbackcallback with result as its argument. The task source for this task is the canvas blob serialization task source.
Color spaces and color correction
Thecanvas APIs must only perform color correction in two circumstances:
- When rendering the actual canvas bitmap to the output device.
-
When images which contain their own gamma correction and color space information are
rendered onto a bitmap which has an existing color space. The image must be converted to
to the bitmap's color space. (e.g., using the 2D Context's
drawImage()method with aHTMLImageElementobject).
Thus, in the 2D context, colors used to draw shapes onto the canvas will exactly
match colors obtained through the getImageData() method.
toDataURL() method must not include color space information in the resources
they return. Where the output format allows it, the color of pixels in resources created by
toDataURL() must match those returned by the getImageData() method.
In user agents that support CSS, the color space used by a <{canvas}> element must
match the color space used for processing any colors for that element in CSS.
The gamma correction and color space information of images must be handled in such a way that
an image rendered directly using an <{img}> element would use the same colors as one
painted on a <{canvas}> element that is then itself rendered. Furthermore, the rendering
of images that have no color correction information (such as those returned by the
toDataURL() method) must be rendered with no color correction.
Thus, in the 2D context, calling the drawImage() method to render the output
of the toDataURL() method to the canvas, given the appropriate
dimensions, has no visible effect.
Serializing bitmaps to a file
When a user agent is to create a serialization of the bitmap as a file, optionally with some given arguments, and optionally with a native flag set, it must create an image file in the format given by the first value of arguments, or, if there are no arguments, in the PNG format. [[!PNG]] If the native flag is set, or if the bitmap has one pixel per coordinate space unit, then the image file must have the same pixel data (before compression, if applicable) as the bitmap, and if the file format used supports encoding resolution metadata, the resolution of that bitmap (device pixels per coordinate space units being interpreted as image pixels per CSS pixel) must be given as well. Otherwise, the image file's pixel data must be the bitmap's pixel data scaled to one image pixel per coordinate space unit, and if the file format used supports encoding resolution metadata, the resolution must be given as 96dpi (one image pixel per CSS pixel). If arguments is not empty, the first value must be interpreted as a MIME type giving the format to use. If the type has any parameters, it must be treated as not supported.
For example, the value "image/png" would mean to generate a PNG
image, the value "image/jpeg" would mean to generate a JPEG image, and the value
"image/svg+xml" would mean to generate an SVG image (which would require that the
user agent track how the bitmap was generated, an unlikely, though potentially awesome,
feature).
image/png"). User agents may support other types.
If the user agent does not support the requested type, it must create the file using the PNG
format. [[!PNG]]
User agents must convert the provided type to ASCII lowercase before establishing if they support that type.
For image types that do not support an alpha channel, the serialized image must be the bitmap
image composited onto a solid black background using the source-over operator.
If the first argument in arguments gives a type corresponding to one of the types
given in the first column of the following table, and the user agent supports that type, then
the subsequent arguments, if any, must be treated as described in the second cell of that row.
| Type | Other arguments | Reference |
|---|---|---|
image/jpeg |
The second argument, if it is a number in the range 0.0 to 1.0 inclusive, must be treated as the desired quality level. If it is not a number or is outside that range, the user agent must use its default value, as if the argument had been omitted. | [[!JPEG]] |
any in the
Web IDL specification. [[!WEBIDL]]
Other arguments must be ignored and must not cause the user agent to throw an exception. A
future version of this specification will probably define other parameters to be passed to these
methods to allow authors to more carefully control compression settings, image metadata, etc.
Security with <{canvas}> elements
This section is non-normative. Information leakage can occur if scripts from one [=concept/origin=] can access information (e.g., read pixels) from images from another origin (one that isn't the same). To mitigate this, bitmaps used with <{canvas}> elements andImageBitmap
objects are defined to have a flag indicating whether they are origin-clean.
All bitmaps start with their origin-clean set to true. The flag is set to
false when cross-origin images or fonts are used.
The toDataURL(), toBlob(), and getImageData()
methods check the flag and will throw a "{{SecurityError}}" {{DOMException}} rather than
leak cross-origin data.
The value of the origin-clean flag is propagated from a source <{canvas}> element's
bitmap to a new ImageBitmap object by createImageBitmap().
Conversely, a destination <{canvas}> element's bitmap will have its origin-clean flags
set to false by drawImage if the source image is an
ImageBitmap object whose bitmap has its origin-clean flag set to false.
The flag can be reset in certain situations; for example, when a
CanvasRenderingContext2D is bound to a new <{canvas}>, the bitmap is cleared
and its flag reset.
Custom Elements
A custom element is an element whose {{constructor}} andprototype are defined by the author.
The author-supplied constructor function is called the
custom element constructor.
Custom elements have the custom element state "custom".
For the elements whose semantics are described in this specification, or in other applicable specifications, {{constructor}} and prototype are defined by the user agent.
There are two types of custom elements: : autonomous custom Elements :: These are entirely author-defined, extending {{HTMLElement}} : customized built-in Elements :: These extend elements that are already defined. This is typically to inherit some functionality.Autonomous custom elements
An autonomous custom element is a custom element completely defined by
the author. It extends {{HTMLElement}}, and its local name is equal to its
name.
Autonomous custom elements have the following element definition:
-
Categories:
- Flow content.
- Phrasing content.
- Palpable content.
-
Contexts in which this element can be used:
-
Where phrasing content is expected.
-
Content model:
-
Transparent.
-
Content attributes:
-
Global attributes, except the <{global/is}> attribute
-
Allowed ARIA role attribute values:
-
Any role value
-
Allowed ARIA state and property attributes:
- Global aria-* attributes
-
Any
aria-* attributes
applicable to the allowed roles.
-
DOM interface:
-
Supplied by the element's author (inherits from {{HTMLElement}})
An autonomous custom element's meaning is defined by its author.
It represents its children.
To illustrate how to create an autonomous custom element, the following example
will create the foundation for a custom heading element. The element will have two required
attributes (level and text) to pass in the heading level and text
for the heading. The permalink will be created based on the text of the heading.
Before an author can use a custom element in their markup, a class for the new element must be
declared by extending {{HTMLElement}} and defining the {{constructor}}. The class always
starts by calling super() so that the correct prototype chain will be
established.
class permaHeading extends HTMLElement {
constructor() {
super();
// Element functionality will go here
}
}
All of the custom element's functionality will be written within the {{constructor}}. It's here
where the custom element's shadow DOM structure and styling may be defined and attached to
the custom element's shadow root.
The basic functionality for the custom element is defined in the following JavaScript. The
necessary elements for the custom element are created and styling is defined.
class permaHeading extends HTMLElement {
constructor() {
super();
// Create a shadow root
var shadow = this.attachShadow({mode: 'open'});
// The custom element will need a heading level
// and heading text to be complete
var hLevel = this.getAttribute('level') || '1';
var hText = this.getAttribute('text') || '';
var hID = hText.replace(/\s+/g, '-').toLowerCase();
// Setup wrapping element
const wrapper = document.createElement('div');
wrapper.classList.add('ph');
// Setup the heading
const heading = document.createElement('h'+ hLevel);
heading.classList.add('ph__heading');
heading.id = hID;
heading.textContent = hText;
// Setup the link
const link = document.createElement('a');
link.classList.add('ph__link');
link.href = '#' + hID;
link.setAttribute('aria-label', 'Permalink for ' + hText);
link.textContent = '§';
// Add styling to the shadow DOM
var styles = document.createElement('style');
styles.textContent = '.ph {' +
'align-items: center;' +
'display: flex;' +
'}' +
'.ph__heading {' +
'padding: .25em;' +
'}' +
'.ph__link {' +
'color: #aaa;' +
'padding: .5em .75em;' +
'}' +
'.ph__link:hover, .ph__link:focus {' +
'background: #111;' +
'color: #fff;' +
'}';
// Attach the created elements to the shadow DOM
shadow.appendChild(styles);
shadow.appendChild(wrapper);
wrapper.appendChild(link);
wrapper.appendChild(heading);
}
}
// Define the new custom element
customElements.define('perma-heading', permaHeading);
After the custom element has been defined, an author would be able to use the custom element
in their markup like so:
<perma-heading level="2" text="Beaches on the east coast"></perma-heading>
Customized built-in elements
A customized built-in element is a custom element that extends an
existing element.
A customized built-in element's local name is the name of the element it extends.
Its name is called the is value: the value of
the <{global/is}> attribute when it is used in HTML.
For example a <{button}> has pre-defined interaction behaviour, a <{tr}> already participates
in the table model, and a <{input/checkbox}> has defined behaviour and participates in
form submission.
Since only existing table elements take part in the table model, with other elements
moved outside the <{table}>, creating a custom element that is part of a <{table}> can only
be done by customizing a built-in table element.
A customized built-in element inherits the semantics
of the element that it extends.
A customized built-in element has the same requirements for attributes as the element
it extends. To add custom attribute-based behavior, use
[=custom data attributes|data-*=] attributes.
aria-* attributes
applicable to the allowed roles.
level and text) to pass in the heading level and text
for the heading. The permalink will be created based on the text of the heading.
Before an author can use a custom element in their markup, a class for the new element must be
declared by extending {{HTMLElement}} and defining the {{constructor}}. The class always
starts by calling super() so that the correct prototype chain will be
established.
A customized built-in element's is value is saved on the element when it is [=create an element|created=]. This means changing the value of the <{global/is}> attribute after the element is [=create an element|created=] does not change the element's behaviour.
Requirements for all custom elements
A valid custom element name is a sequence of characters name that matches the PotentialCustomElementName production, and is not one of the following:annotation-xmlcolor-profilefont-facefont-face-srcfont-face-urifont-face-formatfont-face-namemissing-glyph
These are all hyphen-containing element names from the applicable specifications: SVG and MathML. [[SVG11]] [[MATHML]]
ThePotentialCustomElementName production is as follows:
- 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]
These requirements ensure a number of goals for valid custom element names:
A custom element definition describes a custom element and consists of:
- They start with a lowercase ASCII letter, ensuring that the HTML parser will treat them as tags instead of as text.
- They do not contain any uppercase ASCII letters, so user agents can always treat HTML elements ASCII-case-insensitively.
- They contain a hyphen, used for namespacing and to ensure forward compatibility. No new elements will be added to HTML, SVG, or MathML with names containing a hyphen.
- They can always be created with {{Document/createElement()}} and {{Document/createElementNS()}}, which have more restrictions than the parser.
-
They allow a wide range of names to give maximum flexibility:
e.g.
<x-小山><math-α>or<emotion-😍>.
- A name
- A valid custom element name.
- A local name
- For autonomous custom elements this is the same as its name.
- For customized built-in elements this is the name of the element it extends.
- A constructor
- A custom element constructor function.
- A prototype
- A JavaScript object
- A list of observed attributes
-
A
sequence<DOMString>that is a list of attribute names. When any attribute in that list changes value, theattributeChangedCallbackcustom element reaction is [=enqueue a custom element callback reaction|enqueued=]. - A collection of lifecycle callbacks
- These callbacks are used to invoke custom element reactions
-
The value must be a map, whose four keys are the strings "
connectedCallback", "disconnectedCallback", "adoptedCallback", and "attributeChangedCallback". The values of each key are either a Web IDL {{Function!!callback}}, or null. The default value of each entry is null. - A construction stack
- A list, initially empty, that is manipulated by the upgrade an element algorithm and the HTML element constructors. Each entry in the list is either an element or an already constructed marker.
- If namespace is not the HTML namespace, return null.
- If document does not have a browsing context, return null.
- Let registry be document's browsing context's {{Window}}'s {{CustomElementRegistry}} object.
- If there is custom element definition in registry with name and local name both equal to localName, return that custom element definition.
- If there is a custom element definition in registry with name equal to is and local name equal to localName, return that custom element definition.
- Return null.
Requirements for custom element constructors
A custom element constructor must meet the following requirements:-
A parameter-less call to
super()must be the first statement in the constructor body. This establishes the correct prototype chain andthisvalue before any further code is run. -
A
returnstatement must not appear anywhere inside the constructor body, unless it is a simple early-return (returnorreturn this). - The constructor must not use the {{Document/write()|document.write()}} or {{Document/open()|document.open()}} methods.
- The element's attributes and children must not be inspected. In the non-upgrade case none will be present, and relying on upgrades makes the element less usable.
- The element must not gain any attributes or children. Doing so violates the expectations of consumers who use the {{Document/createElement()}} or {{Document/createElementNS()}} methods.
-
Work should be deferred to
connectedCallback. This especially applies to work involving fetching resources or rendering. However, note thatconnectedCallbackcan be called more than once, so initialization work may need a guard to prevent it from running twice. - The constructor should set up initial state and default values, event listeners, and possibly a shadow root.
The slot element
- Categories:
- Flow content.
- Phrasing content.
- Contexts in which this element can be used:
- Where phrasing content is expected.
- Content model:
- Transparent
- Tag omission in text/html:
- Neither tag is omissible
- Content attributes:
- Global attributes
- <{slot/name}> - the name of the slot created.
- [=Allowed ARIA role attribute values=]:
- Any role value.
- [=Allowed ARIA state and property attributes=]:
-
Any
aria-*attributes applicable to the default or allowed roles. - DOM interface:
-
[Exposed=Window, HTMLConstructor] interface HTMLSlotElement : HTMLElement { [CEReactions] attribute DOMString name; sequence<Node> assignedNodes(optional AssignedNodesOptions options); sequence<Element> assignedElements(optional AssignedNodesOptions options); }; dictionary AssignedNodesOptions { boolean flatten = false; }; - DPub Roles:
- Any
The following example uses the <{slot}> element with a <{template}> for user profile cards.
Two <{slot}>s are named, using the <{slot/name}> attribute, the other is unnamed, or anonymous.
<template id="profile-card">
<div class="card">
<slot name="user-name">
<p>No user name available.</p>
</slot>
<slot name="user-email">
<p>No email provided.</p>
</slot>
<!-- an anonymous slot -->
<slot>
<p>No details provided.</p>
</slot>
</div>
</template>
When using a custom element based on that <{template}>, each slot can be replaced with a
defined HTML fragment.
If a child element of the custom element has a <{global/slot}> attribute, that element will
replace the slot whose <{slot/name}> matches it.
An element without a <{global/slot}> attribute will be inserted into the anonymous
<{slot}> element.
If the browser doesn't support the 
slot element, or a custom element doesn't
define replacement content for a slot, the fallback content of that slot in the
<{template}> will be used.
<user-card>
<h2 slot="user-name">Violet Ann</h2>
<div>
<p>Enjoys:</p>
<ul>
<li>Reading</li>
<li>Sketching</li>
<li>Cycling</li>
</ul>
</div>
<-- notice no defined user-email -->
</user-card>
After the browser runs the necessary JavaScript to define the custom element, the content
defined within the custom element user-card will be inserted into the appropriate
<{slot}> elements defined within the <{template}>.
With some CSS styling the example could be rendered like this:
- slot .
name - Get or set the slot's name.
- slot .
assignedNodes() - Returns the slot's assigned nodes.
- slot .
assignedNodes({ flatten: true}) - Returns the slot's assigned nodes, including those of any <{slot}> elements that are descendants, calculated recursively. If there are not assigned nodes it returns the elements children.
- slot .
assignedElements() - Returns the slot's assigned nodes that are Elements.
- slot .
assignedElements({ flatten: true}) - Returns only the Elements that would be returned by
assignedNodes({ flatten: true}).
assignedNodes(), when invoked on an element
element, and given options options, must run the
following algorithm:
- If the
flattenmember of options isfalse, return the element's assigned nodes. - otherwise, return the result of [=find flattened slotables|finding flattened slottables=] for element.
assignedElements(), when invoked on an element
element, and given options options, must run the
following algorithm:
- Let result be empty.
- If the
flattenmember of options isfalse, set result to the element's assigned nodes. - otherwise, set result to the result of [=find flattened slotables|finding flattened slottables=] for element.
- Remove all nodes from result that are not elements.
- Return result.