Status: Last call for comments
html
elementStatus: Last call for comments
head
element followed by a body
element.manifest
interface HTMLHtmlElement : HTMLElement {};
The html
element represents the root of
an HTML document.
The manifest
attribute gives the address of the document's application
cache manifest, if there is
one. If the attribute is present, the attribute's value must be a
valid URL.
The manifest
attribute
only has an effect during
the early stages of document load. Changing the attribute
dynamically thus has no effect (and thus, no DOM API is provided for
this attribute).
For the purposes of application cache selection,
later base
elements cannot affect the resolving of relative URLs in manifest
attributes, as the
attributes are processed before those elements are seen.
The window.applicationCache
IDL
attribute provides scripted access to the offline application
cache mechanism.
The html
element in the following example declares
that the document's language is English.
<!DOCTYPE html> <html lang="en"> <head> <title>Swapping Songs</title> </head> <body> <h1>Swapping Songs</h1> <p>Tonight I swapped some of the songs I wrote with some friends, who gave me some of the songs they wrote. I love sharing my music.</p> </body> </html>
Status: Last call for comments
head
elementStatus: Last call for comments. ISSUE-55 (head-profile) blocks progress to Last Call
html
element.iframe
srcdoc
document or if title information is available from a higher-level protocol: Zero or more elements of metadata content.title
element.interface HTMLHeadElement : HTMLElement {};
The head
element represents a
collection of metadata for the Document
.
The collection of metadata in a head
element can be
large or small. Here is an example of a very short one:
<!doctype html> <html> <head> <title>A document with a short head</title> </head> <body> ...
Here is an example of a longer one:
<!DOCTYPE HTML> <HTML> <HEAD> <META CHARSET="UTF-8"> <BASE HREF="http://www.example.com/"> <TITLE>An application with a long head</TITLE> <LINK REL="STYLESHEET" HREF="default.css"> <LINK REL="STYLESHEET ALTERNATE" HREF="big.css" TITLE="Big Text"> <SCRIPT SRC="support.js"></SCRIPT> <META NAME="APPLICATION-NAME" CONTENT="Long headed application"> </HEAD> <BODY> ...
The title
element is a required child
in most situations, but when a higher-level protocol provides title
information, e.g. in the Subject line of an e-mail when HTML is used
as an e-mail authoring format, the title
element can be
omitted.
title
elementStatus: Last call for comments
head
element containing no other title
elements.interface HTMLTitleElement : HTMLElement { attribute DOMString text; };
The title
element represents the
document's title or name. Authors should use titles that identify
their documents even when they are used out of context, for example
in a user's history or bookmarks, or in search results. The
document's title is often different from its first heading, since the
first heading does not have to stand alone when taken out of
context.
There must be no more than one title
element per
document.
text
[ = value ]Returns the contents of the element, ignoring child nodes that aren't text nodes.
Can be set, to replace the element's children with the given value.
The IDL attribute text
must return a
concatenation of the contents of all the text nodes that are direct children of the
title
element (ignoring any other nodes such as
comments or elements), in tree order. On setting, it must act the
same way as the textContent
IDL attribute.
Here are some examples of appropriate titles, contrasted with the top-level headings that might be used on those same pages.
<title>Introduction to The Mating Rituals of Bees</title> ... <h1>Introduction</h1> <p>This companion guide to the highly successful <cite>Introduction to Medieval Bee-Keeping</cite> book is...
The next page might be a part of the same site. Note how the title describes the subject matter unambiguously, while the first heading assumes the reader knows what the context is and therefore won't wonder if the dances are Salsa or Waltz:
<title>Dances used during bee mating rituals</title> ... <h1>The Dances</h1>
The string to use as the document's title is given by the document.title
IDL
attribute. User agents should use the document's
title when referring to the document in their user
interface.
base
elementStatus: Last call for comments
head
element containing no other base
elements.href
target
interface HTMLBaseElement : HTMLElement { attribute DOMString href; attribute DOMString target; };
The base
element allows authors to specify the
document base URL for the purposes of resolving relative URLs, and the name
of the default browsing context for the purposes of
following hyperlinks. The element does not represent any content beyond this
information.
There must be no more than one base
element per
document.
A base
element must have either an href
attribute, a target
attribute, or both.
The href
content
attribute, if specified, must contain a valid URL.
A base
element, if it has an href
attribute, must come before any
other elements in the tree that have attributes defined as taking
URLs, except the html
element
(its manifest
attribute
isn't affected by base
elements).
The target
attribute, if specified, must contain a valid browsing context
name or keyword, which specifies which browsing
context is to be used as the default when hyperlinks and forms in the Document
cause navigation.
A base
element, if it has a target
attribute, must come before
any elements in the tree that represent hyperlinks.
If there are multiple base
elements
with target
attributes, all but
the first are ignored.
The href
and target
IDL attributes
must reflect the respective content attributes of the
same name.
In this example, a base
element is used to set the
document base URL:
<!DOCTYPE html> <html> <head> <title>This is an example for the <base> element</title> <base href="http://www.example.com/news/index.html"> </head> <body> <p>Visit the <a href="archives.html">archives</a>.</p> </body> </html>
The link in the above example would be a link to "http://www.example.com/news/archives.html
".
link
elementStatus: Last call for comments
noscript
element that is a child of a head
element.href
rel
media
hreflang
type
sizes
title
attribute has special semantics on this element.interface HTMLLinkElement : HTMLElement {
attribute boolean disabled;
attribute DOMString href;
attribute DOMString rel;
readonly attribute DOMTokenList relList;
attribute DOMString media;
attribute DOMString hreflang;
attribute DOMString type;
[PutForwards=value] readonly attribute DOMSettableTokenList sizes;
};
HTMLLinkElement implements LinkStyle;
The link
element allows authors to link their
document to other resources.
The destination of the link(s) is given by the href
attribute, which must
be present and must contain a valid URL. If the href
attribute is absent, then the element does not define a
link.
A link
element must have rel
attribute.
The types of link indicated (the relationships) are given by the
value of the rel
attribute, which, if present, must have a value that is a set
of space-separated tokens. The allowed
values and their meanings are defined in a later section. If the rel
attribute
is absent, or if the values used are not allowed according to the
definitions in this specification, then the element does not define
a link.
Two categories of links can be created using the
link
element. Links
to external resources are links to resources that are to be
used to augment the current document, and hyperlink links are links to
other documents. The link types
section defines whether a particular link type is an external
resource or a hyperlink. One element can create multiple links (of
which some might be external resource links and some might be
hyperlinks); exactly which and how many links are created depends on
the keywords given in the rel
attribute. User agents must process the links on a per-link basis,
not a per-element basis.
Each link is handled separately. For instance, if
there are two link
elements with rel="stylesheet"
, they each count as a separate
external resource, and each is affected by its own attributes
independently.
The exact behavior for links to external resources depends on the
exact relationship, as defined for the relevant link type. Some of
the attributes control whether or not the external resource is to be
applied (as defined below). For external
resources that are represented in the DOM (for example, style
sheets), the DOM representation must be made available even if the
resource is not applied. To obtain
the resource, the user agent must resolve the URL given by the href
attribute, relative to the
element, and then fetch the resulting absolute
URL. User agents may opt to only try to obtain such resources
when they are needed, instead of pro-actively fetching all the external resources that are
not applied.
The semantics of the protocol used (e.g. HTTP) must be followed when fetching external resources. (For example, redirects will be followed and 404 responses will cause the external resource to not be applied.)
Once the attempts to obtain the resource and its critical
subresources are complete, the user agent must, if the loads were
successful, queue a task to fire a simple
event named load
at the
link
element, or, if the resource or one of its
critical subresources failed to completely load for any reason
(e.g. DNS error, HTTP 404 response, a connection being prematurely
closed, unsupported Content-Type), queue a task to
fire a simple event named error
at the link
element. Non-network errors in processing the resource or its
subresources (e.g. CSS parse errors, PNG decoding errors) are not
failures for the purposes of this paragraph.
The task source for these tasks is the DOM manipulation task source.
The element must delay the load event of the element's document until all the attempts to obtain the resource and its critical subresources are complete. (Resources that the user agent has not yet attempted to obtain, e.g. because it is waiting for the resource to be needed, do not delay the load event.)
Which resources are considered critical or not is defined by the
relevant specification. For CSS resources, only @import
rules introduce critical subresources; other
resources, e.g. fonts or backgrounds, are not.
Interactive user agents may provide users with a
means to follow the
hyperlinks created using the link
element,
somewhere within their user interface. The exact interface is not
defined by this specification, but it could include the following
information (obtained from the element's attributes, again as
defined below), in some form or another (possibly simplified), for
each hyperlink created with each link
element in the
document:
rel
attribute)title
attribute).href
attribute).hreflang
attribute).media
attribute).User agents could also include other information, such as the
type of the resource (as given by the type
attribute).
Hyperlinks created with the link
element and its rel
attribute
apply to the whole page. This contrasts with the rel
attribute of a
and area
elements, which indicates the type of a link
whose context is given by the link's location within the
document.
The media
attribute says which media the resource applies to. The value must
be a valid media query.
If the link is a hyperlink
then the media
attribute is
purely advisory, and describes for which media the document in
question was designed.
However, if the link is an external resource link,
then the media
attribute is
prescriptive. The user agent must apply the external resource to a
view when the media
attribute's value matches
the environment of that view and the other relevant
conditions apply, and must not apply it otherwise.
The external resource might have further
restrictions defined within that limit its applicability. For
example, a CSS style sheet might have some @media
blocks. This specification does not override
such further restrictions or requirements.
The default, if the media
attribute is omitted, is "all
", meaning that by default links apply to all
media.
The hreflang
attribute on the link
element has the same semantics as
the hreflang
attribute on hyperlink elements.
The type
attribute
gives the MIME type of the linked resource. It is
purely advisory. The value must be a valid MIME
type.
For external resource
links, the type
attribute
is used as a hint to user agents so that they can avoid fetching
resources they do not support. If the attribute
is present, then the user agent must assume that the resource is of
the given type (even if that is not a valid MIME type,
e.g. the empty string). If the attribute is omitted, but the
external resource link type has a default type defined, then the
user agent must assume that the resource is of that type. If the UA
does not support the given MIME type for the given link
relationship, then the UA should not obtain the resource; if the UA
does support the given MIME type for the given link
relationship, then the UA should obtain the resource. If the
attribute is omitted, and the external resource link type does not
have a default type defined, but the user agent would obtain the resource if the type
was known and supported, then the user agent should obtain the resource under the
assumption that it will be supported.
User agents must not consider the type
attribute authoritative —
upon fetching the resource, user agents must not use the type
attribute to determine its actual
type. Only the actual type (as defined in the next paragraph) is
used to determine whether to apply the resource, not the
aforementioned assumed type.
If the external resource link type defines rules for processing the resource's Content-Type metadata, then those rules apply. Otherwise, if the resource is expected to be an image, user agents may apply the image sniffing rules, with the official type being the type determined from the resource's Content-Type metadata, and use the resulting sniffed type of the resource as if it was the actual type. Otherwise, if neither of these conditions apply or if the user agent opts not to apply the image sniffing rules, then the user agent must use the resource's Content-Type metadata to determine the type of the resource. If there is no type metadata, but the external resource link type has a default type defined, then the user agent must assume that the resource is of that type.
The stylesheet
link type defines rules for processing the resource's Content-Type metadata.
Once the user agent has established the type of the resource, the user agent must apply the resource if it is of a supported type and the other relevant conditions apply, and must ignore the resource otherwise.
If a document contains style sheet links labeled as follows:
<link rel="stylesheet" href="A" type="text/plain"> <link rel="stylesheet" href="B" type="text/css"> <link rel="stylesheet" href="C">
...then a compliant UA that supported only CSS style sheets
would fetch the B and C files, and skip the A file (since
text/plain
is not the MIME type for CSS style
sheets).
For files B and C, it would then check the actual types returned
by the server. For those that are sent as text/css
, it
would apply the styles, but for those labeled as
text/plain
, or any other type, it would not.
If one of the two files was returned without a
Content-Type metadata, or with a syntactically
incorrect type like Content-Type: "null"
, then the default type
for stylesheet
links would kick
in. Since that default type is text/css
, the
style sheet would nonetheless be applied.
The title
attribute gives the title of the link. With one exception, it is
purely advisory. The value is text. The exception is for style sheet
links, where the title
attribute defines alternative style sheet sets.
The title
attribute on link
elements differs from the global
title
attribute of most other
elements in that a link without a title does not inherit the title
of the parent element: it merely has no title.
The sizes
attribute is used
with the icon
link type. The attribute
must not be specified on link
elements that do not have
a rel
attribute that specifies
the icon
keyword.
Some versions of HTTP defined a Link:
header, to be processed like a series of link
elements.
If supported, for the purposes of ordering links defined by HTTP
headers must be assumed to come before any links in the document, in
the order that they were given in the HTTP entity header. (URIs in
these headers are to be processed and resolved according to the
rules given in HTTP; the rules of this specification don't
apply.) [HTTP] [WEBLINK]
The IDL attributes href
, rel
, media
, hreflang
, and type
, and sizes
each must
reflect the respective content attributes of the same
name.
The IDL attribute relList
must reflect the rel
content attribute.
The IDL attribute disabled
only applies
to style sheet links. When the link
element defines a
style sheet link, then the disabled
attribute behaves as
defined for the alternative
style sheets DOM. For all other link
elements it
always return false and does nothing on setting.
The LinkStyle
interface is also implemented by
this element; the styling processing model defines
how. [CSSOM]
Here, a set of link
elements provide some style
sheets:
<!-- a persistent style sheet --> <link rel="stylesheet" href="default.css"> <!-- the preferred alternate style sheet --> <link rel="stylesheet" href="green.css" title="Green styles"> <!-- some alternate style sheets --> <link rel="alternate stylesheet" href="contrast.css" title="High contrast"> <link rel="alternate stylesheet" href="big.css" title="Big fonts"> <link rel="alternate stylesheet" href="wide.css" title="Wide screen">
The following example shows how you can specify versions of the page that use alternative formats, are aimed at other languages, and that are intended for other media:
<link rel=alternate href="/en/html" hreflang=en type=text/html title="English HTML"> <link rel=alternate href="/fr/html" hreflang=fr type=text/html title="French HTML"> <link rel=alternate href="/en/html/print" hreflang=en type=text/html media=print title="English HTML (for printing)"> <link rel=alternate href="/fr/html/print" hreflang=fr type=text/html media=print title="French HTML (for printing)"> <link rel=alternate href="/en/pdf" hreflang=en type=application/pdf title="English PDF"> <link rel=alternate href="/fr/pdf" hreflang=fr type=application/pdf title="French PDF">
meta
elementStatus: Last call for comments. ISSUE-99 (meta-scheme) blocks progress to Last Call
charset
attribute is present, or if the element's http-equiv
attribute is in the Encoding declaration state: in a head
element.http-equiv
attribute is present but not in the Encoding declaration state: in a head
element.http-equiv
attribute is present but not in the Encoding declaration state: in a noscript
element that is a child of a head
element.name
attribute is present: where metadata content is expected.name
http-equiv
content
charset
interface HTMLMetaElement : HTMLElement { attribute DOMString name; attribute DOMString httpEquiv; attribute DOMString content; };
The meta
element represents various
kinds of metadata that cannot be expressed using the
title
, base
, link
,
style
, and script
elements.
The meta
element can represent document-level
metadata with the name
attribute, pragma directives with the http-equiv
attribute, and the
file's character encoding declaration when an HTML
document is serialized to string form (e.g. for transmission over
the network or for disk storage) with the charset
attribute.
Exactly one of the name
,
http-equiv
, and charset
attributes must be
specified.
If either name
or http-equiv
is specified, then
the content
attribute must
also be specified. Otherwise, it must be omitted.
The charset
attribute specifies the character encoding used by the
document. This is a character encoding declaration. If
the attribute is present in an XML
document, its value must be an ASCII
case-insensitive match for the string "UTF-8
" (and the document is therefore forced to use
UTF-8 as its encoding).
The charset
attribute on the meta
element has no effect in XML
documents, and is only allowed in order to facilitate migration to
and from XHTML.
There must not be more than one meta
element with a
charset
attribute per
document.
The content
attribute gives the value of the document metadata or pragma
directive when the element is used for those purposes. The allowed
values depend on the exact context, as described in subsequent
sections of this specification.
If a meta
element has a name
attribute, it sets
document metadata. Document metadata is expressed in terms of
name/value pairs, the name
attribute on the meta
element giving the name, and the
content
attribute on the same
element giving the value. The name specifies what aspect of metadata
is being set; valid names and the meaning of their values are
described in the following sections. If a meta
element
has no content
attribute,
then the value part of the metadata name/value pair is the empty
string.
The name
and content
IDL attributes
must reflect the respective content attributes of the
same name. The IDL attribute httpEquiv
must
reflect the content attribute http-equiv
.
Status: Last call for comments. ISSUE-79 (meta-keywords) blocks progress to Last Call
This specification defines a few names for the name
attribute of the
meta
element.
Names are case-insensitive, and must be compared in an ASCII case-insensitive manner.
application-name
The value must be a short free-form string giving the name
of the Web application that the page represents. If the page is not
a Web application, the application-name
metadata name
must not be used. There must not be more than one meta
element with its name
attribute
set to the value application-name
per
document. User agents may use the application
name in UI in preference to the page's title
, since
the title might include status messages and the like relevant to
the status of the page at a particular moment in time instead of
just being the name of the application.
author
The value must be a free-form string giving the name of one of the page's authors.
description
The value must be a free-form string that describes the
page. The value must be appropriate for use in a directory of
pages, e.g. in a search engine. There must not be more than one
meta
element with its name
attribute set to the value description
per document.
generator
The value must be a free-form string that identifies one of the software packages used to generate the document. This value must not be used on hand-authored pages.
Here is what a tool called "Frontweaver" could include in its
output, in the page's head
element, to identify
itself as the tool used to generate the page:
<meta name=generator content="Frontweaver 8.2">
Status: Last call for comments. ISSUE-27 (rel-ownership) and ISSUE-102 (meta-name-registry) block progress to Last Call
Extensions to the predefined set of metadata names may be registered in the WHATWG Wiki MetaExtensions page. [WHATWGWIKI]
Anyone is free to edit the WHATWG Wiki MetaExtensions page at any time to add a type. These new names must be specified with the following information:
The actual name being defined. The name should not be confusingly similar to any other defined name (e.g. differing only in case).
A short non-normative description of what the metadata name's meaning is, including the format the value is required to be in.
A list of other names that have exactly the same processing requirements. Authors should not use the names defined to be synonyms, they are only intended to allow user agents to support legacy content. Anyone may remove synonyms that are not used in practice; only names that need to be processed as synonyms for compatibility with legacy content are to be registered in this way.
One of the following:
If a metadata name is found to be redundant with existing values, it should be removed and listed as a synonym for the existing value.
If a metadata name is registered in the "proposed" state for a period of a month or more without being used or specified, then it may be removed from the registry.
If a metadata name is added with the "proposed" status and found to be redundant with existing values, it should be removed and listed as a synonym for the existing value. If a metadata name is added with the "proposed" status and found to be harmful, then it should be changed to "discontinued" status.
Anyone can change the status at any time, but should only do so in accordance with the definitions above.
Conformance checkers must use the information given on the WHATWG Wiki MetaExtensions page to establish if a value is allowed or not: values defined in this specification or marked as "proposed" or "ratified" must be accepted, whereas values marked as "discontinued" or not listed in either this specification or on the aforementioned page must be rejected as invalid. Conformance checkers may cache this information (e.g. for performance reasons or to avoid the use of unreliable network connectivity).
When an author uses a new metadata name not defined by either this specification or the Wiki page, conformance checkers should offer to add the value to the Wiki, with the details described above, with the "proposed" status.
Metadata names whose values are to be URLs must not be proposed or accepted. Links must
be represented using the link
element, not the
meta
element.
Status: Last call for comments
When the http-equiv
attribute
is specified on a meta
element, the element is a pragma
directive.
The http-equiv
attribute is an enumerated attribute. The following
table lists the keywords defined for this attribute. The states
given in the first cell of the rows with keywords give the states to
which those keywords map.
State | Keywords | Notes |
---|---|---|
Content Language | content-language
| Conformance checkers will include a warning |
Encoding declaration | content-type
| |
Default style | default-style
| |
Refresh | refresh
|
When a meta
element is inserted into the document, if its
http-equiv
attribute is
present and represents one of the above states, then the user agent
must run the algorithm appropriate for that state, as described in
the following list:
http-equiv="content-language"
)
This pragma sets the pragma-set default language. Until the pragma is successfully processed, there is no pragma-set default language.
Conformance checkers will include a warning if
this pragma is used. Authors are encouraged to use the lang
attribute instead.
If another meta
element with an http-equiv
attribute in the
Content
Language state has already been successfully processed
(i.e. when it was inserted the user agent processed it and
reached the last step of this list of steps), then abort these
steps.
If the meta
element has no content
attribute, or if that
attribute's value is the empty string, then abort these
steps.
If the element's content
attribute contains a
U+002C COMMA character (,) then abort these steps.
Let input be the value of the
element's content
attribute.
Let position point at the first character of input.
Collect a sequence of characters that are not space characters.
Let the pragma-set default language be the string that resulted from the previous step.
For meta
elements with an http-equiv
attribute in the
Content
Language state, the content
attribute must have a
value consisting of a valid BCP 47 language code. [BCP47]
This pragma is not exactly equivalent to the HTTP
Content-Language
header, for instance it only
supports one language. [HTTP]
http-equiv="content-type"
)
The Encoding
declaration state is just an alternative form of setting
the charset
attribute: it is a
character encoding declaration. This state's user agent requirements are all handled
by the parsing section of the specification.
For meta
elements with an http-equiv
attribute in the
Encoding
declaration state, the content
attribute must have a
value that is an ASCII case-insensitive match for a
string that consists of: the literal string "text/html;
", optionally followed by any number of
space characters, followed by
the literal string "charset=
", followed by
the character encoding name of the character encoding
declaration.
If the document contains a meta
element with an
http-equiv
attribute in
the Encoding
declaration state, then the document must not contain a
meta
element with the charset
attribute present.
The Encoding
declaration state may be used in HTML
documents, but elements with an http-equiv
attribute in that
state must not be used in XML documents.
http-equiv="default-style"
)
This pragma sets the name of the default alternative style sheet set.
http-equiv="refresh"
)
This pragma acts as timed redirect.
If another meta
element with an http-equiv
attribute in the
Refresh state
has already been successfully processed (i.e. when it was
inserted the user agent processed it and reached the last step of
this list of steps), then abort these steps.
If the meta
element has no content
attribute, or if that
attribute's value is the empty string, then abort these
steps.
Let input be the value of the
element's content
attribute.
Let position point at the first character of input.
Collect a sequence of characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9), and parse the resulting string using the rules for parsing non-negative integers. If the sequence of characters collected is the empty string, then no number will have been parsed; abort these steps. Otherwise, let time be the parsed number.
Collect a sequence of characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9) and U+002E FULL STOP (.). Ignore any collected characters.
Let url be the address of the current page.
If the character in input pointed to
by position is a U+003B SEMICOLON (";
"), then advance position to
the next character. Otherwise, jump to the last step.
If the character in input pointed to by position is a U+0055 LATIN CAPITAL LETTER U character (U) or a U+0075 LATIN SMALL LETTER U character (u), then advance position to the next character. Otherwise, jump to the last step.
If the character in input pointed to by position is a U+0052 LATIN CAPITAL LETTER R character (R) or a U+0072 LATIN SMALL LETTER R character (r), then advance position to the next character. Otherwise, jump to the last step.
If the character in input pointed to by position is s U+004C LATIN CAPITAL LETTER L character (L) or a U+006C LATIN SMALL LETTER L character (l), then advance position to the next character. Otherwise, jump to the last step.
If the character in input pointed to
by position is a U+003D EQUALS SIGN ("=
"), then advance position to
the next character. Otherwise, jump to the last step.
If the character in input pointed to by position is either a U+0027 APOSTROPHE character (') or U+0022 QUOTATION MARK character ("), then let quote be that character, and advance position to the next character. Otherwise, let quote be the empty string.
Let url be equal to the substring of input from the character at position to the end of the string.
If quote is not the empty string, and there is a character in url equal to quote, then truncate url at that character, so that it and all subsequent characters are removed.
Strip any trailing space characters from the end of url.
Strip any U+0009 CHARACTER TABULATION, U+000A LINE FEED (LF), and U+000D CARRIAGE RETURN (CR) characters from url.
Resolve the url value to an absolute URL,
relative to the meta
element. If this fails, abort
these steps.
Perform one or more of the following steps:
Set a timer so that in time seconds, adjusted to take into account user or user agent preferences, if the user has not canceled the redirect, the user agent navigates the document's browsing context to url, with replacement enabled, and with the document's browsing context as the source browsing context.
Provide the user with an interface that, when selected, navigates a browsing context to url, with the document's browsing context as the source browsing context.
Do nothing.
In addition, the user agent may, as with anything, inform the user of any and all aspects of its operation, including the state of any timers, the destinations of any timed redirects, and so forth.
For meta
elements with an http-equiv
attribute in the
Refresh state,
the content
attribute must
have a value consisting either of:
In the former case, the integer represents a number of seconds before the page is to be reloaded; in the latter case the integer represents a number of seconds before the page is to be replaced by the page at the given URL.
A news organization's front page could include the following
markup in the page's head
element, to ensure that
the page automatically reloads from the server every five
minutes:
<meta http-equiv="Refresh" content="300">
A sequence of pages could be used as an automated slide show by making each page refresh to the next page in the sequence, using markup such as the following:
<meta http-equiv="Refresh" content="20; URL=page4.html">
There must not be more than one meta
element with
any particular state in the document at a time.
Status: Last call for comments
Extensions to the predefined set of pragma directives may, under certain conditions, be registered in the WHATWG Wiki PragmaExtensions page. [WHATWGWIKI]
Such extensions must use a name that is identical to an HTTP header registered in the Permanent Message Header Field Registry, and must have behavior identical to that described for the HTTP header. [IANAPERMHEADERS]
Pragma directives corresponding to headers describing metadata, or not requiring specific user agent processing, must not be registered; instead, use metadata names. Pragma directives corresponding to headers that affect the HTTP processing model (e.g. caching) must not be registered, as they would result in HTTP-level behavior being different for user agents that implement HTML than for user agents that do not.
Anyone is free to edit the WHATWG Wiki PragmaExtensions page at any time to add a pragma directive satisfying these conditions. Such registrations must specify the following information:
The actual name being defined. The name must match a previously-registered HTTP name with the same requirements.
A short non-normative description of the purpose of the pragma directive.
Conformance checkers must use the information given on the WHATWG Wiki PragmaExtensions page to establish if a value is allowed or not: values defined in this specification or listed on the aforementioned page must be accepted, whereas values not listed in either this specification or on the aforementioned page must be rejected as invalid. Conformance checkers may cache this information (e.g. for performance reasons or to avoid the use of unreliable network connectivity).
Status: Last call for comments
A character encoding declaration is a mechanism by which the character encoding used to store or transmit a document is specified.
The following restrictions apply to character encoding declarations:
If an HTML document does not
start with a BOM, and if its encoding is not explicitly given by
Content-Type metadata, and the
document is not an iframe
srcdoc
document, then the
character encoding used must be an ASCII-compatible character
encoding, and, in addition, if that encoding isn't US-ASCII
itself, then the encoding must be specified using a
meta
element with a charset
attribute or a
meta
element with an http-equiv
attribute in the
Encoding declaration
state.
If the document is an iframe
srcdoc
document, the
document must not have a character encoding
declaration. (In this case, the source is already decoded,
since it is part of the document that contained the
iframe
.)
If an HTML document contains
a meta
element with a charset
attribute or a
meta
element with an http-equiv
attribute in the
Encoding declaration
state, then the character encoding used must be an
ASCII-compatible character encoding.
Authors are encouraged to use UTF-8. Conformance checkers may advise authors against using legacy encodings.
Authoring tools should default to using UTF-8 for newly-created documents.
Encodings in which a series of bytes in the range 0x20 to 0x7E
can encode characters other than the corresponding characters in the
range U+0020 to U+007E represent a potential security vulnerability:
a user agent that does not support the encoding (or does not support
the label used to declare the encoding, or does not use the same
mechanism to detect the encoding of unlabelled content as another
user agent) might end up interpreting technically benign plain text
content as HTML tags and JavaScript. For example, this applies to
encodings in which the bytes corresponding to "<script>
" in ASCII can encode a different
string. Authors should not use such encodings, which are known to
include JIS_C6226-1983,
JIS_X0212-1990, HZ-GB-2312, JOHAB (Windows code
page 1361), encodings based on ISO-2022, and encodings based on EBCDIC. Furthermore, authors must not
use the CESU-8, UTF-7, BOCU-1 and SCSU encodings, which also fall
into this category, because these encodings were never intended for
use for Web content.
[RFC1345]
[RFC1842]
[RFC1468]
[RFC2237]
[RFC1554]
[RFC1922]
[RFC1557]
[CESU8]
[UTF7]
[BOCU1]
[SCSU]
Authors should not use UTF-32, as the encoding detection algorithms described in this specification intentionally do not distinguish it from UTF-16. [UNICODE]
Using non-UTF-8 encodings can have unexpected results on form submission and URL encodings, which use the document's character encoding by default.
In XHTML, the XML declaration should be used for inline character encoding information, if necessary.
In HTML, to declare that the character encoding is UTF-8, the
author could include the following markup near the top of the
document (in the head
element):
<meta charset="utf-8">
In XML, the XML declaration would be used instead, at the very top of the markup:
<?xml version="1.0" encoding="utf-8"?>
style
elementStatus: Last call for comments
scoped
attribute is present: flow content.scoped
attribute is absent: where metadata content is expected.scoped
attribute is absent: in a noscript
element that is a child of a head
element.scoped
attribute is present: where flow content is expected, but before any other flow content other than other style
elements and inter-element whitespace.type
attribute, but must match requirements described in prose below.media
type
scoped
title
attribute has special semantics on this element.interface HTMLStyleElement : HTMLElement {
attribute boolean disabled;
attribute DOMString media;
attribute DOMString type;
attribute boolean scoped;
};
HTMLStyleElement implements LinkStyle;
The style
element allows authors to embed style
information in their documents. The style
element is
one of several inputs to the styling processing
model. The element does not represent content for the user.
The type
attribute gives the styling language. If the attribute is present,
its value must be a valid MIME type that designates a
styling language. The charset
parameter must
not be specified. The default, which is used if the attribute is
absent, is "text/css
". [RFC2318]
When examining types to determine if they support the language,
user agents must not ignore unknown MIME parameters — types
with unknown parameters must be assumed to be unsupported. The charset
parameter must be treated as an unknown
parameter for the purpose of comparing MIME
types here.
The media
attribute says which media the styles apply to. The value must be a
valid media query. The user agent
must apply the styles to a view when the media
attribute's value
matches the environment of that view and the other
relevant conditions apply, and must not apply them
otherwise.
The styles might be further limited in scope,
e.g. in CSS with the use of @media
blocks. This specification does not override such further
restrictions or requirements.
The default, if the media
attribute is omitted, is
"all
", meaning that by default styles apply to
all media.
The scoped
attribute is a boolean attribute. If set, it indicates
that the styles are intended just for the subtree rooted at the
style
element's parent element, as opposed to the whole
Document
.
If the scoped
attribute is
present, then the user agent must apply the specified style
information only to the style
element's parent element
(if any), and that element's child nodes. Otherwise, the specified
styles must, if applied, be applied to the entire document.
The title
attribute on
style
elements defines alternative style sheet
sets. If the style
element has no title
attribute, then it has no
title; the title
attribute of
ancestors does not apply to the style
element. [CSSOM]
The title
attribute on style
elements, like the title
attribute on link
elements, differs from the global title
attribute in that a
style
block without a title does not inherit the title
of the parent element: it merely has no title.
The textContent
of a style
element must
match the style
production in the following
ABNF, the character set for which is Unicode. [ABNF]
style = no-c-start *( c-start no-c-end c-end no-c-start ) no-c-start = <any string that doesn't contain a substring that matches c-start > c-start = "<!--" no-c-end = <any string that doesn't contain a substring that matches c-end > c-end = "-->"
All descendant elements must be processed, according to their
semantics, before the style
element itself is
evaluated. For styling languages that consist of pure text, user
agents must evaluate style
elements by passing the
concatenation of the contents of all the text nodes that are direct children of the
style
element (not any other nodes such as comments or
elements), in tree order, to the style system. For
XML-based styling languages, user agents must pass all the child
nodes of the style
element to the style system.
All URLs found by the styling language's processor must be resolved, relative to the element (or as defined by the styling language), when the processor is invoked.
Once the attempts to obtain the style sheet's critical
subresources, if any, are complete, or, if the style sheet has no
critical subresources, once the style sheet has been parsed and
processed, the user agent must, if the loads were successful or
there were none, queue a task to fire a simple
event named load
at the
style
element, or, if one of the style sheet's critical
subresources failed to completely load for any reason (e.g. DNS
error, HTTP 404 response, a connection being prematurely closed,
unsupported Content-Type), queue a task to fire a
simple event named error
at
the style
element. Non-network errors in processing the
style sheet or its subresources (e.g. CSS parse errors, PNG decoding
errors) are not failures for the purposes of this paragraph.
The task source for these tasks is the DOM manipulation task source.
The element must delay the load event of the element's document until all the attempts to obtain the style sheet's critical subresources, if any, are complete.
Which resources are considered critical or not is defined by the
relevant specification. For CSS resources, only @import
rules introduce critical subresources; other
resources, e.g. fonts or backgrounds, are not.
This specification does not specify a style system, but CSS is expected to be supported by most Web browsers. [CSS]
The media
, type
and scoped
IDL attributes
must reflect the respective content attributes of the
same name.
The disabled
IDL attribute behaves as defined for the alternative style sheets
DOM.
The LinkStyle
interface is also implemented by
this element; the styling processing model defines
how. [CSSOM]
The following document has its emphasis styled as bright red text rather than italics text, while leaving titles of works and Latin words in their default italics. It shows how using appropriate elements enables easier restyling of documents.
<!DOCTYPE html> <html lang="en-US"> <head> <title>My favorite book</title> <style> body { color: black; background: white; } em { font-style: normal; color: red; } </style> </head> <body> <p>My <em>favorite</em> book of all time has <em>got</em> to be <cite>A Cat's Life</cite>. It is a book by P. Rahmel that talks about the <i lang="la">Felis Catus</i> in modern human society.</p> </body> </html>
Status: Last call for comments
The link
and style
elements can provide
styling information for the user agent to use when rendering the
document. The DOM Styling specification specifies what styling
information is to be used by the user agent and how it is to be
used. [CSSOM]
The style
and link
elements implement
the LinkStyle
interface. [CSSOM]
For style
elements, if the user agent does not
support the specified styling language, then the sheet
attribute of the element's
LinkStyle
interface must return null. Similarly,
link
elements that do not represent external resource links that contribute to
the styling processing model (i.e. that do not have a stylesheet
keyword in their rel
attribute), and link
elements whose specified resource has not yet been fetched, or is
not in a supported styling language, must have their
LinkStyle
interface's sheet
attribute return null.
Otherwise, the LinkStyle
interface's sheet
attribute must return a
StyleSheet
object with the following properties: [CSSOM]
The style sheet type must be the same as the style's specified
type. For style
elements, this is the same as the
type
content attribute's
value, or text/css
if that is omitted. For
link
elements, this is the Content-Type metadata of the specified
resource.
For link
elements, the location must be the
result of resolving the
URL given by the element's href
content attribute, relative to
the element, or the empty string if that fails. For
style
elements, there is no location.
The media must be the same as the value of the element's
media
content attribute, or the empty string,
if the attribute is omitted.
The title must be the same as the value of the element's
title
content attribute, if the
attribute is present and has a non-empty value. If the attribute is
absent or its value is the empty string, then the style sheet does
not have a title (it is the empty string). The title is used for
defining alternative style sheet sets.
For link
elements, true if the link is an
alternative stylesheet. In all other cases, false.
The same object must be returned each time.
The disabled
IDL
attribute on link
and style
elements must
return false and do nothing on setting, if the sheet
attribute of their
LinkStyle
interface is null. Otherwise, it must return
the value of the StyleSheet
interface's disabled
attribute on
getting, and forward the new value to that same attribute on
setting.
The rules for handling alternative style sheets are defined in the CSS object model specification. [CSSOM]
Style sheets, whether added by a link
element, a
style
element, an <?xml-stylesheet>
PI,
an HTTP Link:
header, or some other
mechanism, have a style sheet ready flag, which is
initially unset.
When a style sheet is ready to be applied, its style sheet
ready flag must be set. If the style sheet referenced no
other resources (e.g. it was an internal style sheet given by a
style
element with no @import
rules), then the style rules must be synchronously made available to
script; otherwise, the style rules must only be made available to
script once the event loop reaches its "update the
rendering" step.
A style sheet in the context of the Document
of an
HTML parser or XML parser is said to be
a style sheet blocking scripts if the element was created
by that Document
's parser, and the element is either a
style
element or a link
element that was
an external resource link that
contributes to the styling processing model when the element
was created by the parser, and the element's style sheet was enabled
when the element was created by the parser, and the element's
style sheet ready flag is not yet set, and, the last
time the event loop reached step 1, the element was
in that Document
,
and the user agent hasn't given up on that particular style sheet
yet. A user agent may give up on a style sheet at any time.
Status: Last call for comments
Scripts allow authors to add interactivity to their documents.
Authors are encouraged to use declarative alternatives to scripting where possible, as declarative mechanisms are often more maintainable, and many users disable scripting.
For example, instead of using script to show or hide a section
to show more details, the details
element could be
used.
Authors are also encouraged to make their applications degrade gracefully in the absence of scripting support.
For example, if an author provides a link in a table header to dynamically resort the table, the link could also be made to function without scripts by requesting the sorted table from the server.
script
elementStatus: Last call for comments
src
attribute, depends on the value of the type
attribute, but must match
script content restrictions.src
attribute, the element must be either empty or contain only
script documentation that also matches script
content restrictions.src
async
defer
type
charset
interface HTMLScriptElement : HTMLElement { attribute DOMString src; attribute boolean async; attribute boolean defer; attribute DOMString type; attribute DOMString charset; attribute DOMString text; };
The script
element allows authors to include dynamic
script and data blocks in their documents. The element does not
represent content for the user.
When used to include dynamic scripts, the scripts may either be
embedded inline or may be imported from an external file using the
src
attribute. If the language
is not that described by "text/javascript
",
then the type
attribute must
be present, as described below.
When used to include data blocks, the data must be embedded
inline, the format of the data must be given using the type
attribute, and the src
attribute must not be
specified.
The type
attribute gives the language of the script or format of the data. If
the attribute is present, its value must be a valid MIME
type. The charset
parameter must not be
specified. The default, which is used if the attribute is absent,
is "text/javascript
".
The src
attribute, if specified, gives the address of the external script
resource to use. The value of the attribute must be a valid
URL identifying a script resource of the type given by the
type
attribute, if the
attribute is present, or of the type "text/javascript
", if the attribute is absent. A
resource is a script resource of a given type if that type
identifies a scripting language and the resource conforms with the
requirements of that language's specification.
The charset
attribute gives the character encoding of the external script
resource. The attribute must not be specified if the src
attribute is not present. If the
attribute is set, its value must be a valid character encoding name,
must be an ASCII case-insensitive match for the
preferred MIME name for that encoding, and must match
the encoding given in the charset
parameter of
the Content-Type metadata of the
external file, if any. [IANACHARSET]
The async
and
defer
attributes
are boolean attributes that
indicate how the script should be executed.
There are three possible modes that can be selected using these
attributes. If the async
attribute is present, then the script will be executed
asynchronously, as soon as it is available. If the async
attribute is not present but
the defer
attribute is
present, then the script is executed when the page has finished
parsing. If neither attribute is present, then the script is
fetched and executed immediately, before the user agent continues
parsing the page. The exact processing details for these attributes
are described below.
The defer
attribute may be
specified even if the async
attribute is specified, to cause legacy Web browsers that only
support defer
(and not async
) to fall back to the defer
behavior instead of the
synchronous blocking behavior that is the default.
If one or both of the defer
and async
attributes are specified, the
src
attribute must also be
specified.
Changing the src
, type
, charset
, async
, and defer
attributes dynamically has no
direct effect; these attribute are only used at specific times
described below.
A script
element has several associated pieces of
state.
The first is a flag indicating whether or not the script block
has been "already started". Initially,
script
elements must have this flag unset (script
blocks, when created, are not "already started"). When a
script
element is cloned, the "already started" flag,
if set, must be propagated to the clone when it is created.
The second is a flag indicating whether the element was
"parser-inserted". Initially, script
elements must have this flag unset. It is set by the HTML
parser and is used to handle document.write()
calls.
The third is a flag indicating whether or not the script block is
"ready to be parser-executed". Initially,
script
elements must have this flag unset (script
blocks, when created, are not "ready to be parser-executed"). This
flag is used only for elements that are also
"parser-inserted", to let the parser know when to
execute the script.
The fourth and fifth pieces of state are the script block's type and the script block's character encoding. They are determined when the script is run, based on the attributes on the element at that time.
When a script
element that is neither marked as
having "already started" nor marked as being
"parser-inserted" experiences one of the events listed
in the following list, the user agent must synchronously run the script
element:
script
element gets inserted into a document.script
element is in a
Document
and its child nodes are changed.script
element is in a
Document
and has a src
attribute set where previously
the element had no such attribute.Running a script: When a
script
element is to be run, the user agent must act as
follows:
If either:
script
element has a type
attribute and its value is
the empty string, orscript
element has no type
attribute but it has a language
attribute and
that attribute's value is the empty string, orscript
element has neither a type
attribute nor a language
attribute, then...let the script block's type for this
script
element be "text/javascript
".
Otherwise, if the script
element has a type
attribute, let the
script block's type for this script
element be
the value of that attribute with any leading or trailing sequences
of space characters
removed.
Otherwise, the element has a non-empty language
attribute; let
the script block's type for this script
element be the concatenation of the string "text/
" followed by the value of the language
attribute.
The language
attribute is never
conforming, and is always ignored if there is a type
attribute present.
If the script
element has a charset
attribute, then let
the script block's character encoding for this
script
element be the encoding given by the charset
attribute.
Otherwise, let the script block's character encoding
for this script
element be the same as the encoding of the document
itself.
If the script
element has a for
attribute, then the user agent
must abort these steps at this point. The script is not
executed.
If scripting is
disabled for the script
element, or if the
user agent does not support the scripting language
given by the script block's type for this
script
element, then the user agent must abort these
steps at this point. The script is not executed.
If the element has no src
attribute, and its child nodes consist only of comment nodes and
empty text nodes, then the user
agent must abort these steps at this point. The script is not
executed.
The user agent must set the element's "already started" flag.
If the element has a src
attribute, then the value of that attribute must be resolved relative to the element, and
if that is successful, the specified resource must then be fetched, from the origin of the
element's Document
.
For historical reasons, if the URL is a javascript:
URL, then the user agent must not, despite the requirements
in the definition of the fetching
algorithm, actually execute the script in the URL; instead the
user agent must act as if it had received an empty HTTP 400
response.
Once the resource's Content Type metadata is available, if it ever is, apply the algorithm for extracting an encoding from a Content-Type to it. If this returns an encoding, and the user agent supports that encoding, then let the script block's character encoding be that encoding.
For performance reasons, user agents may start fetching the
script as soon as the attribute is set, instead, in the hope that
the element will be inserted into the document. Either way, once
the element is inserted into the document, the load must have
started. If the UA performs such prefetching, but the element is
never inserted in the document, or the src
attribute is dynamically
changed, then the
user agent will not execute the script, and the fetching process
will have been effectively wasted.
Then, the first of the following options that describes the situation must be followed:
src
attribute, and the element has a defer
attribute, and the element
has been flagged as "parser-inserted", and the
element does not have an async
attributeThe element must be added to the end of the list of scripts that will execute when the document has finished parsing.
The task that the networking task source places on the task queue once the fetching algorithm has completed must set the element's "ready to be parser-executed" flag. The parser will handle executing the script.
src
attribute, and the element has been flagged as
"parser-inserted", and the element does not have an
async
attributeThe element is the pending parsing-blocking script. (There can only be one such script at a time.)
The task that the networking task source places on the task queue once the fetching algorithm has completed must set the element's "ready to be parser-executed" flag. The parser will handle executing the script.
src
attribute, but there is
a style sheet blocking scripts, and the element has
been flagged as "parser-inserted"The element is the pending parsing-blocking script. (There can only be one such script at a time.)
Set the element's "ready to be parser-executed" flag. The parser will handle executing the script.
src
attributeThe element must be added to the end of the list of scripts that will execute as soon as possible.
The task that the networking task source places on the task queue once the fetching algorithm has completed must execute the script block.
Fetching an external script must delay the load event of the element's document until the task that is queued by the networking task source once the resource has been fetched (defined above) has been run.
The pending parsing-blocking script is used by the parser.
Executing a script block: When the steps above require that the script block be executed, the user agent must act as follows:
Executing the script block must just consist of firing a simple event named
error
at the element.
Initialize the script block's source as follows:
The contents of that file, interpreted as string of Unicode characters, are the script source.
For each of the rows in the following table, starting with the first one and going down, if the file has as many or more bytes available than the number of bytes in the first column, and the first bytes of the file match the bytes given in the first column, then set the script block's character encoding to the encoding given in the cell in the second column of that row, irrespective of any previous value:
Bytes in Hexadecimal | Encoding |
---|---|
FE FF | UTF-16BE |
FF FE | UTF-16LE |
EF BB BF | UTF-8 |
This step looks for Unicode Byte Order Marks (BOMs).
The file must then be converted to Unicode using the character encoding given by the script block's character encoding.
The external file is the script source. When it is later executed, it must be interpreted in a manner consistent with the specification defining the language given by the script block's type.
The value of the text
IDL attribute at the time the element's "already
started" flag was set is the script source.
The child nodes of the script
element at the
time the element's "already started" flag was set
are the script source.
Create a
script from the script
element node, using
the script block's source and the script
block's type.
This is where the script is compiled and actually executed.
Fire a simple event named load
at the script
element.
The IDL attributes src
, type
, charset
, async
, and defer
, each must
reflect the respective content attributes of the same
name.
text
[ = value ]Returns the contents of the element, ignoring child nodes that aren't text nodes.
Can be set, to replace the element's children with the given value.
The IDL attribute text
must return a
concatenation of the contents of all the text nodes that are direct children of the
script
element (ignoring any other nodes such as
comments or elements), in tree order. On setting, it must act the
same way as the textContent
IDL attribute.
When inserted using the document.write()
method,
script
elements execute (typically synchronously), but
when inserted using innerHTML
and outerHTML
attributes, they do not
execute at all.
In this example, two script
elements are used. One
embeds an external script, and the other includes some data.
<script src="game-engine.js"></script> <script type="text/x-game-map"> ........U.........e o............A....e .....A.....AAA....e .A..AAA...AAAAA...e </script>
The data in this case might be used by the script to generate the map of a video game. The data doesn't have to be used that way, though; maybe the map data is actually embedded in other parts of the page's markup, and the data block here is just used by the site's search engine to help users who are looking for particular features in their game maps.
The following sample shows how a script element can be used to
define a function that is then used by other parts of the
document. It also shows how a script
element can be
used to invoke script while the document is being parsed, in this
case to initialize the form's output.
<script> function calculate(form) { var price = 52000; if (form.elements.brakes.checked) price += 1000; if (form.elements.radio.checked) price += 2500; if (form.elements.turbo.checked) price += 5000; if (form.elements.sticker.checked) price += 250; form.elements.result.value = price; } </script> <form name="pricecalc" onsubmit="return false"> <fieldset> <legend>Work out the price of your car</legend> <p>Base cost: £52000.</p> <p>Select additional options:</p> <ul> <li><label><input type=checkbox name=brakes> Ceramic brakes (£1000)</label></li> <li><label><input type=checkbox name=radio> Satellite radio (£2500)</label></li> <li><label><input type=checkbox name=turbo> Turbo charger (£5000)</label></li> <li><label><input type=checkbox name=sticker> "XZ" sticker (£250)</label></li> </ul> <p>Total: £<output name=result onformchange="calculate(form)"></output></p> </fieldset> <script> document.forms.pricecalc.dispatchFormChange(); </script> </form>
Status: Last call for comments
A user agent is said to support the scripting language if the script block's type is an ASCII case-insensitive match for the MIME type string of a scripting language that the user agent implements.
The following lists some MIME type strings and the languages to which they refer:
application/ecmascript
"application/javascript
"application/x-ecmascript
"application/x-javascript
"text/ecmascript
"text/javascript
"text/javascript1.0
"text/javascript1.1
"text/javascript1.2
"text/javascript1.3
"text/javascript1.4
"text/javascript1.5
"text/jscript
"text/livescript
"text/x-ecmascript
"text/x-javascript
"text/javascript;e4x=1
"User agents may support other MIME types and other languages.
When examining types to determine if they support the language,
user agents must not ignore unknown MIME parameters — types
with unknown parameters must be assumed to be unsupported. The charset
parameter must be treated as an unknown
parameter for the purpose of comparing MIME
types here.
script
elementsStatus: Last call for comments
The textContent
of a script
element must match the
script
production in the following ABNF, the
character set for which is Unicode. [ABNF]
script = data1 *( escape [ script-start data3 ] "-->" data1 ) [ escape ] escape = "<!--" data2 *( script-start data3 script-end data2 ) data1 = <any string that doesn't contain a substring that matches not-data1> not-data1 = "<!--" data2 = <any string that doesn't contain a substring that matches not-data2> not-data2 = script-start / "-->" data3 = <any string that doesn't contain a substring that matches not-data3> not-data3 = script-end / "-->" script-start = lt s c r i p t tag-end script-end = lt slash s c r i p t tag-end lt = %x003C ; U+003C LESS-THAN SIGN character (<) slash = %x002F ; U+002F SOLIDUS character (/) 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 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.
Status: Last call for comments
If a script
element's src
attribute is specified, then the
contents of the script
element, if any, must be such
that the value of the text
IDL
attribute, which is derived from the element's contents, matches the
documentation
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 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 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>
noscript
elementStatus: Last call for comments
head
element of an HTML document, if there are no ancestor noscript
elements.noscript
elements.head
element: in any order, zero or more link
elements, zero or more style
elements, and zero or more meta
elements.head
element: transparent, but there must be no noscript
element descendants.HTMLElement
.The noscript
element represents nothing
if scripting is enabled, and
represents its children if scripting is disabled. It is used
to present different markup to user agents that support scripting
and those that don't support scripting, by affecting how the
document is parsed.
When used in HTML documents, the allowed content model is as follows:
head
element, if scripting is disabled for the
noscript
elementThe noscript
element must contain only
link
, style
, and meta
elements.
head
element, if scripting is enabled for the
noscript
elementThe noscript
element must contain only text,
except that invoking the HTML fragment parsing
algorithm with
the noscript
element as the context element and the text contents as the input must result in a list of nodes that consists
only of link
, style
, and
meta
elements that would be conforming if they were
children of the noscript
element, and no parse errors.
head
elements, if scripting is disabled for the
noscript
elementThe noscript
element's content model is
transparent, with the additional restriction that a
noscript
element must not have a noscript
element as an ancestor (that is, noscript
can't be
nested).
head
elements, if scripting is enabled for the
noscript
elementThe noscript
element must contain only text,
except that the text must be such that running the following
algorithm results in a conforming document with no
noscript
elements and no script
elements, and such that no step in the algorithm causes an
HTML parser to flag a parse error:
script
element from the
document.noscript
element in the
document. For every noscript
element in that list,
perform the following steps:
noscript
element.noscript
element, and call these
elements the before children.noscript
element, and
call these elements the after children.noscript
element.innerHTML
attribute of the parent element to the value
of s. (This, as a side-effect, causes the
noscript
element to be removed from the
document.)All these contortions are required because, for
historical reasons, the noscript
element is handled
differently by the HTML parser based on whether 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.
The noscript
element has no other requirements. In
particular, children of the noscript
element are not
exempt from 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.
Status: Last call for comments
body
elementStatus: Last call for comments
html
element.onafterprint
onbeforeprint
onbeforeunload
onblur
onerror
onfocus
onhashchange
onload
onmessage
onoffline
ononline
onpagehide
onpageshow
onpopstate
onredo
onresize
onstorage
onundo
onunload
interface HTMLBodyElement : HTMLElement { attribute Function onafterprint; attribute Function onbeforeprint; attribute Function onbeforeunload; attribute Function onblur; attribute Function onerror; attribute Function onfocus; attribute Function onhashchange; attribute Function onload; attribute Function onmessage; attribute Function onoffline; attribute Function ononline; attribute Function onpopstate; attribute Function onpagehide; attribute Function onpageshow; attribute Function onredo; attribute Function onresize; attribute Function onstorage; attribute Function onundo; attribute Function onunload; };
The body
element represents the main
content of the document.
In conforming documents, there is only one body
element. The document.body
IDL attribute provides scripts with easy access to a document's
body
element.
Some DOM operations (for example, parts of the
drag and drop model) are defined in terms of "the
body element". This refers to a particular element in the
DOM, as per the definition of the term, and not any arbitrary
body
element.
The body
element exposes as event handler
content attributes a number of the event
handlers of the Window
object. It also mirrors
their event handler IDL attributes.
The onblur
, onerror
, onfocus
, and onload
event
handlers of the Window
object, exposed on the
body
element, shadow the generic event
handlers with the same names normally supported by HTML
elements.
Thus, for example, a bubbling error
event fired on a child of the
body element of a Document
would first trigger
the onerror
event handler
content attributes of that element, then that of the root
html
element, and only then would it trigger
the onerror
event handler content
attribute on the body
element. This is because
the event would bubble from the target, to the body
, to
the html
, to the Document
, to the
Window
, and the event
handler on the body
is watching the
Window
not the body
. A regular event
listener attached to the body
using addEventListener()
, however, would fire when the
event bubbled through the body
and not when it reaches
the Window
object.
This page updates an indicator to show whether or not the user is online:
<!DOCTYPE HTML> <html> <head> <title>Online or offline?</title> <script> function update(online) { document.getElementById('status').textContent = online ? 'Online' : 'Offline'; } </script> </head> <body ononline="update(true)" onoffline="update(false)" onload="update(navigator.onLine)"> <p>You are: <span id="status">(Unknown)</span></p> </body> </html>
section
elementStatus: Last call for comments
formatBlock
candidate.HTMLElement
.The section
element represents a
generic document or application section. A section, in this context,
is a thematic grouping of content, typically with a heading.
Examples of sections would be chapters, the various tabbed pages in a tabbed dialog box, or the numbered sections of a thesis. A Web site's home page could be split into sections for an introduction, news items, contact information.
Authors are encouraged to use the
article
element instead of the section
element when it would make sense to syndicate the contents of the
element.
The section
element is not a generic container element. When an element is
needed for styling purposes or as a convenience for scripting,
authors are encouraged to use the div
element
instead. A general rule is that the section
element is
appropriate only if the element's contents would be listed
explicitly in the document's outline.
In the following example, we see an article (part of a larger Web page) about apples, containing two short sections.
<article> <hgroup> <h1>Apples</h1> <h2>Tasty, delicious fruit!</h2> </hgroup> <p>The apple is the pomaceous fruit of the apple tree.</p> <section> <h1>Red Delicious</h1> <p>These bright red apples are the most common found in many supermarkets.</p> </section> <section> <h1>Granny Smith</h1> <p>These juicy, green apples make a great filling for apple pies.</p> </section> </article>
Notice how the use of section
means that the author
can use h1
elements throughout, without having to
worry about whether a particular section is at the top level, the
second level, the third level, and so on.
Here is a graduation programme with two sections, one for the list of people graduating, and one for the description of the ceremony.
<!DOCTYPE Html> <Html ><Head ><Title >Graduation Ceremony Summer 2022</Title ></Head ><Body ><H1 >Graduation</H1 ><Section ><H1 >Ceremony</H1 ><P >Opening Procession</P ><P >Speech by Validactorian</P ><P >Speech by Class President</P ><P >Presentation of Diplomas</P ><P >Closing Speech by Headmaster</P ></Section ><Section ><H1 >Graduates</H1 ><Ul ><Li >Molly Carpenter</Li ><Li >Anastasia Luccio</Li ><Li >Ebenezar McCoy</Li ><Li >Karrin Murphy</Li ><Li >Thomas Raith</Li ><Li >Susan Rodriguez</Li ></Ul ></Section ></Body ></Html>
nav
elementStatus: Last call for comments
formatBlock
candidate.HTMLElement
.The nav
element represents a section of
a page that links to other pages or to parts within the page: a
section with navigation links.
Not all groups of links on a page need to be in a
nav
element — only sections that consist of major
navigation blocks are appropriate for the nav
element. In particular, it is common for footers to have a short
list of links to various pages of a site, such as the terms of
service, the home page, and a copyright page. The
footer
element alone is sufficient for such cases,
without a nav
element.
User agents (such as screen readers) that are targeted at users who can benefit from navigation information being omitted in the initial rendering, or who can benefit from navigation information being immediately available, can use this element as a way to determine what content on the page to initially skip and/or provide on request.
In the following example, the page has several places where links are present, but only one of those places is considered a navigation section.
<body> <header> <h1>Wake up sheeple!</h1> <p><a href="news.html">News</a> - <a href="blog.html">Blog</a> - <a href="forums.html">Forums</a></p> <p>Last Modified: <time>2009-04-01</time></p> <nav> <h1>Navigation</h1> <ul> <li><a href="articles.html">Index of all articles</a></li> <li><a href="today.html">Things sheeple need to wake up for today</a></li> <li><a href="successes.html">Sheeple we have managed to wake</a></li> </ul> </nav> </header> <div> <article> <header> <h1>My Day at the Beach</h1> </header> <div> <p>Today I went to the beach and had a lot of fun.</p> ...more content... </div> <footer> <p>Posted <time pubdate datetime="2009-10-10T14:36-08:00">Thursday</time>.</p> </footer> </article> ...more blog posts... </div> <footer> <p>Copyright © 2006 The Example Company</p> <p><a href="about.html">About</a> - <a href="policy.html">Privacy Policy</a> - <a href="contact.html">Contact Us</a></p> </footer> </body>
Notice the div
elements being used to wrap all the
contents of the page other than the header and footer, and all the
contents of the blog entry other than its header and footer.
In the following example, there are two nav
elements, one for primary navigation around the site, and one for
secondary navigation around the page itself.
<body> <h1>The Wiki Center Of Exampland</h1> <nav> <ul> <li><a href="/">Home</a></li> <li><a href="/events">Current Events</a></li> ...more... </ul> </nav> <article> <header> <h1>Demos in Exampland</h1> <p>Written by A. N. Other.</p> </header> <nav> <ul> <li><a href="#public">Public demonstrations</a></li> <li><a href="#destroy">Demolitions</a></li> ...more... </ul> </nav> <div> <section id="public"> <h1>Public demonstrations</h1> <p>...more...</p> </section> <section id="destroy"> <h1>Demolitions</h1> <p>...more...</p> </section> ...more... </div> <footer> <p><a href="?edit">Edit</a> | <a href="?delete">Delete</a> | <a href="?Rename">Rename</a></p> </footer> </article> <footer> <p><small>© copyright 1998 Exampland Emperor</small></p> </footer> </body>
article
elementStatus: Last call for comments
formatBlock
candidate.HTMLElement
.The article
element represents a
component of a page that consists of a self-contained composition in
a document, page, application, or site and that is intended to be
independently distributable or reusable, e.g. in syndication. This
could be a forum post, a magazine or newspaper article, a blog
entry, a user-submitted comment, an interactive widget or gadget, or
any other independent item of content.
When article
elements are nested, the inner
article
elements represent articles that are in
principle related to the contents of the outer article. For
instance, a blog entry on a site that accepts user-submitted
comments could represent the comments as article
elements nested within the article
element for the blog
entry.
Author information associated with an article
element (q.v. the address
element) does not apply to
nested article
elements.
When used specifically with content to be
redistributed in syndication, the article
element is
similar in purpose to the entry
element in
Atom. [ATOM]
The time
element's pubdate
attribute can be used to
provide the publication date for an article
element.
This example shows a blog post using the article
element:
<article> <header> <h1>The Very First Rule of Life</h1> <p><time pubdate datetime="2009-10-09T14:28-08:00"></time></p> </header> <p>If there's a microphone anywhere near you, assume it's hot and sending whatever you're saying to the world. Seriously.</p> <p>...</p> <footer> <a href="?comments=1">Show comments...</a> </footer> </article>
Here is that same blog post, but showing some of the comments:
<article> <header> <h1>The Very First Rule of Life</h1> <p><time pubdate datetime="2009-10-09T14:28-08:00"></time></p> </header> <p>If there's a microphone anywhere near you, assume it's hot and sending whatever you're saying to the world. Seriously.</p> <p>...</p> <section> <h1>Comments</h1> <article> <footer> <p>Posted by: George Washington</p> <p><time pubdate datetime="2009-10-10T19:10-08:00"></time></p> </footer> <p>Yeah! Especially when talking about your lobbyist friends!</p> </article> <article> <footer> <p>Posted by: George Hammond</p> <p><time pubdate datetime="2009-10-10T19:15-08:00"></time></p> </footer> <p>Hey, you have the same first name as me.</p> </article> </section> </article>
Notice the use of footer
to give the information
each comment (such as who wrote it and when): the
footer
element can appear at the start of its
section when appropriate, such as in this case. (Using
header
in this case wouldn't be wrong either; it's
mostly a matter of authoring preference.)
aside
elementStatus: Last call for comments. ISSUE-91 (aside) blocks progress to Last Call
formatBlock
candidate.HTMLElement
.The aside
element represents a section
of a page that consists of content that is tangentially related to
the content around the aside
element, and which could
be considered separate from that content. Such sections are often
represented as sidebars in printed typography.
The element can be used for typographical effects like pull
quotes or sidebars, for advertising, for groups of nav
elements, and for other content that is considered separate from the
main content of the page.
It's not appropriate to use the aside
element just for parentheticals, since those are part of the main
flow of the document.
The following example shows how an aside is used to mark up background material on Switzerland in a much longer news story on Europe.
<aside> <h1>Switzerland</h1> <p>Switzerland, a land-locked country in the middle of geographic Europe, has not joined the geopolitical European Union, though it is a signatory to a number of European treaties.</p> </aside>
The following example shows how an aside is used to mark up a pull quote in a longer article.
... <p>He later joined a large company, continuing on the same work. <q>I love my job. People ask me what I do for fun when I'm not at work. But I'm paid to do my hobby, so I never know what to answer. Some people wonder what they would do if they didn't have to work... but I know what I would do, because I was unemployed for a year, and I filled that time doing exactly what I do now.</q></p> <aside> <q> People ask me what I do for fun when I'm not at work. But I'm paid to do my hobby, so I never know what to answer. </q> </aside> <p>Of course his work — or should that be hobby? — isn't his only passion. He also enjoys other pleasures.</p> ...
The following extract shows how aside
can be used
for blogrolls and other side content on a blog:
<body> <header> <h1>My wonderful blog</h1> <p>My tagline</p> </header> <aside> <!-- this aside contains two sections that are tangentially related to the page, namely, links to other blogs, and links to blog posts from this blog --> <nav> <h1>My blogroll</h1> <ul> <li><a href="http://blog.example.com/">Example Blog</a> </ul> </nav> <nav> <h1>Archives</h1> <ol reversed> <li><a href="/last-post">My last post</a> <li><a href="/first-post">My first post</a> </ol> </nav> </aside> <aside> <!-- this aside is tangentially related to the page also, it contains twitter messages from the blog author --> <h1>Twitter Feed</h1> <blockquote cite="http://twitter.example.net/t31351234"> <p>I'm on vacation, writing my blog.</p> </blockquote> <blockquote cite="http://twitter.example.net/t31219752"> <p>I'm going to go on vacation soon.</p> </blockquote> </aside> <article> <!-- this is a blog post --> <h1>My last post</h1> <p>This is my last post.</p> <footer> <p><a href="/last-post" rel=bookmark>Permalink</a> </footer> </article> <article> <!-- this is also a blog post --> <h1>My first post</h1> <p>This is my first post.</p> <aside> <!-- this aside is about the blog post, since it's inside the <article> element; it would be wrong, for instance, to put the blogroll here, since the blogroll isn't really related to this post specifically, only to the page as a whole --> <h1>Posting</h1> <p>While I'm thinking about it, I wanted to say something about posting. Posting is fun!</p> </aside> <footer> <p><a href="/first-post" rel=bookmark>Permalink</a> </footer> </article> <footer> <nav> <a href="/archives">Archives</a> — <a href="/about">About me</a> — <a href="/copyright">Copyright</a> </nav> </footer> </body>
h1
, h2
,
h3
, h4
,
h5
, and h6
elementsformatBlock
candidate.hgroup
element.interface HTMLHeadingElement : HTMLElement {};
These elements represent headings for their sections.
The semantics and meaning of these elements are defined in the section on headings and sections.
These elements have a rank given by the number in
their name. The h1
element is said to have the highest
rank, the h6
element has the lowest rank, and two
elements with the same name have equal rank.
These two snippets are equivalent:
<body> <h1>Let's call it a draw(ing surface)</h1> <h2>Diving in</h2> <h2>Simple shapes</h2> <h2>Canvas coordinates</h2> <h3>Canvas coordinates diagram</h3> <h2>Paths</h2> </body>
<body> <h1>Let's call it a draw(ing surface)</h1> <section> <h1>Diving in</h1> </section> <section> <h1>Simple shapes</h1> </section> <section> <h1>Canvas coordinates</h1> <section> <h1>Canvas coordinates diagram</h1> </section> </section> <section> <h1>Paths</h1> </section> </body>
hgroup
elementStatus: Last call for comments
formatBlock
candidate.h1
, h2
, h3
, h4
, h5
, and/or h6
elements.HTMLElement
.The hgroup
element represents the
heading of a section. The element is used to group a set of
h1
–h6
elements when the heading has
multiple levels, such as subheadings, alternative titles, or
taglines.
For the purposes of document summaries, outlines, and the like,
the text of hgroup
elements is defined to be the text
of the highest ranked
h1
–h6
element descendant of the
hgroup
element, if there are any such elements, and the
first such element if there are multiple elements with that
rank. If there are no such elements, then the text of
the hgroup
element is the empty string.
Other elements of heading content in the
hgroup
element indicate subheadings or subtitles.
The rank of an hgroup
element is the
rank of the highest-ranked h1
–h6
element descendant of the hgroup
element, if there are
any such elements, or otherwise the same as for an h1
element (the highest rank).
The section on headings and sections
defines how hgroup
elements are assigned to individual
sections.
Here are some examples of valid headings. In each case, the emphasized text represents the text that would be used as the heading in an application extracting heading data and ignoring subheadings.
<hgroup> <h1>The reality dysfunction</h1> <h2>Space is not the only void</h2> </hgroup>
<hgroup> <h1>Dr. Strangelove</h1> <h2>Or: How I Learned to Stop Worrying and Love the Bomb</h2> </hgroup>
The point of using hgroup
in these examples is to
mask the h2
element (which acts as a secondary title)
from the outline algorithm.
header
elementStatus: Last call for comments
formatBlock
candidate.header
or
footer
element descendants.HTMLElement
.The header
element represents a group
of introductory or navigational aids.
A header
element is intended to usually
contain the section's heading (an
h1
–h6
element or an
hgroup
element), but this is not required. The
header
element can also be used to wrap a section's
table of contents, a search form, or any relevant logos.
Here are some sample headers. This first one is for a game:
<header> <p>Welcome to...</p> <h1>Voidwars!</h1> </header>
The following snippet shows how the element can be used to mark up a specification's header:
<header> <hgroup> <h1>Scalable Vector Graphics (SVG) 1.2</h1> <h2>W3C Working Draft 27 October 2004</h2> </hgroup> <dl> <dt>This version:</dt> <dd><a href="http://www.w3.org/TR/2004/WD-SVG12-20041027/">http://www.w3.org/TR/2004/WD-SVG12-20041027/</a></dd> <dt>Previous version:</dt> <dd><a href="http://www.w3.org/TR/2004/WD-SVG12-20040510/">http://www.w3.org/TR/2004/WD-SVG12-20040510/</a></dd> <dt>Latest version of SVG 1.2:</dt> <dd><a href="http://www.w3.org/TR/SVG12/">http://www.w3.org/TR/SVG12/</a></dd> <dt>Latest SVG Recommendation:</dt> <dd><a href="http://www.w3.org/TR/SVG/">http://www.w3.org/TR/SVG/</a></dd> <dt>Editor:</dt> <dd>Dean Jackson, W3C, <a href="mailto:dean@w3.org">dean@w3.org</a></dd> <dt>Authors:</dt> <dd>See <a href="#authors">Author List</a></dd> </dl> <p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notic ... </header>
The header
element is not
sectioning content; it doesn't introduce a new
section.
In this example, the page has a page heading given by the
h1
element, and two subsections whose headings are
given by h2
elements. The content after the
header
element is still part of the last subsection
started in the header
element, because the
header
element doesn't take part in the
outline algorithm.
<body> <header> <h1>Little Green Guys With Guns</h1> <nav> <ul> <li><a href="/games">Games</a> <li><a href="/forum">Forum</a> <li><a href="/download">Download</a> </ul> </nav> <h2>Important News</h2> <!-- this starts a second subsection --> <!-- this is part of the subsection entitled "Important News" --> <p>To play today's games you will need to update your client.</p> <h2>Games</h2> <!-- this starts a third subsection --> </header> <p>You have three active games:</p> <!-- this is still part of the subsection entitled "Games" --> ...
footer
elementStatus: Last call for comments
formatBlock
candidate.header
or
footer
element descendants.HTMLElement
.The footer
element represents a footer
for its nearest ancestor sectioning content or
sectioning root element. A footer typically contains
information about its section such as who wrote it, links to related
documents, copyright data, and the like.
Contact information for the author or editor of a
section belongs in an address
element, possibly itself
inside a footer
.
Footers don't necessarily have to appear at the end of a section, though they usually do.
When the footer
element contains entire sections,
they represent appendices, indexes,
long colophons, verbose license agreements, and other such
content.
The footer
element is not
sectioning content; it doesn't introduce a new
section.
When the nearest ancestor sectioning content or sectioning root element is the body element, then it applies to the whole page.
Here is a page with two footers, one at the top and one at the bottom, with the same content:
<body> <footer><a href="../">Back to index...</a></footer> <hgroup> <h1>Lorem ipsum</h1> <h2>The ipsum of all lorems</h2> </hgroup> <p>A dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p> <footer><a href="../">Back to index...</a></footer> </body>
Here is an example which shows the footer
element
being used both for a site-wide footer and for a section
footer.
<!DOCTYPE HTML> <HTML><HEAD> <TITLE>The Ramblings of a Scientist</TITLE> <BODY> <H1>The Ramblings of a Scientist</H1> <ARTICLE> <H1>Episode 15</H1> <VIDEO SRC="/fm/015.ogv" CONTROLS PRELOAD> <P><A HREF="/fm/015.ogv">Download video</A>.</P> </VIDEO> <FOOTER> <!-- footer for article --> <P>Published <TIME PUBDATE DATETIME="2009-10-21T18:26-07:00"></TIME></P> </FOOTER> </ARTICLE> <ARTICLE> <H1>My Favorite Trains</H1> <P>I love my trains. My favorite train of all time is a Köf.</P> <P>It is fun to see them pull some coal cars because they look so dwarfed in comparison.</P> <FOOTER> <!-- footer for article --> <P>Published <TIME PUBDATE DATETIME="2009-09-15T14:54-07:00"></TIME></P> </FOOTER> </ARTICLE> <FOOTER> <!-- site wide footer --> <NAV> <P><A HREF="/credits.html">Credits</A> — <A HREF="/tos.html">Terms of Service</A> — <A HREF="/index.html">Blog Index</A></P> </NAV> <P>Copyright © 2009 Gordon Freeman</P> </FOOTER> </BODY> </HTML>
address
elementStatus: Last call for comments
formatBlock
candidate.header
, footer
, or
address
element descendants.HTMLElement
.The address
element represents the
contact information for its nearest article
or
body
element ancestor. If that is the body
element, then the contact information applies to the document
as a whole.
For example, a page at the W3C Web site related to HTML might include the following contact information:
<ADDRESS> <A href="../People/Raggett/">Dave Raggett</A>, <A href="../People/Arnaud/">Arnaud Le Hors</A>, contact persons for the <A href="Activity">W3C HTML Activity</A> </ADDRESS>
The address
element must not be used to represent
arbitrary addresses (e.g. postal addresses), unless those addresses
are in fact the relevant contact information. (The p
element is the appropriate element for marking up postal addresses
in general.)
The address
element must not contain information
other than contact information.
For example, the following is non-conforming use of the
address
element:
<ADDRESS>Last Modified: 1999/12/24 23:37:50</ADDRESS>
Typically, the address
element would be included
along with other information in a footer
element.
The contact information for a node node is a
collection of address
elements defined by the first
applicable entry from the following list:
article
elementbody
elementThe contact information consists of all the
address
elements that have node
as an ancestor and do not have another body
or
article
element ancestor that is a descendant of node.
article
elementbody
elementThe contact information of node is the same
as the contact information of the nearest article
or
body
element ancestor, whichever is nearest.
Document
has a body elementThe contact information of node is the same
as the contact information the body element of the
Document
.
There is no contact information for node.
User agents may expose the contact information of a node to the user, or use it for other purposes, such as indexing sections based on the sections' contact information.
Status: Last call for comments
The h1
–h6
elements and the
hgroup
element are headings.
The first element of heading content in an element of sectioning content represents the heading for that section. Subsequent headings of equal or higher rank start new (implied) sections, headings of lower rank start implied subsections that are part of the previous one. In both cases, the element represents the heading of the implied section.
Sectioning content elements are always considered subsections of their nearest ancestor element of sectioning content, regardless of what implied sections other headings may have created.
Certain elements are said to be sectioning roots, including blockquote
and
td
elements. These elements can have their own
outlines, but the sections and headings inside these elements do not
contribute to the outlines of their ancestors.
For the following fragment:
<body> <h1>Foo</h1> <h2>Bar</h2> <blockquote> <h3>Bla</h3> </blockquote> <p>Baz</p> <h2>Quux</h2> <section> <h3>Thud</h3> </section> <p>Grunt</p> </body>
...the structure would be:
body
section, containing the "Grunt" paragraph)
section
section)
Notice how the section
ends the earlier implicit
section so that a later paragraph ("Grunt") is back at the top
level.
Sections may contain headings of any rank, but
authors are strongly encouraged to either use only h1
elements, or to use elements of the appropriate rank
for the section's nesting level.
Authors are also encouraged to explicitly wrap sections in elements of sectioning content, instead of relying on the implicit sections generated by having multiple headings in one element of sectioning content.
For example, the following is correct:
<body> <h4>Apples</h4> <p>Apples are fruit.</p> <section> <h2>Taste</h2> <p>They taste lovely.</p> <h6>Sweet</h6> <p>Red apples are sweeter than green ones.</p> <h1>Color</h1> <p>Apples come in various colors.</p> </section> </body>
However, the same document would be more clearly expressed as:
<body> <h1>Apples</h1> <p>Apples are fruit.</p> <section> <h2>Taste</h2> <p>They taste lovely.</p> <section> <h3>Sweet</h3> <p>Red apples are sweeter than green ones.</p> </section> </section> <section> <h2>Color</h2> <p>Apples come in various colors.</p> </section> </body>
Both of the documents above are semantically identical and would produce the same outline in compliant user agents.
Status: Last call for comments
This section defines an algorithm for creating an outline for a sectioning content element or a sectioning root element. It is defined in terms of a walk over the nodes of a DOM tree, in tree order, with each node being visited when it is entered and when it is exited during the walk.
The outline for a sectioning content
element or a sectioning root element consists of a list
of one or more potentially nested sections. A section is a container that
corresponds to some nodes in the original DOM tree. Each section can
have one heading associated with it, and can contain any number of
further nested sections. The algorithm for the
outline also associates each node in the DOM tree with a particular
section and potentially a heading. (The sections in the
outline aren't section
elements, though some may
correspond to such elements — they are merely conceptual
sections.)
The following markup fragment:
<body> <h1>A</h1> <p>B</p> <h2>C</h2> <p>D</p> <h2>E</h2> <p>F</p> </body>
...results in the following outline being created for the
body
node (and thus the entire document):
Section created for body
node.
Associated with heading "A".
Also associated with paragraph "B".
Nested sections:
The algorithm that must be followed during a walk of a DOM subtree rooted at a sectioning content element or a sectioning root element to determine that element's outline is as follows:
Let current outlinee be null. (It holds the element whose outline is being created.)
Let current section be null. (It holds a pointer to a section, so that elements in the DOM can all be associated with a section.)
Create a stack to hold elements, which is used to handle nesting. Initialize this stack to empty.
As you walk over the DOM in tree order, trigger the first relevant step below for each element as you enter and exit it.
The element being exited is a heading content element.
Pop that element from the stack.
Do nothing.
If current outlinee is not null, and the current section has no heading, create an implied heading and let that be the heading for the current section.
If current outlinee is not null, push current outlinee onto the stack.
Let current outlinee be the element that is being entered.
Let current section be a newly created section for the current outlinee element.
Let there be a new outline for the new current outlinee, initialized with just the new current section as the only section in the outline.
Pop the top element from the stack, and let the current outlinee be that element.
Let current section be the last section in the outline of the current outlinee element.
Append the outline of the sectioning content element being exited to the current section. (This does not change which section is the last section in the outline.)
Run these steps:
Pop the top element from the stack, and let the current outlinee be that element.
Let current section be the last section in the outline of the current outlinee element.
Finding the deepest child: If current section has no child sections, stop these steps.
Let current section be the last child section of the current current section.
Go back to the substep labeled finding the deepest child.
The current outlinee is the element being exited.
Let current section be the first section in the outline of the current outlinee element.
Skip to the next step in the overall set of steps. (The walk is over.)
Do nothing.
If the current section has no heading, let the element being entered be the heading for the current section.
Otherwise, if the element being entered has a rank equal to or greater than the heading of the last section of the outline of the current outlinee, then create a new section and append it to the outline of the current outlinee element, so that this new section is the new last section of that outline. Let current section be that new section. Let the element being entered be the new heading for the current section.
Otherwise, run these substeps:
Let candidate section be current section.
If the element being entered has a rank lower than the rank of the heading of the candidate section, then create a new section, and append it to candidate section. (This does not change which section is the last section in the outline.) Let current section be this new section. Let the element being entered be the new heading for the current section. Abort these substeps.
Let new candidate section be the section that contains candidate section in the outline of current outlinee.
Let candidate section be new candidate section.
Return to step 2.
Push the element being entered onto the stack. (This causes the algorithm to skip any descendants of the element.)
Recall that h1
has the
highest rank, and h6
has the lowest
rank.
Do nothing.
In addition, whenever you exit a node, after doing the steps above, if current section is not null, associate the node with the section current section.
If the current outlinee is null, then there was no sectioning content element or sectioning root element in the DOM. There is no outline. Abort these steps.
Associate any nodes that were not associated with a section in the steps above with current outlinee as their section.
Associate all nodes with the heading of the section with which they are associated, if any.
If current outlinee is the body element, then the outline created for that element is the outline of the entire document.
The tree of sections created by the algorithm above, or a proper subset thereof, must be used when generating document outlines, for example when generating tables of contents.
When creating an interactive table of contents, entries should jump the user to the relevant sectioning content element, if the section was created for a real element in the original document, or to the relevant heading content element, if the section in the tree was generated for a heading in the above process.
Selecting the first section of the document therefore
always takes the user to the top of the document, regardless of
where the first heading in the body
is to be found.
The outline depth of a heading content
element associated with a section section
is the number of sections that
are ancestors of section in the
outline that section finds itself
in when the outlines of its
Document
's elements are created, plus 1. The
outline depth of a heading content element
not associated with a section
is 1.
User agents should provide default headings for sections that do not have explicit section headings.
Consider the following snippet:
<body> <nav> <p><a href="/">Home</a></p> </nav> <p>Hello world.</p> <aside> <p>My cat is cute.</p> </aside> </body>
Although it contains no headings, this snippet has three
sections: a document (the body
) with two subsections
(a nav
and an aside
). A user agent could
present the outline as follows:
These default headings ("Untitled document", "Navigation", "Sidebar") are not specified by this specification, and might vary with the user's language, the page's language, the user's preferences, the user agent implementor's preferences, etc.
The following JavaScript function shows how the tree walk could be implemented. The root argument is the root of the tree to walk, and the enter and exit arguments are callbacks that are called with the nodes as they are entered and exited. [ECMA262]
function (root, enter, exit) { var node = root; start: while (node) { enter(node); if (node.firstChild) { node = node.firstChild; continue start; } while (node) { exit(node); if (node.nextSibling) { node = node.nextSibling; continue start; } if (node == root) node = null; else node = node.parentNode; } } }
Status: Last call for comments
p
elementStatus: Last call for comments
formatBlock
candidate.interface HTMLParagraphElement : HTMLElement {};
The p
element represents a
paragraph.
The following examples are conforming HTML fragments:
<p>The little kitten gently seated himself on a piece of carpet. Later in his life, this would be referred to as the time the cat sat on the mat.</p>
<fieldset> <legend>Personal information</legend> <p> <label>Name: <input name="n"></label> <label><input name="anon" type="checkbox"> Hide from other users</label> </p> <p><label>Address: <textarea name="a"></textarea></label></p> </fieldset>
<p>There was once an example from Femley,<br> Whose markup was of dubious quality.<br> The validator complained,<br> So the author was pained,<br> To move the error from the markup to the rhyming.</p>
The p
element should not be used when a more
specific element is more appropriate.
The following example is technically correct:
<section> <!-- ... --> <p>Last modified: 2001-04-23</p> <p>Author: fred@example.com</p> </section>
However, it would be better marked-up as:
<section> <!-- ... --> <footer>Last modified: 2001-04-23</footer> <address>Author: fred@example.com</address> </section>
Or:
<section> <!-- ... --> <footer> <p>Last modified: 2001-04-23</p> <address>Author: fred@example.com</address> </footer> </section>
hr
elementStatus: Last call for comments
interface HTMLHRElement : HTMLElement {};
The hr
element represents a
paragraph-level thematic break, e.g. a scene change in
a story, or a transition to another topic within a section of a
reference book.
The following extract from Pandora's Star by Peter
F. Hamilton shows two paragraphs that precede a scene change and
the paragraph that follows it. The scene change, represented in the
printed book by a gap containing a solitary centered star between
the second and third paragraphs, is here represented using the
hr
element.
<p>Dudley was ninety-two, in his second life, and fast approaching
time for another rejuvenation. Despite his body having the physical
age of a standard fifty-year-old, the prospect of a long degrading
campaign within academia was one he regarded with dread. For a
supposedly advanced civilization, the Intersolar Commonwearth could be
appallingly backward at times, not to mention cruel.</p>
<p><i>Maybe it won't be that bad</i>, he told himself. The lie was
comforting enough to get him through the rest of the night's
shift.</p>
<hr>
<p>The Carlton AllLander drove Dudley home just after dawn. Like the
astronomer, the vehicle was old and worn, but perfectly capable of
doing its job. It had a cheap diesel engine, common enough on a
semi-frontier world like Gralmond, although its drive array was a
thoroughly modern photoneural processor. With its high suspension and
deep-tread tyres it could plough along the dirt track to the
observatory in all weather and seasons, including the metre-deep snow
of Gralmond's winters.</p>
br
elementStatus: Last call for comments
interface HTMLBRElement : HTMLElement {};
The br
element represents a line
break.
br
elements must be used only for line breaks that
are actually part of the content, as in poems or addresses.
The following example is correct usage of the br
element:
<p>P. Sherman<br> 42 Wallaby Way<br> Sydney</p>
br
elements must not be used for separating thematic
groups in a paragraph.
The following examples are non-conforming, as they abuse the
br
element:
<p><a ...>34 comments.</a><br> <a ...>Add a comment.</a></p>
<p><label>Name: <input name="name"></label><br> <label>Address: <input name="address"></label></p>
Here are alternatives to the above, which are correct:
<p><a ...>34 comments.</a></p> <p><a ...>Add a comment.</a></p>
<p><label>Name: <input name="name"></label></p> <p><label>Address: <input name="address"></label></p>
If a paragraph consists of nothing but a single
br
element, it represents a placeholder blank line
(e.g. as in a template). Such blank lines must not be used for
presentation purposes.
Any content inside br
elements must not be
considered part of the surrounding text.
A br
element does not separate paragraphs for the
purposes of the Unicode bidirectional algorithm. [BIDI]
pre
elementStatus: Last call for comments
formatBlock
candidate.interface HTMLPreElement : HTMLElement {};
The pre
element represents a block of
preformatted text, in which structure is represented by typographic
conventions rather than by elements.
In the HTML syntax, a leading
newline character immediately following the pre
element
start tag is stripped.
Some examples of cases where the pre
element could
be used:
Authors are encouraged to consider how preformatted text will be experienced when the formatting is lost, as will be the case for users of speech synthesizers, braille displays, and the like. For cases like ASCII art, it is likely that an alternative presentation, such as a textual description, would be more universally accessible to the readers of the document.
To represent a block of computer code, the pre
element can be used with a code
element; to represent a
block of computer output the pre
element can be used
with a samp
element. Similarly, the kbd
element can be used within a pre
element to indicate
text that the user is to enter.
In the following snippet, a sample of computer code is presented.
<p>This is the <code>Panel</code> constructor:</p> <pre><code>function Panel(element, canClose, closeHandler) { this.element = element; this.canClose = canClose; this.closeHandler = function () { if (closeHandler) closeHandler() }; }</code></pre>
In the following snippet, samp
and kbd
elements are mixed in the contents of a pre
element to
show a session of Zork I.
<pre><samp>You are in an open field west of a big white house with a boarded front door. There is a small mailbox here. ></samp> <kbd>open mailbox</kbd> <samp>Opening the mailbox reveals: A leaflet. ></samp></pre>
The following shows a contemporary poem that uses the
pre
element to preserve its unusual formatting, which
forms an intrinsic part of the poem itself.
<pre> maxling it is with a heart heavy that i admit loss of a feline so loved a friend lost to the unknown (night) ~cdr 11dec07</pre>
blockquote
elementStatus: Last call for comments
formatBlock
candidate.cite
interface HTMLQuoteElement : HTMLElement { attribute DOMString cite; };
The HTMLQuoteElement
interface is
also used by the q
element.
The blockquote
element represents a
section that is quoted from another source.
Content inside a blockquote
must be quoted from
another source, whose address, if it has one, should be cited in the
cite
attribute.
If the cite
attribute
is present, it must be a valid URL. To obtain the corresponding citation link, the value of
the attribute must be resolved
relative to the element. User agents should allow users to follow
such citation links.
The cite
IDL
attribute must reflect the element's cite
content attribute.
This next example shows the use of cite
alongside
blockquote
:
<p>His next piece was the aptly named <cite>Sonnet 130</cite>:</p> <blockquote cite="http://quotes.example.org/s/sonnet130.html"> <p>My mistress' eyes are nothing like the sun,<br> Coral is far more red, than her lips red,<br> ...
This example shows how a forum post could use
blockquote
to show what post a user is replying
to. The article
element is used for each post, to mark
up the threading.
<article> <h1><a href="http://bacon.example.com/?blog=109431">Bacon on a crowbar</a></h1> <article> <header><strong>t3yw</strong> 12 points 1 hour ago</header> <p>I bet a narwhal would love that.</p> <footer><a href="?pid=29578">permalink</a></footer> <article> <header><strong>greg</strong> 8 points 1 hour ago</header> <blockquote><p>I bet a narwhal would love that.</p></blockquote> <p>Dude narwhals don't eat bacon.</p> <footer><a href="?pid=29579">permalink</a></footer> <article> <header><strong>t3yw</strong> 15 points 1 hour ago</header> <blockquote> <blockquote><p>I bet a narwhal would love that.</p></blockquote> <p>Dude narwhals don't eat bacon.</p> </blockquote> <p>Next thing you'll be saying they don't get capes and wizard hats either!</p> <footer><a href="?pid=29580">permalink</a></footer> <article> <article> <header><strong>boing</strong> -5 points 1 hour ago</header> <p>narwhals are worse than ceiling cat</p> <footer><a href="?pid=29581">permalink</a></footer> </article> </article> </article> </article> <article> <header><strong>fred</strong> 1 points 23 minutes ago</header> <blockquote><p>I bet a narwhal would love that.</p></blockquote> <p>I bet they'd love to peel a banana too.</p> <footer><a href="?pid=29582">permalink</a></footer> </article> </article> </article>
Examples of how to
represent a conversation are shown in a later section; it is not
appropriate to use the cite
and blockquote
elements for this purpose.
ol
elementStatus: Last call for comments
li
elements.reversed
start
interface HTMLOListElement : HTMLElement { attribute boolean reversed; attribute long start; };
The ol
element represents a list of
items, where the items have been intentionally ordered, such that
changing the order would change the meaning of the document.
The items of the list are the li
element child nodes
of the ol
element, in tree order.
The reversed
attribute is a boolean attribute. If present, it
indicates that the list is a descending list (..., 3, 2, 1). If the
attribute is omitted, the list is an ascending list (1, 2, 3,
...).
The start
attribute, if present, must be a valid integer giving
the ordinal value of the first list item.
If the start
attribute is
present, user agents must parse it as an integer, in order to determine the
attribute's value. The default value, used if the attribute is
missing or if the value cannot be converted to a number according to
the referenced algorithm, is 1 if the element has no reversed
attribute, and is the
number of child li
elements otherwise.
The first item in the list has the ordinal value given by the
ol
element's start
attribute, unless that li
element has a value
attribute with a value that can
be successfully parsed, in which case it has the ordinal value given
by that value
attribute.
Each subsequent item in the list has the ordinal value given by
its value
attribute, if it has
one, or, if it doesn't, the ordinal value of the previous item, plus
one if the reversed
is absent,
or minus one if it is present.
The reversed
IDL
attribute must reflect the value of the reversed
content attribute.
The start
IDL
attribute must reflect the value of the start
content attribute.
The following markup shows a list where the order matters, and
where the ol
element is therefore appropriate. Compare
this list to the equivalent list in the ul
section to
see an example of the same items using the ul
element.
<p>I have lived in the following countries (given in the order of when I first lived there):</p> <ol> <li>Switzerland <li>United Kingdom <li>United States <li>Norway </ol>
Note how changing the order of the list changes the meaning of the document. In the following example, changing the relative order of the first two items has changed the birthplace of the author:
<p>I have lived in the following countries (given in the order of when I first lived there):</p> <ol> <li>United Kingdom <li>Switzerland <li>United States <li>Norway </ol>
ul
elementStatus: Last call for comments
li
elements.interface HTMLUListElement : HTMLElement {};
The ul
element represents a list of
items, where the order of the items is not important — that
is, where changing the order would not materially change the meaning
of the document.
The items of the list are the li
element child nodes
of the ul
element.
The following markup shows a list where the order does not
matter, and where the ul
element is therefore
appropriate. Compare this list to the equivalent list in the
ol
section to see an example of the same items using
the ol
element.
<p>I have lived in the following countries:</p> <ul> <li>Norway <li>Switzerland <li>United Kingdom <li>United States </ul>
Note that changing the order of the list does not change the meaning of the document. The items in the snippet above are given in alphabetical order, but in the snippet below they are given in order of the size of their current account balance in 2007, without changing the meaning of the document whatsoever:
<p>I have lived in the following countries:</p> <ul> <li>Switzerland <li>Norway <li>United Kingdom <li>United States </ul>
li
elementStatus: Last call for comments
ol
elements.ul
elements.menu
elements.ol
element: value
interface HTMLLIElement : HTMLElement { attribute long value; };
The li
element represents a list
item. If its parent element is an ol
, ul
,
or menu
element, then the element is an item of the
parent element's list, as defined for those elements. Otherwise, the
list item has no defined list-related relationship to any other
li
element.
The value
attribute, if present, must be a valid integer giving
the ordinal value of the list item.
If the value
attribute is
present, user agents must parse it as an integer, in order to determine the
attribute's value. If the attribute's value cannot be converted to a
number, the attribute must be treated as if it was absent. The
attribute has no default value.
The value
attribute is
processed relative to the element's parent ol
element
(q.v.), if there is one. If there is not, the attribute has no
effect.
The value
IDL
attribute must reflect the value of the value
content attribute.
The following example, the top ten movies are listed (in reverse
order). Note the way the list is given a title by using a
figure
element and its figcaption
element.
<figure> <figcaption>The top 10 movies of all time</figcaption> <ol> <li value="10"><cite>Josie and the Pussycats</cite>, 2001</li> <li value="9"><cite lang="sh">Црна мачка, бели мачор</cite>, 1998</li> <li value="8"><cite>A Bug's Life</cite>, 1998</li> <li value="7"><cite>Toy Story</cite>, 1995</li> <li value="6"><cite>Monsters, Inc</cite>, 2001</li> <li value="5"><cite>Cars</cite>, 2006</li> <li value="4"><cite>Toy Story 2</cite>, 1999</li> <li value="3"><cite>Finding Nemo</cite>, 2003</li> <li value="2"><cite>The Incredibles</cite>, 2004</li> <li value="1"><cite>Ratatouille</cite>, 2007</li> </ol> </figure>
The markup could also be written as follows, using the reversed
attribute on the
ol
element:
<figure> <figcaption>The top 10 movies of all time</figcaption> <ol reversed> <li><cite>Josie and the Pussycats</cite>, 2001</li> <li><cite lang="sh">Црна мачка, бели мачор</cite>, 1998</li> <li><cite>A Bug's Life</cite>, 1998</li> <li><cite>Toy Story</cite>, 1995</li> <li><cite>Monsters, Inc</cite>, 2001</li> <li><cite>Cars</cite>, 2006</li> <li><cite>Toy Story 2</cite>, 1999</li> <li><cite>Finding Nemo</cite>, 2003</li> <li><cite>The Incredibles</cite>, 2004</li> <li><cite>Ratatouille</cite>, 2007</li> </ol> </figure>
If the li
element is the child of a
menu
element and itself has a child that defines a
command, then the
li
element will match the :enabled
and :disabled
pseudo-classes in the
same way as the first such child element does.
dl
elementStatus: Last call for comments
dt
elements followed by one or more dd
elements.interface HTMLDListElement : HTMLElement {};
The dl
element represents an
association list consisting of zero or more name-value groups (a
description list). Each group must consist of one or more names
(dt
elements) followed by one or more values
(dd
elements). Within a single dl
element,
there should not be more than one dt
element for each
name.
Name-value groups may be terms and definitions, metadata topics and values, or any other groups of name-value data.
The values within a group are alternatives; multiple paragraphs
forming part of the same value must all be given within the same
dd
element.
The order of the list of groups, and of the names and values within each group, may be significant.
If a dl
element is empty, it contains no groups.
If a dl
element contains non-whitespace text nodes, or elements other than dt
and
dd
, then those elements or text
nodes do not form part of any groups in that
dl
.
If a dl
element contains only dt
elements, then it consists of one group with names but no
values.
If a dl
element contains only dd
elements, then it consists of one group with values but no
names.
If a dl
element starts with one or more
dd
elements, then the first group has no associated
name.
If a dl
element ends with one or more
dt
elements, then the last group has no associated
value.
When a dl
element doesn't match its
content model, it is often due to accidentally using dd
elements in the place of dt
elements and vice
versa. Conformance checkers can spot such mistakes and might be able
to advise authors how to correctly use the markup.
In the following example, one entry ("Authors") is linked to two values ("John" and "Luke").
<dl> <dt> Authors <dd> John <dd> Luke <dt> Editor <dd> Frank </dl>
In the following example, one definition is linked to two terms.
<dl> <dt lang="en-US"> <dfn>color</dfn> </dt> <dt lang="en-GB"> <dfn>colour</dfn> </dt> <dd> A sensation which (in humans) derives from the ability of the fine structure of the eye to distinguish three differently filtered analyses of a view. </dd> </dl>
The following example illustrates the use of the dl
element to mark up metadata of sorts. At the end of the example,
one group has two metadata labels ("Authors" and "Editors") and two
values ("Robert Rothman" and "Daniel Jackson").
<dl> <dt> Last modified time </dt> <dd> 2004-12-23T23:33Z </dd> <dt> Recommended update interval </dt> <dd> 60s </dd> <dt> Authors </dt> <dt> Editors </dt> <dd> Robert Rothman </dd> <dd> Daniel Jackson </dd> </dl>
The following example shows the dl
element used to
give a set of instructions. The order of the instructions here is
important (in the other examples, the order of the blocks was not
important).
<p>Determine the victory points as follows (use the first matching case):</p> <dl> <dt> If you have exactly five gold coins </dt> <dd> You get five victory points </dd> <dt> If you have one or more gold coins, and you have one or more silver coins </dt> <dd> You get two victory points </dd> <dt> If you have one or more silver coins </dt> <dd> You get one victory point </dd> <dt> Otherwise </dt> <dd> You get no victory points </dd> </dl>
The following snippet shows a dl
element being used
as a glossary. Note the use of dfn
to indicate the
word being defined.
<dl> <dt><dfn>Apartment</dfn>, n.</dt> <dd>An execution context grouping one or more threads with one or more COM objects.</dd> <dt><dfn>Flat</dfn>, n.</dt> <dd>A deflated tire.</dd> <dt><dfn>Home</dfn>, n.</dt> <dd>The user's login directory.</dd> </dl>
The dl
element is inappropriate for
marking up dialogue. Examples of how to
mark up dialogue are shown below.
dt
elementStatus: Last call for comments
dd
or dt
elements inside dl
elements.HTMLElement
.The dt
element represents the term, or
name, part of a term-description group in a description list
(dl
element).
The dt
element itself, when used in a
dl
element, does not indicate that its contents are a
term being defined, but this can be indicated using the
dfn
element.
dd
elementStatus: Last call for comments
dt
or dd
elements inside dl
elements.HTMLElement
.The dd
element represents the
description, definition, or value, part of a term-description group
in a description list (dl
element).
A dl
can be used to define a vocabulary list, like
in a dictionary. In the following example, each entry, given by a
dt
with a dfn
, has several
dd
s, showing the various parts of the definition.
<dl> <dt><dfn>happiness</dfn></dt> <dd class="pronunciation">/'hæ p. nes/</dd> <dd class="part-of-speech"><i><abbr>n.</abbr></i></dd> <dd>The state of being happy.</dd> <dd>Good fortune; success. <q>Oh <b>happiness</b>! It worked!</q></dd> <dt><dfn>rejoice</dfn></dt> <dd class="pronunciation">/ri jois'/</dd> <dd><i class="part-of-speech"><abbr>v.intr.</abbr></i> To be delighted oneself.</dd> <dd><i class="part-of-speech"><abbr>v.tr.</abbr></i> To cause one to be delighted.</dd> </dl>
figure
elementStatus: Last call for comments. ISSUE-90 (figure) blocks progress to Last Call
figcaption
element followed by flow content.figcaption
element.HTMLElement
.The figure
element represents some
flow content, optionally with a caption, that is
self-contained and is typically referenced as a single unit from the
main flow of the document.
The element can thus be used to annotate illustrations, diagrams, photos, code listings, etc, that are referred to from the main content of the document, but that could, without affecting the flow of the document, be moved away from that primary content, e.g. to the side of the page, to dedicated pages, or to an appendix.
The first figcaption
element child of the element, if any, represents the caption of the
figure
element's contents. If there is no child
figcaption
element, then there is no caption.
This example shows the figure
element to mark up a
code listing.
<p>In <a href="#l4">listing 4</a> we see the primary core interface API declaration.</p> <figure id="l4"> <figcaption>Listing 4. The primary core interface API declaration.</figcaption> <pre><code>interface PrimaryCore { boolean verifyDataLine(); void sendData(in sequence<byte> data); void initSelfDestruct(); }</code></pre> </figure> <p>The API is designed to use UTF-8.</p>
Here we see a figure
element to mark up a
photo.
<figure> <img src="bubbles-work.jpeg" alt="Bubbles, sitting in his office chair, works on his latest project intently."> <figcaption>Bubbles at work</figcaption> </figure>
In this example, we see an image that is not a figure, as well as an image and a video that are.
<h2>Malinko's comics</h2> <p>This case centered on some sort of "intellectual property" infringement related to a comic (see Exhibit A). The suit started after a trailer ending with these words: <blockquote> <img src="promblem-packed-action.png" alt="ROUGH COPY! Promblem-Packed Action!"> </blockquote> <p>...was aired. A lawyer, armed with a Bigger Notebook, launched a preemptive strike using snowballs. A complete copy of the trailer is included with Exhibit B. <figure> <img src="ex-a.png" alt="Two squiggles on a dirty piece of paper."> <figcaption>Exhibit A. The alleged <cite>rough copy</cite> comic.</figcaption> </figure> <figure> <video src="ex-b.mov"></video> <figcaption>Exhibit B. The <cite>Rough Copy</cite> trailer.</figcaption> </figure> <p>The case was resolved out of court.
Here, a part of a poem is marked up using
figure
.
<figure> <p>'Twas brillig, and the slithy toves<br> Did gyre and gimble in the wabe;<br> All mimsy were the borogoves,<br> And the mome raths outgrabe.</p> <figcaption><cite>Jabberwocky</cite> (first verse). Lewis Carroll, 1832-98</figcaption> </figure>
In this example, which could be part of a much larger work discussing a castle, the figure has three images in it.
<figure> <img src="castle1423.jpeg" title="Etching. Anonymous, ca. 1423." alt="The castle has one tower, and a tall wall around it."> <img src="castle1858.jpeg" title="Oil-based paint on canvas. Maria Towle, 1858." alt="The castle now has two towers and two walls."> <img src="castle1999.jpeg" title="Film photograph. Peter Jankle, 1999." alt="The castle lies in ruins, the original tower all that remains in one piece."> <figcaption>The castle through the ages: 1423, 1858, and 1999 respectively.</figcaption> </figure>
figcaption
elementfigure
element.HTMLElement
.The figcaption
element represents a
caption or legend for the rest of the contents of the
figcaption
element's parent figure
element, if any.
div
elementStatus: Last call for comments
formatBlock
candidate.interface HTMLDivElement : HTMLElement {};
The div
element has no special meaning at all. It
represents its children. It can be used with the class
, lang
, and title
attributes to mark up semantics
common to a group of consecutive elements.
Authors are strongly encouraged to view the
div
element as an element of last resort, for when no
other element is suitable. Use of the div
element
instead of more appropriate elements leads to poor accessibility for
readers and poor maintainability for authors.
For example, a blog post would be marked up using
article
, a chapter using section
, a
page's navigation aids using nav
, and a group of form
controls using fieldset
.
On the other hand, div
elements can be useful for
stylistic purposes or to wrap multiple paragraphs within a section
that are all to be annotated in a similar way. In the following
example, we see div
elements used as a way to set the
language of two paragraphs at once, instead of setting the language
on the two paragraph elements separately:
<article lang="en-US"> <h1>My use of language and my cats</h1> <p>My cat's behavior hasn't changed much since her absence, except that she plays her new physique to the neighbors regularly, in an attempt to get pets.</p> <div lang="en-GB"> <p>My other cat, coloured black and white, is a sweetie. He followed us to the pool today, walking down the pavement with us. Yesterday he apparently visited our neighbours. I wonder if he recognises that their flat is a mirror image of ours.</p> <p>Hm, I just noticed that in the last paragraph I used British English. But I'm supposed to write in American English. So I shouldn't say "pavement" or "flat" or "colour"...</p> </div> <p>I should say "sidewalk" and "apartment" and "color"!</p> </article>