Links are a conceptual construct, created by a
,
area
, and link
elements, that represent a connection between two
resources, one of which is the current Document
. There
are two kinds of links in HTML:
These are links to resources that are to be used to augment the current document, generally automatically processed by the user agent.
These are links to other resources that are generally exposed to the user by the user agent so that the user can cause the user agent to navigate to those resources, e.g. to visit them in a browser or download them.
For link
elements with an href
attribute and a rel
attribute, links must be created
for the keywords of the rel
attribute, as defined for those keywords in the link types section.
Similarly, for a
and area
elements with
an href
attribute and a
rel
attribute, links must be
created for the keywords of the rel
attribute as defined for those
keywords in the link types section. Unlike
link
elements, however, a
and
area
element with an href
attribute that either do not
have a rel
attribute, or
whose rel
attribute has no
keywords that are defined as specifying hyperlinks, must also create a
hyperlink. This implied hyperlink has no special
meaning (it has no link type) beyond
linking the element's document to the resource given by the
element's href
attribute.
A hyperlink can have one or more hyperlink annotations that modify the processing semantics of that hyperlink.
a
and area
elementsThe href
attribute on a
and area
elements must have
a value that is a valid URL potentially surrounded by
spaces.
The href
attribute on a
and area
elements is not
required; when those elements do not have href
attributes they do not
create hyperlinks.
The target
attribute, if present, must be a valid browsing context name
or keyword. It gives the name of the browsing
context that will be used. User agents use
this name when following hyperlinks.
When an a
or area
element's
activation behavior is invoked, the user agent may
allow the user to indicate a preference regarding whether the
hyperlink is to be used for navigation
or whether the resource it specifies is to be downloaded.
In the absence of a user preference, the default should be
navigation if the element has no download
attribute, and
should be to download the specified resource if it does.
Whether determined by the user's preferences or via the presence or absence of the attribute, if the decision is to use the hyperlink for navigation then the user agent must follow the hyperlink, and if the decision is to use the hyperlink to download a resource, the user agent must download the hyperlink. These terms are defined in subsequent sections below.
The download
attribute, if present, indicates that the author intends the
hyperlink to be used for downloading a resource. The attribute may
have a value; the value, if any, specifies the default filename that
the author recommends for use in labeling the resource in a local
file system. There are no restrictions on allowed values, but
authors are cautioned that most file systems have limitations with
regard to what punctuation is supported in file names, and user
agents are likely to adjust file names accordingly.
The ping
attribute, if
present, gives the URLs of the resources that are interested in
being notified if the user follows the hyperlink. The value must be
a set of space-separated tokens, each of which must be
a valid non-empty URL. The value is
used by the user agent for hyperlink
auditing.
The rel
attribute on a
and area
elements controls
what kinds of links the elements create. The attribue's value must
be a set of space-separated tokens. The allowed keywords and their meanings are
defined below.
The rel
attribute has
no default value. If the attribute is omitted or if none of the
values in the attribute are recognized by the user agent, then the
document has no particular relationship with the destination
resource other than there being a hyperlink between the two.
The media
attribute describes for which media the target document was
designed. It is purely advisory. The value must be a valid
media query. The default, if the media
attribute is omitted, is
"all
".
The hreflang
attribute on a
and area
elements that
create hyperlinks, if present, gives
the language of the linked resource. It is purely advisory. The
value must be a valid BCP 47 language tag. [BCP47] User agents must
not consider this attribute authoritative — upon fetching the
resource, user agents must use only language information associated
with the resource to determine its language, not metadata included
in the link to the resource.
The type
attribute, if present, gives the MIME type of the
linked resource. It is purely advisory. The value must be a
valid MIME type. User agents must
not consider the type
attribute authoritative — upon fetching the resource, user
agents must not use metadata included in the link to the resource to
determine its type.
When a user follows a
hyperlink created by an element, the user agent must resolve the URL given by
the href
attribute of that
element, relative to that element, and if that is successful, must
navigate a browsing
context to the resulting absolute URL. In the
case of server-side image maps, that absolute URL must
have its hyperlink suffix appended to it before the
navigation is started.
If resolving the URL fails, the user agent may report the error to the user in a user-agent-specific manner, may navigate to an error page to report the error, or may ignore the error and do nothing.
If the user indicated a specific browsing context when following the hyperlink, or if the user agent is configured to follow hyperlinks by navigating a particular browsing context, then that must be the browsing context that is navigated.
Otherwise, if the element is an a
or
area
element that has a target
attribute, then the
browsing context that is navigated must be chosen by
applying the rules for choosing a browsing context given a
browsing context name, using the value of the target
attribute as the
browsing context name. If these rules result in the creation of a
new browsing context, it must be navigated with
replacement enabled.
Otherwise, if the hyperlink is a sidebar hyperlink and the user agent implements a feature that can be considered a secondary browsing context, such a secondary browsing context may be selected as the browsing context to be navigated.
Otherwise, if the element is an a
or
area
element with no target
attribute, but the
Document
contains a base
element with a
target
attribute, then the
browsing context that is navigated must be chosen by applying
the rules for choosing a browsing context given a browsing
context name, using the value of the target
attribute of the first such
base
element as the browsing context name. If these
rules result in the creation of a new browsing context,
it must be navigated with replacement enabled.
Otherwise, the browsing context that must be navigated is the same browsing context as the one which the element itself is in.
The navigation must be done with the browsing
context that contains the Document
object with
which the element in question is associated as the source
browsing context.
In some cases, resources are intended for later use rather than
immediate viewing. To indicate that a resource is intended to be
downloaded for use later, rather than immediately used, the download
attribute can be
specified on the a
or area
element that
creates the hyperlink to that resource.
The attribute can furthermore be given a value, to specify the
filename that user agents are to use when storing the resource in a
file system. This value can be overridden by the Content-Disposition
HTTP
header's filename parameters. [RFC6266]
In cross-origin situations, the download
attribute has to be
combined with the Content-Disposition
HTTP
header, specifically with the attachment
disposition type, to avoid the user being warned of possibly
nefarious activity. (This is to protect users from being made to
download sensitive personal or confidential information without
their full understanding.)
When a user downloads a hyperlink created by an element, the user agent must run the following steps:
Resolve the
URL given by the href
attribute of that element,
relative to that element.
If resolving the URL fails, the user agent may report the error to the user in a user-agent-specific manner, may navigate to an error page to report the error, or may ignore the error and do nothing. In either case, the user agent must abort these steps.
Otherwise, let URL be the resulting absolute URL.
In the case of server-side image maps, append the hyperlink suffix to URL.
Return to whatever algorithm invoked these steps and continue these steps asynchronously.
Fetch URL and handle the resulting resource as a download.
When a user agent is to handle a resource obtained from a fetch algorithm as a download, it should provide the user with a way to save the resource for later use, if a resource is successfully obtained; or otherwise should report any problems downloading the file to the user.
If the user agent needs a file name for a resource being handled as a download, it should select one using the following algorithm.
This algorithm is intended to mitigate security dangers involved in downloading files from untrusted sites, and user agents are strongly recommended to follow it.
Let filename be the void value.
If the resource has a Content-Disposition
header,
that header specifies the attachment
disposition type, and the header includes filename information,
then let filename have the value specified by
the header, and jump to the step labeled "sanitize" below. [RFC6266]
Let resource origin be the origin of the resource being downloaded.
Let interface origin be the
origin of the Document
in which the download or
navigate action resulting in the download was
initiated, if any.
If there is no interface origin, then let trusted operation be true. Otherwise, let trusted operation be true if resource origin is the same origin as interface origin, and false otherwise.
If trusted operation is true and the
resource has a Content-Disposition
header
and that header includes filename information, then let filename have the value specified by the header, and
jump to the step labeled "sanitize" below. [RFC6266]
If the download was not initiated from a
hyperlink created by an a
or
area
element, or if the element of the
hyperlink from which it was initiated did not have a
download
attribute
when the download was initiated, or if there was such an attribute
but its value when the download was initiated was the empty string,
then jump to the step labeled no proposed filename.
Let proposed filename have the value of
the download
attribute
of the element of the hyperlink that initiated the
download at the time the download was initiated.
If trusted operation is true, let filename have the value of proposed filename, and jump to the step labeled "sanitize" below.
If the resource has a Content-Disposition
header
and that header specifies the attachment
disposition type, let filename have the value
of proposed filename, and jump to the step
labeled "sanitize" below. [RFC6266]
No proposed filename: If trusted operation is true, or if the user indicated a preference for having the resource in question downloaded, let filename have a value derived from the URL of the resource in a user-agent-defined manner, and jump to the step labeled "sanitize" below.
Act in a user-agent-defined manner to safeguard the user from a potentially hostile cross-origin download. If the download is not to be aborted, then let filename be set to the user's preferred file name or to a file name selected by the user agent, and jump to the step labeled "sanitize" below.
If the algorithm reaches this step, then a download was begun
from a different origin than the resource being downloaded, and
the origin did not mark the file as suitable for downloading, and
the download was not initiated by the user. This could be because
a download
attribute
was used to trigger the download, or because the resource in
question is not of a type that the user agent supports.
This could be dangerous, because, for instance, a hostile server could be trying to get a user to unknowingly download private information and then re-upload it to the hostile server, by tricking the user into thinking the data is from the hostile server.
Thus, it is in the user's interests that the user be somehow notified that the resource in question comes from quite a different source, and to prevent confusion, any suggested filename from the potentially hostile interface origin should be ignored.
Sanitize: Optionally, allow the user to influence filename. For example, a user agent could prompt the user for a file name, potentially providing the value of filename as determined above as a default value.
Adjust filename to be suitable for the local file system.
For example, this could involve removing characters that are not legal in file names, or trimming leading and trailing whitespace.
If the platform conventions do not in any way use extensions to determine the types of file on the file system, then return filename as the file name and abort these steps.
Let claimed type be the type given by the resource's Content-Type metadata, if any is known. Let named type be the type given by filename's extension, if any is known. For the purposes of this step, a type is a mapping of a MIME type to an extension.
If named type is consistent with the user's preferences (e.g. because the value of filename was determined by prompting the user), then return filename as the file name and abort these steps.
If claimed type and named type are the same type (i.e. the type given by the resource's Content-Type metadata is consistent with the type given by filename's extension), then return filename as the file name and abort these steps.
If the claimed type is known, then alter filename to add an extension corresponding to claimed type.
Otherwise, if named type is known to be
potentially dangerous (e.g. it will be treated by the platform
conventions as a native executable, shell script, HTML
application, or executable-macro-capable document) then optionally
alter filename to add a known-safe extension (e.g. ".txt
").
This last step would make it impossible to download executables, which might not be desireable. As always, implementors are forced to balance security and usability in this matter.
Return filename as the file name.
For the purposes of this algorithm, a file extension consists of any part of
the file name that platform conventions dictate will be used for
identifying the type of the file. For example, many operating
systems use the part of the file name following the last dot (".
") in the file name to determine the type of the
file, and from that the manner in which the file is to be opened or
executed.
User agents should ignore any directory or path information
provided by the resource itself, its URL, and any download
attribute, in
deciding where to store the resulting file in the user's file
system.
If a hyperlink created by an a
or
area
element has a ping
attribute, and the user
follows the hyperlink, and the value of the element's href
attribute can be resolved, relative to the element,
without failure, then the user agent must take the ping
attribute's value, split that string on spaces,
resolve each resulting token
relative to the element, and then should send a request (as
described below) to each of the resulting absolute URLs. (Tokens that fail to resolve are
ignored.) This may be done in parallel with the primary request, and
is independent of the result of that request.
User agents should allow the user to adjust this behavior, for
example in conjunction with a setting that disables the sending of
HTTP Referer
(sic) headers. Based
on the user's preferences, UAs may either ignore the
ping
attribute altogether,
or selectively ignore URLs in the list (e.g. ignoring any
third-party URLs).
For URLs that are HTTP URLs, the requests must be performed by
fetching the specified URLs using the
POST method, with an entity body with the MIME type
text/ping
consisting of the four-character string
"PING
", from the origin of the
Document
containing the hyperlink. All relevant cookie and HTTP
authentication headers must be included in the request. Which other
headers are required depends on the URLs involved.
Document
object containing the hyperlink being
audited and the ping URL have the same originPing-From
HTTP header with, as its
value, the address of
the document containing the hyperlink, and a Ping-To
HTTP header with, as its value,
the address of the absolute URL of the target of the
hyperlink. The request must not include a Referer
(sic) HTTP header. Referer
(sic) HTTP header with, as its
value, the address of
the document containing the hyperlink, a Ping-From
HTTP header with the same
value, and a Ping-To
HTTP header
with, as its value, the address of the target of the
hyperlink.Ping-To
HTTP header with, as its value,
the address of the target of the hyperlink. The request must
neither include a Referer
(sic)
HTTP header nor include a Ping-From
HTTP header.To save bandwidth, implementors might also wish to
consider omitting optional headers such as Accept
from
these requests.
User agents must, unless otherwise specified by the user, honor the HTTP headers (including, in particular, redirects and HTTP cookie headers), but must ignore any entity bodies returned in the responses. User agents may close the connection prematurely once they start receiving an entity body. [COOKIES]
For URLs that are not HTTP URLs, the requests must be performed by fetching the specified URL normally, and discarding the results.
When the ping
attribute is
present, user agents should clearly indicate to the user that
following the hyperlink will also cause secondary requests to be
sent in the background, possibly including listing the actual target
URLs.
For example, a visual user agent could include the hostnames of the target ping URLs along with the hyperlink's actual URL in a status bar or tooltip.
The ping
attribute is redundant
with pre-existing technologies like HTTP redirects and JavaScript
in allowing Web pages to track which off-site links are most
popular or allowing advertisers to track click-through rates.
However, the ping
attribute
provides these advantages to the user over those alternatives:
Thus, while it is possible to track users without this feature,
authors are encouraged to use the ping
attribute so that the user
agent can make the user experience more transparent.
The following table summarizes the link types that are defined by this specification. This table is non-normative; the actual definitions for the link types are given in the next few sections.
In this section, the term referenced document refers to the resource identified by the element representing the link, and the term current document refers to the resource within which the element representing the link finds itself.
To determine which link types apply to a link
,
a
, or area
element, the element's rel
attribute must be split on spaces. The resulting tokens are the link
types that apply to that element.
Except where otherwise specified, a keyword must not be specified
more than once per rel
attribute.
Link types are always ASCII case-insensitive, and must be compared as such.
Thus, rel="next"
is the
same as rel="NEXT"
.
Link type | Effect on... | Brief description | |
---|---|---|---|
link |
a and area |
||
alternate |
Hyperlink | Hyperlink | Gives alternate representations of the current document. |
author |
Hyperlink | Hyperlink | Gives a link to the current document's author. |
bookmark |
not allowed | Hyperlink | Gives the permalink for the nearest ancestor section. |
help |
Hyperlink | Hyperlink | Provides a link to context-sensitive help. |
icon |
External Resource | not allowed | Imports an icon to represent the current document. |
license |
Hyperlink | Hyperlink | Indicates that the main content of the current document is covered by the copyright license described by the referenced document. |
next |
Hyperlink | Hyperlink | Indicates that the current document is a part of a series, and that the next document in the series is the referenced document. |
nofollow |
not allowed | Annotation | Indicates that the current document's original author or publisher does not endorse the referenced document. |
noreferrer |
not allowed | Annotation | Requires that the user agent not send an HTTP Referer (sic) header if the user follows the hyperlink. |
prefetch |
External Resource | External Resource | Specifies that the target resource should be preemptively cached. |
prev |
Hyperlink | Hyperlink | Indicates that the current document is a part of a series, and that the previous document in the series is the referenced document. |
search |
Hyperlink | Hyperlink | Gives a link to a resource that can be used to search through the current document and its related pages. |
stylesheet |
External Resource | not allowed | Imports a stylesheet. |
tag |
not allowed | Hyperlink | Gives a tag (identified by the given address) that applies to the current document. |
Some of the types described below list synonyms for these values. These are to be handled as specified by user agents, but must not be used in documents.
alternate
"The alternate
keyword may be
used with link
, a
, and area
elements.
The meaning of this keyword depends on the values of the other attributes.
link
element and the rel
attribute also contains the
keyword stylesheet
The alternate
keyword
modifies the meaning of the stylesheet
keyword in the way
described for that keyword. The alternate
keyword does not create a
link of its own.
alternate
keyword is
used with the type
attribute set to the value application/rss+xml
or the value application/atom+xml
The keyword creates a hyperlink referencing a syndication feed (though not necessarily syndicating exactly the same content as the current page).
The first link
, a
, or area
element in the document (in tree order) with the alternate
keyword used with the type
attribute set to the value
application/rss+xml
or the value application/atom+xml
must be treated as the default
syndication feed for the purposes of feed autodiscovery.
The following link
element gives the syndication
feed for the current page:
<link rel="alternate" type="application/atom+xml" href="data.xml">
The following extract offers various different syndication feeds:
<p>You can access the planets database using Atom feeds:</p> <ul> <li><a href="recently-visited-planets.xml" rel="alternate" type="application/atom+xml">Recently Visited Planets</a></li> <li><a href="known-bad-planets.xml" rel="alternate" type="application/atom+xml">Known Bad Planets</a></li> <li><a href="unexplored-planets.xml" rel="alternate" type="application/atom+xml">Unexplored Planets</a></li> </ul>
The keyword creates a hyperlink referencing an alternate representation of the current document.
The nature of the referenced document is given by the media
, hreflang
, and type
attributes.
If the alternate
keyword is
used with the media
attribute, it indicates that the referenced document is intended for
use with the media specified.
If the alternate
keyword is
used with the hreflang
attribute, and that attribute's value differs from the root
element's language, it indicates that the
referenced document is a translation.
If the alternate
keyword is
used with the type
attribute, it indicates that the referenced document is a
reformulation of the current document in the specified format.
The media
, hreflang
, and type
attributes can be combined
when specified with the alternate
keyword.
For example, the following link is a French translation that uses the PDF format:
<link rel=alternate type=application/pdf hreflang=fr href=manual-fr>
This relationship is transitive — that is, if a document
links to two other documents with the link type "alternate
", then, in addition to
implying that those documents are alternative representations of
the first document, it is also implying that those two documents
are alternative representations of each other.
author
"The author
keyword may be
used with link
, a
, and area
elements. This keyword creates a hyperlink.
For a
and area
elements, the author
keyword indicates that the
referenced document provides further information about the author of
the nearest article
element ancestor of the element
defining the hyperlink, if there is one, or of the page as a whole,
otherwise.
For link
elements, the author
keyword indicates that the
referenced document provides further information about the author
for the page as a whole.
The "referenced document" can be, and often is, a
mailto:
URL giving the e-mail address of the
author. [MAILTO]
Synonyms: For historical reasons, user agents
must also treat link
, a
, and
area
elements that have a rev
attribute with the value "made
" as having the author
keyword specified as a link
relationship.
bookmark
"The bookmark
keyword may be
used with a
and area
elements. This
keyword creates a hyperlink.
The bookmark
keyword gives a
permalink for the nearest ancestor article
element of
the linking element in question, or of the section the linking element is most
closely associated with, if there are no ancestor
article
elements.
The following snippet has three permalinks. A user agent could determine which permalink applies to which part of the spec by looking at where the permalinks are given.
... <body> <h1>Example of permalinks</h1> <div id="a"> <h2>First example</h2> <p><a href="a.html" rel="bookmark">This</a> permalink applies to only the content from the first H2 to the second H2. The DIV isn't exactly that section, but it roughly corresponds to it.</p> </div> <h2>Second example</h2> <article id="b"> <p><a href="b.html" rel="bookmark">This</a> permalink applies to the outer ARTICLE element (which could be, e.g., a blog post).</p> <article id="c"> <p><a href="c.html" rel="bookmark">This</a> permalink applies to the inner ARTICLE element (which could be, e.g., a blog comment).</p> </article> </article> </body> ...
help
"The help
keyword may be used with
link
, a
, and area
elements. This keyword creates a hyperlink.
For a
and area
elements, the help
keyword indicates that the referenced
document provides further help information for the parent of the
element defining the hyperlink, and its children.
In the following example, the form control has associated context-sensitive help. The user agent could use this information, for example, displaying the referenced document if the user presses the "Help" or "F1" key.
<p><label> Topic: <input name=topic> <a href="help/topic.html" rel="help">(Help)</a></label></p>
For link
elements, the help
keyword indicates that the referenced
document provides help for the page as a whole.
For a
and area
elements, on some
browsers, the help
keyword causes the
link to use a different cursor.
icon
"The icon
keyword may be used with
link
elements. This keyword creates an external resource link.
The specified resource is an icon representing the page or site, and should be used by the user agent when representing the page in the user interface.
Icons could be auditory icons, visual icons, or other kinds of
icons. If multiple icons are provided, the user
agent must select the most appropriate icon according to the type
, media
, and sizes
attributes. If there are
multiple equally appropriate icons, user agents must use the last
one declared in tree order at the time that the user
agent collected the list of icons. If the user agent tries to use an
icon but that icon is determined, upon closer examination, to in
fact be inappropriate (e.g. because it uses an unsupported format),
then the user agent must try the next-most-appropriate icon as
determined by the attributes.
User agents are not required to update icons when the list of icons changes, but are encouraged to do so.
There is no default type for resources given by the icon
keyword. However, for the purposes of
determining the type of the
resource, user agents must expect the resource to be an image.
The sizes
attribute gives the sizes of icons for visual media. Its value, if
present, is merely advisory. User agents may use the value to decide
which icon(s) to use if multiple icons are available.
If specified, the attribute must have a value that is an
unordered set of unique space-separated tokens which
are ASCII case-insensitive. Each value must be either
an ASCII case-insensitive match for the string "any
", or a value that consists of
two valid non-negative
integers that do not have a leading U+0030 DIGIT ZERO (0)
character and that are separated by a single U+0078 LATIN SMALL
LETTER X or U+0058 LATIN CAPITAL LETTER X character.
The keywords represent icon sizes.
To parse and process the attribute's value, the user agent must first split the attribute's value on spaces, and must then parse each resulting keyword to determine what it represents.
The any
keyword
represents that the resource contains a scalable icon, e.g. as
provided by an SVG image.
Other keywords must be further parsed as follows to determine what they represent:
If the keyword doesn't contain exactly one U+0078 LATIN SMALL LETTER X or U+0058 LATIN CAPITAL LETTER X character, then this keyword doesn't represent anything. Abort these steps for that keyword.
Let width string be the string before
the "x
" or "X
".
Let height string be the string after
the "x
" or "X
".
If either width string or height string start with a U+0030 DIGIT ZERO (0) character or contain any characters other than characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9), then this keyword doesn't represent anything. Abort these steps for that keyword.
Apply the rules for parsing non-negative integers to width string to obtain width.
Apply the rules for parsing non-negative integers to height string to obtain height.
The keyword represents that the resource contains a bitmap icon with a width of width device pixels and a height of height device pixels.
The keywords specified on the sizes
attribute must not represent
icon sizes that are not actually available in the linked
resource.
In the absence of a link
with the icon
keyword, for Document
s
obtained over HTTP or HTTPS, user agents may instead attempt to
fetch and use an icon with the absolute
URL obtained by resolving the URL "/favicon.ico
" against the document's
address, as if the page had declared that icon using the
icon
keyword.
The following snippet shows the top part of an application with several icons.
<!DOCTYPE HTML> <html> <head> <title>lsForums — Inbox</title> <link rel=icon href=favicon.png sizes="16x16" type="image/png"> <link rel=icon href=windows.ico sizes="32x32 48x48" type="image/vnd.microsoft.icon"> <link rel=icon href=mac.icns sizes="128x128 512x512 8192x8192 32768x32768"> <link rel=icon href=iphone.png sizes="57x57" type="image/png"> <link rel=icon href=gnome.svg sizes="any" type="image/svg+xml"> <link rel=stylesheet href=lsforums.css> <script src=lsforums.js></script> <meta name=application-name content="lsForums"> </head> <body> ...
For historical reasons, the icon
keyword may be preceded by the keyword "shortcut
". If the "shortcut
"
keyword is present, it must be come immediately before the icon
keyword and the two keywords must be
separated by only a single U+0020 SPACE character.
license
"The license
keyword may be used
with link
, a
, and area
elements. This keyword creates a hyperlink.
The license
keyword indicates
that the referenced document provides the copyright license terms
under which the main content of the current document is
provided.
This specification does not specify how to distinguish between the main content of a document and content that is not deemed to be part of that main content. The distinction should be made clear to the user.
Consider a photo sharing site. A page on that site might describe and show a photograph, and the page might be marked up as follows:
<!DOCTYPE HTML> <html> <head> <title>Exampl Pictures: Kissat</title> <link rel="stylesheet" href="/style/default"> </head> <body> <h1>Kissat</h1> <nav> <a href="../">Return to photo index</a> </nav> <figure> <img src="/pix/39627052_fd8dcd98b5.jpg"> <figcaption>Kissat</figcaption> </figure> <p>One of them has six toes!</p> <p><small><a rel="license" href="http://www.opensource.org/licenses/mit-license.php">MIT Licensed</a></small></p> <footer> <a href="/">Home</a> | <a href="../">Photo index</a> <p><small>© copyright 2009 Exampl Pictures. All Rights Reserved.</small></p> </footer> </body> </html>
In this case the license
applies to just the photo (the main content of the document), not
the whole document. In particular not the design of the page
itself, which is covered by the copyright given at the bottom of
the document. This could be made clearer in the styling
(e.g. making the license link prominently positioned near the
photograph, while having the page copyright in light small text at
the foot of the page.
Synonyms: For historical reasons, user agents
must also treat the keyword "copyright
" like
the license
keyword.
nofollow
"The nofollow
keyword may be
used with a
and area
elements. This
keyword does not create a hyperlink, but annotates any other hyperlinks
created by the element (the implied hyperlink, if no other keywords
create one).
The nofollow
keyword indicates
that the link is not endorsed by the original author or publisher of
the page, or that the link to the referenced document was included
primarily because of a commercial relationship between people
affiliated with the two pages.
noreferrer
"The noreferrer
keyword may be
used with a
and area
elements. This
keyword does not create a hyperlink, but annotates any other hyperlinks
created by the element (the implied hyperlink, if no other keywords
create one).
It indicates that no referrer information is to be leaked when following the link.
If a user agent follows a link defined by an a
or
area
element that has the noreferrer
keyword, the user agent
must not include a Referer
(sic)
HTTP header (or
equivalent for other protocols) in the request.
This keyword also causes the opener
attribute to remain null if the
hyperlink creates a new browsing context.
prefetch
"The prefetch
keyword may be
used with link
, a
, and area
elements. This keyword creates an external resource link.
The prefetch
keyword indicates
that preemptively fetching and caching the specified resource is
likely to be beneficial, as it is highly likely that the user will
require this resource.
There is no default type for resources given by the prefetch
keyword.
search
"The search
keyword may be used
with link
, a
, and area
elements. This keyword creates a hyperlink.
The search
keyword indicates that
the referenced document provides an interface specifically for
searching the document and its related resources.
OpenSearch description documents can be used with
link
elements and the search
link type to enable user agents to
autodiscover search interfaces. [OPENSEARCH]
stylesheet
"The stylesheet
keyword may be
used with link
elements. This keyword creates an external resource link that
contributes to the styling processing model.
The specified resource is a resource that describes how to present the document. Exactly how the resource is to be processed depends on the actual type of the resource.
If the alternate
keyword is
also specified on the link
element, then the link
is an alternative stylesheet; in this case, the title
attribute must be specified on the
link
element, with a non-empty value.
The default type for resources given by the stylesheet
keyword is text/css
.
The appropriate time to obtain the resource is when the external resource link is created or when its element is inserted into a document, whichever happens last. If the resource is an alternative stylesheet then the user agent may defer obtaining the resource until it is part of the preferred style sheet set. [CSSOM]
Quirk: If the document has been set to
quirks mode, has the same origin as the
URL of the external resource, and
the Content-Type metadata of the
external resource is not a supported style sheet type, the user
agent must instead assume it to be text/css
.
tag
"The tag
keyword may be used with
a
and area
elements. This keyword creates
a hyperlink.
The tag
keyword indicates that the
tag that the referenced document represents applies to the
current document.
Since it indicates that the tag applies to the current document, it would be inappropriate to use this keyword in the markup of a tag cloud, which lists the popular tags across a set of pages.
Some documents form part of a sequence of documents.
A sequence of documents is one where each document can have a previous sibling and a next sibling. A document with no previous sibling is the start of its sequence, a document with no next sibling is the end of its sequence.
A document may be part of multiple sequences.
next
"The next
keyword may be used with
link
, a
, and area
elements. This keyword creates a hyperlink.
The next
keyword indicates that the
document is part of a sequence, and that the link is leading to the
document that is the next logical document in the sequence.
prev
"The prev
keyword may be used with
link
, a
, and area
elements. This keyword creates a hyperlink.
The prev
keyword indicates that the
document is part of a sequence, and that the link is leading to the
document that is the previous logical document in the sequence.
Synonyms: For historical reasons, user agents
must also treat the keyword "previous
" like
the prev
keyword.
Extensions to the predefined set of link types may be registered in the microformats wiki existing-rel-values page. [MFREL]
Anyone is free to edit the microformats wiki existing-rel-values page at any time to add a type. Extension types must be specified with the following information:
The actual value being defined. The value should not be confusingly similar to any other defined value (e.g. differing only in case).
If the value contains a U+003A COLON character (:), it must also be an absolute URL.
link
One of the following:
link
elements.link
element;
it creates a hyperlink.link
element;
it creates an external resource link.a
and area
One of the following:
a
and
area
elements.a
and
area
elements; it creates a
hyperlink.a
and
area
elements; it creates an external resource
link.a
and
area
elements; it annotates other hyperlinks created by the element.A short non-normative description of what the keyword's meaning is.
A link to a more detailed description of the keyword's semantics and requirements. It could be another page on the Wiki, or a link to an external page.
A list of other keyword values that have exactly the same processing requirements. Authors should not use the values 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 keyword is found to be redundant with existing values, it should be removed and listed as a synonym for the existing value.
If a keyword 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 keyword 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 keyword 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 microformats wiki existing-rel-values page to establish if a value is allowed or not: values defined in this specification or marked as "proposed" or "ratified" must be accepted when used on the elements for which they apply as described in the "Effect on..." field, 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 type 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.
Types defined as extensions in the microformats
wiki existing-rel-values page with the status "proposed" or
"ratified" may be used with the rel
attribute
on link
, a
, and area
elements
in accordance to the "Effect on..." field. [MFREL]
The main content of a page — not including headers and footers, navigation links, sidebars, advertisements, and so forth — can be marked up in a variety of ways, depending on the needs of the author.
The simplest solution is to not mark up the main content at all,
and just leave it as implicit. Another way to think of this is that
the body
elements marks up the main content of the
page, and the bits that aren't main content are excluded through the
use of more appropriate elements like aside
and
nav
.
Here is a short Web page marked up along this minimalistic
school of thought. The main content is highlighted. Notice how all
the other content in the body
is marked up
with elements to indicate that it's not part of the main content,
in this case header
, nav
, and
footer
.
<!DOCTYPE HTML> <html> <head> <title> My Toys </title> </head> <body> <header> <h1>My toys</h1> </header> <nav> <p><a href="/">Home</a></p> <p><a href="/contact">Contact</a></p> </nav> <p>I really like my chained book and my telephone. I'm not such a fan of my big ball.</p> <p>Another toy I like is my mirror.</p> <footer> <p>© copyright 2010 by the boy</p> </footer> </body> </html>
If the main content is an independent unit of content that one
could imagine syndicating independently, then the
article
element would be appropriate to mark up the
main content of the document.
The document in the previous example is here recast as a blog post:
<!DOCTYPE HTML> <html> <head> <title> The Boy Blog: My Toys </title> </head> <body> <header> <h1>The Boy Blog</h1> </header> <nav> <p><a href="/">Home</a></p> <p><a href="/contact">Contact</a></p> </nav> <article> <header> <h1>My toys</h1> <p>Published August 4th</p> </header> <p>I really like my chained book and my telephone. I'm not such a fan of my big ball.</p> <p>Another toy I like is my mirror.</p> </article> <footer> <p>© copyright 2010 by the boy</p> </footer> </body> </html>
If the main content is not an independent unit of content so much
as a section of a larger work, for instance a chapter, then the
section
element would be appropriate to mark up the
main content of the document.
Here is the same document, case as a chapter in an online book:
<!DOCTYPE HTML> <html> <head> <title> Chapter 2: My Toys — The Book of the Boy </title> </head> <body> <header> <h1>Chapter 2: My Toys</h1> </header> <nav> <p><a href="/">Front Page</a></p> <p><a href="/toc">Table of Contents</a></p> <p><a href="/c1">Chapter 1</a> — <a href="/c3">Chapter 3</a></p> </nav> <section> <p>I really like my chained book and my telephone. I'm not such a fan of my big ball.</p> <p>Another toy I like is my mirror.</p> </section> <footer> <p>© copyright 2010 by the boy</p> </footer> </body> </html>
If neither article
nor section
would be
appropriate, but the main content still needs an explicit element,
for example for styling purposes, then the div
element
can be used.
This is the same as the original example, but using
div
for the main content instead of leaving it
implied:
<!DOCTYPE HTML> <html> <head> <title> My Toys </title> <style> body > div { background: navy; color: yellow; } </style> </head> <body> <header> <h1>My toys</h1> </header> <nav> <p><a href="/">Home</a></p> <p><a href="/contact">Contact</a></p> </nav> <div> <p>I really like my chained book and my telephone. I'm not such a fan of my big ball.</p> <p>Another toy I like is my mirror.</p> </div> <footer> <p>© copyright 2010 by the boy</p> </footer> </body> </html>
This specification does not provide a machine-readable way of
describing bread-crumb navigation menus. Authors are encouraged to
just use a series of links in a paragraph. The nav
element can be used to mark the section containing these
paragraphs as being navigation blocks.
In the following example, the current page can be reached via two paths.
<nav> <p> <a href="/">Main</a> > <a href="/products/">Products</a> > <a href="/products/dishwashers/">Dishwashers</a> > <a>Second hand</a> </p> <p> <a href="/">Main</a> > <a href="/second-hand/">Second hand</a> > <a>Dishwashers</a> </p> </nav>
This specification does not define any markup
specifically for marking up lists of keywords that apply to a group
of pages (also known as tag clouds). In general, authors are
encouraged to either mark up such lists using ul
elements with explicit inline counts that are then hidden and turned
into a presentational effect using a style sheet, or to use SVG.
Here, three tags are included in a short tag cloud:
<style> @media screen, print, handheld, tv { /* should be ignored by non-visual browsers */ .tag-cloud > li > span { display: none; } .tag-cloud > li { display: inline; } .tag-cloud-1 { font-size: 0.7em; } .tag-cloud-2 { font-size: 0.9em; } .tag-cloud-3 { font-size: 1.1em; } .tag-cloud-4 { font-size: 1.3em; } .tag-cloud-5 { font-size: 1.5em; } } </style> ... <ul class="tag-cloud"> <li class="tag-cloud-4"><a title="28 instances" href="/t/apple">apple</a> <span>(popular)</span> <li class="tag-cloud-2"><a title="6 instances" href="/t/kiwi">kiwi</a> <span>(rare)</span> <li class="tag-cloud-5"><a title="41 instances" href="/t/pear">pear</a> <span>(very popular)</span> </ul>
The actual frequency of each tag is given using the title
attribute. A CSS style sheet is
provided to convert the markup into a cloud of differently-sized
words, but for user agents that do not support CSS or are not
visual, the markup contains annotations like "(popular)" or
"(rare)" to categorize the various tags by frequency, thus enabling
all users to benefit from the information.
The ul
element is used (rather than
ol
) because the order is not particularly important:
while the list is in fact ordered alphabetically, it would convey
the same information if ordered by, say, the length of the tag.
The tag
rel
-keyword is not used
on these a
elements because they do not represent tags
that apply to the page itself; they are just part of an index
listing the tags themselves.
This specification does not define a specific element for marking up conversations, meeting minutes, chat transcripts, dialogues in screenplays, instant message logs, and other situations where different players take turns in discourse.
Instead, authors are encouraged to mark up conversations using
p
elements and punctuation. Authors who need to mark
the speaker for styling purposes are encouraged to use
span
or b
. Paragraphs with their text
wrapped in the i
element can be used for marking up
stage directions.
This example demonstrates this using an extract from Abbot and Costello's famous sketch, Who's on first:
<p> Costello: Look, you gotta first baseman? <p> Abbott: Certainly. <p> Costello: Who's playing first? <p> Abbott: That's right. <p> Costello becomes exasperated. <p> Costello: When you pay off the first baseman every month, who gets the money? <p> Abbott: Every dollar of it.
The following extract shows how an IM conversation log could be
marked up, using the data
element to provide Unix
timestamps for each line. Note that the timestamps are provided in
a format that the time
element does not support, so
the data
element is used instead (namely, Unix time_t
timestamps). Had the author wished to mark
up the data using one of the date and time formats supported by the
time
element, that element could have been used
instead of data
. This could be advantageous as it
would allow data analysis tools to detect the timestamps
unambiguously, without coordination with the page author.
<p> <data value="1319898155">14:22</data> <b>egof</b> I'm not that nerdy, I've only seen 30% of the star trek episodes <p> <data value="1319898192">14:23</data> <b>kaj</b> if you know what percentage of the star trek episodes you have seen, you are inarguably nerdy <p> <data value="1319898200">14:23</data> <b>egof</b> it's unarguably <p> <data value="1319898228">14:23</data> <i>* kaj blinks</i> <p> <data value="1319898260">14:24</data> <b>kaj</b> you are not helping your case
HTML does not have a good way to mark up graphs, so descriptions
of interactive conversations from games are more difficult to mark
up. This example shows one possible convention using
dl
elements to list the possible responses at each
point in the conversation. Another option to consider is describing
the conversation in the form of a DOT file, and outputting the
result as an SVG image to place in the document. [DOT]
<p> Next, you meet a fisherman. You can say one of several greetings: <dl> <dt> "Hello there!" <dd> <p> He responds with "Hello, how may I help you?"; you can respond with: <dl> <dt> "I would like to buy a fish." <dd> <p> He sells you a fish and the conversation finishes. <dt> "Can I borrow your boat?" <dd> <p> He is surprised and asks "What are you offering in return?". <dl> <dt> "Five gold." (if you have enough) <dt> "Ten gold." (if you have enough) <dt> "Fifteen gold." (if you have enough) <dd> <p> He lends you his boat. The conversation ends. <dt> "A fish." (if you have one) <dt> "A newspaper." (if you have one) <dt> "A pebble." (if you have one) <dd> <p> "No thanks", he replies. Your conversation options at this point are the same as they were after asking to borrow his boat, minus any options you've suggested before. </dl> </dd> </dl> </dd> <dt> "Vote for me in the next election!" <dd> <p> He turns away. The conversation finishes. <dt> "Sir, are you aware that your fish are running away?" <dd> <p> He looks at you skeptically and says "Fish cannot run, sir". <dl> <dt> "You got me!" <dd> <p> The fisherman sighs and the conversation ends. <dt> "Only kidding." <dd> <p> "Good one!" he retorts. Your conversation options at this point are the same as those following "Hello there!" above. <dt> "Oh, then what are they doing?" <dd> <p> He looks at his fish, giving you an opportunity to steal his boat, which you do. The conversation ends. </dl> </dd> </ul>
HTML does not have a dedicated mechanism for marking up footnotes. Here are the recommended alternatives.
For short inline annotations, the title
attribute should be used.
In this example, two parts of a dialogue are annotated with
footnote-like content using the title
attribute.
<p> <b>Customer</b>: Hello! I wish to register a complaint. Hello. Miss? <p> <b>Shopkeeper</b>: <span title="Colloquial pronunciation of 'What do you'" >Watcha</span> mean, miss? <p> <b>Customer</b>: Uh, I'm sorry, I have a cold. I wish to make a complaint. <p> <b>Shopkeeper</b>: Sorry, <span title="This is, of course, a lie.">we're closing for lunch</span>.
For longer annotations, the a
element should be
used, pointing to an element later in the document. The convention
is that the contents of the link be a number in square brackets.
In this example, a footnote in the dialogue links to a paragraph below the dialogue. The paragraph then reciprocally links back to the dialogue, allowing the user to return to the location of the footnote.
<p> Announcer: Number 16: The <i>hand</i>. <p> Interviewer: Good evening. I have with me in the studio tonight Mr Norman St John Polevaulter, who for the past few years has been contradicting people. Mr Polevaulter, why <em>do</em> you contradict people? <p> Norman: I don't. <sup><a href="#fn1" id="r1">[1]</a></sup> <p> Interviewer: You told me you did! ... <section> <p id="fn1"><a href="#r1">[1]</a> This is, naturally, a lie, but paradoxically if it were true he could not say so without contradicting the interviewer and thus making it false.</p> </section>
For side notes, longer annotations that apply to entire sections
of the text rather than just specific words or sentences, the
aside
element should be used.
In this example, a sidebar is given after a dialogue, giving it some context.
<p> <span class="speaker">Customer</span>: I will not buy this record, it is scratched. <p> <span class="speaker">Shopkeeper</span>: I'm sorry? <p> <span class="speaker">Customer</span>: I will not buy this record, it is scratched. <p> <span class="speaker">Shopkeeper</span>: No no no, this's'a tobacconist's. <aside> <p>In 1970, the British Empire lay in ruins, and foreign nationalists frequented the streets — many of them Hungarians (not the streets — the foreign nationals). Sadly, Alexander Yalt has been publishing incompetently-written phrase books. </aside>
For figures or tables, footnotes can be included in the relevant
figcaption
or caption
element, or in
surrounding prose.
In this example, a table has cells with footnotes
that are given in prose. A figure
element is used to
give a single legend to the combination of the table and its
footnotes.
<figure> <figcaption>Table 1. Alternative activities for knights.</figcaption> <table> <tr> <th> Activity <th> Location <th> Cost <tr> <td> Dance <td> Wherever possible <td> £0<sup><a href="#fn1">1</a></sup> <tr> <td> Routines, chorus scenes<sup><a href="#fn2">2</a></sup> <td> Undisclosed <td> Undisclosed <tr> <td> Dining<sup><a href="#fn3">3</a></sup> <td> Camelot <td> Cost of ham, jam, and spam<sup><a href="#fn4">4</a></sup> </table> <p id="fn1">1. Assumed.</p> <p id="fn2">2. Footwork impeccable.</p> <p id="fn3">3. Quality described as "well".</p> <p id="fn4">4. A lot.</p> </figure>
The Selectors specification leaves the case-sensitivity of IDs, classes, element names, attribute names, and attribute values to be defined by the host language. [SELECTORS]
The unique identifier of HTML elements in documents that are in quirks mode must be treated as ASCII case-insensitive for the purposes of selector matching.
Classes from the class
attribute
of HTML elements in documents that are in quirks
mode must be treated as ASCII case-insensitive
for the purposes of selector matching.
Attribute and element names of HTML elements in HTML documents must be treated as ASCII case-insensitive for the purposes of selector matching.
Everything else (attribute values on HTML elements, IDs and classes in no-quirks mode and limited-quirks mode, and element names, attribute names, and attribute values in XML documents) must be treated as case-sensitive for the purposes of selector matching.
There are a number of dynamic selectors that can be used with HTML. This section defines when these selectors match HTML elements. [SELECTORS] [CSSUI]
:link
:visited
All a
elements that have an href
attribute, all
area
elements that have an href
attribute, and all
link
elements that have an href
attribute, must match one of
:link
and :visited
.
Other specifications might apply more specific rules regarding how these elements are to match these pseudo-elements, to mitigate some privacy concerns that apply with straightforward implementations of this requirement.
:active
The :active
pseudo-class
is defined to match an element while
an element is being activated by the user
. For the
purposes of defining the :active
pseudo-class only, an HTML
user agent must consider an element as being activated if
it is:
An element falling into one of the following categories between the time the user begins to indicate an intent to trigger the element's activation behavior and either the time the user stops indicating an intent to trigger the element's activation behavior, or the time the element's activation behavior has finished running, which ever comes first:
a
elements that have an href
attributearea
elements that have an href
attributelink
elements that have an href
attributebutton
elements that are not disabledinput
elements whose type
attribute is in the Submit Button, Image Button, Reset Button, or Button statecommand
elements that do not have a disabled
attributeFor example, if the user is using a keyboard
to push a button
element by pressing the space bar,
the element would match this pseudo-class in between the time
that the element received the keydown
event and the time the
element received the keyup
event.
An element that the user indicates using a pointing device while that pointing device is in the "down" state (e.g. for a mouse, between the time the mouse button is pressed and the time it is depressed).
An element that has a descendant that is currently matching
the :active
pseudo-class.
:hover
The :hover
pseudo-class is
defined to match an element while
the user designates an element with a pointing device
.
For the purposes of defining the :hover
pseudo-class only, an HTML
user agent must consider an element as being one that the user
designates if it is:
An element that the user indicates using a pointing device.
An element that has a descendant that the user indicates using a pointing device.
An element that is the labeled control of a
label
element that is currently matching :hover.
Consider in particular a fragment such as:
<p> <label for=c> <input id=a> </label> <span id=b> <input id=c> </span> </p>
If the user designates the element with ID "a
" with their pointing device, then the
p
element (and all its ancestors not shown in the
snippet above), the label
element, the element with
ID "a
", and the element with ID "c
" will match the :hover pseudo-class. The element
with ID "a
" matches it from condition 1,
the label
and p
elements match it
because of condition 2 (one of their descendants is designated),
and the element with ID "c
" matches it
through condition 3 (its label
element matches :hover). However, the element with
ID "b
" does not match :hover: its descendant is not
designated, even though it matches :hover.
:enabled
The :enabled
pseudo-class
must match any element falling into one of the following
categories:
a
elements that have an href
attributearea
elements that have an href
attributelink
elements that have an href
attributebutton
elements that are not disabledinput
elements whose type
attribute are not in the
Hidden state and that
are not disabledselect
elements that are not disabledtextarea
elements that are not disabledoptgroup
elements that do not have a disabled
attributeoption
elements that are not disabledcommand
elements that do not have a disabled
attributeli
elements that are children of
menu
elements, and that have a child element that
defines a command, if the
first such element's Disabled State facet
is false (not disabled)fieldset
elements that do not have a disabled
attribute:disabled
The :disabled
pseudo-class must match any element falling into one of the
following categories:
button
elements that are disabledinput
elements whose type
attribute are not in the
Hidden state and that
are disabledselect
elements that are disabledtextarea
elements that are disabledoptgroup
elements that have a disabled
attributeoption
elements that are disabledcommand
elements that have a disabled
attributeli
elements that are children of
menu
elements, and that have a child element that
defines a command, if the
first such element's Disabled State facet
is true (disabled)fieldset
elements that have a disabled
attribute:checked
The :checked
pseudo-class
must match any element falling into one of the following
categories:
input
elements whose type
attribute is in the Checkbox state and whose
checkedness state is
trueinput
elements whose type
attribute is in the Radio Button state and whose
checkedness state is
trueoption
elements whose selectedness is
truecommand
elements whose type
attribute is in the Checkbox state
and that have a checked
attributecommand
elements whose type
attribute is in the Radio state and that
have a checked
attribute:indeterminate
The :indeterminate
pseudo-class must match any element falling into one of the
following categories:
:default
The :default
pseudo-class
must match any element falling into one of the following
categories:
button
elements that are their form's
default buttoninput
elements whose type
attribute is in the Submit Button or Image Button state, and that
are their form's default buttoninput
elements to which the checked
attribute applies and
that have a checked
attributeoption
elements that have a selected
attribute:valid
The :valid
pseudo-class
must match any element falling into one of the following
categories:
form
elements that are not the form
owner of any elements that themselves are candidates for
constraint validation but do not satisfy their constraints:invalid
The :invalid
pseudo-class
must match any element falling into one of the following
categories:
form
elements that are the form
owner of one or more elements that themselves are candidates for
constraint validation but do not satisfy their constraints:in-range
The :in-range
pseudo-class must match all elements that are candidates for
constraint validation, have range limitations,
and that are neither suffering from an underflow nor
suffering from an overflow.
:out-of-range
The :out-of-range
pseudo-class must match all elements that are candidates for
constraint validation, have range limitations,
and that are either suffering from an underflow or
suffering from an overflow.
:required
The :required
pseudo-class must match any element falling into one of the
following categories:
:optional
The :optional
pseudo-class must match any element falling into one of the
following categories:
:read-only
:read-write
The :read-write
pseudo-class must match any element falling into one of the
following categories:
input
elements to which the readonly
attribute applies,
and that are mutable (i.e. that
do not have the readonly
attribute specified and that are not disabled)textarea
elements that do not have a readonly
attribute, and
that are not disabledinput
elements nor textarea
elementsThe :read-only
pseudo-class must match all other HTML elements.
:dir(ltr)
The :dir(ltr)
pseudo-class must
match all elements whose directionality is 'ltr'.
:dir(rtl)
The :dir(rtl)
pseudo-class must
match all elements whose directionality is 'rtl'.
Another section of this specification defines the
target element used with the :target
pseudo-class.
This specification does not define when an element
matches the :focus
or :lang()
dynamic pseudo-classes, as
those are all defined in sufficient detail in a language-agnostic
fashion in the Selectors specification. [SELECTORS]
This section is non-normative.
Sometimes, it is desirable to annotate content with specific machine-readable labels, e.g. to allow generic scripts to provide services that are customised to the page, or to enable content from a variety of cooperating authors to be processed by a single script in a consistent manner.
For this purpose, authors can use the microdata features described in this section. Microdata allows nested groups of name-value pairs to be added to documents, in parallel with the existing content.
This section is non-normative.
At a high level, microdata consists of a group of name-value pairs. The groups are called items, and each name-value pair is a property. Items and properties are represented by regular elements.
To create an item, the itemscope
attribute is used.
To add a property to an item, the itemprop
attribute is used on one of
the item's descendants.
Here there are two items, each of which has the property "name":
<div itemscope> <p>My name is <span itemprop="name">Elizabeth</span>.</p> </div> <div itemscope> <p>My name is <span itemprop="name">Daniel</span>.</p> </div>
Properties generally have values that are strings.
Here the item has three properties:
<div itemscope> <p>My name is <span itemprop="name">Neil</span>.</p> <p>My band is called <span itemprop="band">Four Parts Water</span>.</p> <p>I am <span itemprop="nationality">British</span>.</p> </div>
When a string value is a URLs, it is
expressed using the a
element and its href
attribute, the
img
element and its src
attribute, or other elements that
link to or embed external resources.
In this example, the item has one property, "image", whose value is a URL:
<div itemscope> <img itemprop="image" src="google-logo.png" alt="Google"> </div>
When a string value is in some machine-readable format unsuitable
for human consumption, it is expressed using the value
attribute of the
data
element, with the human-readable version given in
the element's contents.
Here, there is an item with a property whose value is a product ID. The ID is not human-friendly, so the product's name is used the human-visible text instead of the ID.
<h1 itemscope> <data itemprop="product-id" value="9678AOU879">The Instigator 2000</data> </h1>
For date- and time-related data, the time
element
and its datetime
attribute
can be used instead.
In this example, the item has one property, "birthday", whose value is a date:
<div itemscope> I was born on <time itemprop="birthday" datetime="2009-05-10">May 10th 2009</time>. </div>
Properties can also themselves be groups of name-value pairs, by
putting the itemscope
attribute
on the element that declares the property.
Items that are not part of others are called top-level microdata items.
In this example, the outer item represents a person, and the inner one represents a band:
<div itemscope> <p>Name: <span itemprop="name">Amanda</span></p> <p>Band: <span itemprop="band" itemscope> <span itemprop="name">Jazz Band</span> (<span itemprop="size">12</span> players)</span></p> </div>
The outer item here has two properties, "name" and "band". The "name" is "Amanda", and the "band" is an item in its own right, with two properties, "name" and "size". The "name" of the band is "Jazz Band", and the "size" is "12".
The outer item in this example is a top-level microdata item.
Properties that are not descendants of the element with the itemscope
attribute can be associated
with the item using the itemref
attribute. This attribute takes
a list of IDs of elements to crawl in addition to crawling the
children of the element with the itemscope
attribute.
This example is the same as the previous one, but all the properties are separated from their items:
<div itemscope id="amanda" itemref="a b"></div> <p id="a">Name: <span itemprop="name">Amanda</span></p> <div id="b" itemprop="band" itemscope itemref="c"></div> <div id="c"> <p>Band: <span itemprop="name">Jazz Band</span></p> <p>Size: <span itemprop="size">12</span> players</p> </div>
This gives the same result as the previous example. The first item has two properties, "name", set to "Amanda", and "band", set to another item. That second item has two further properties, "name", set to "Jazz Band", and "size", set to "12".
An item can have multiple properties with the same name and different values.
This example describes an ice cream, with two flavors:
<div itemscope> <p>Flavors in my favorite ice cream:</p> <ul> <li itemprop="flavor">Lemon sorbet</li> <li itemprop="flavor">Apricot sorbet</li> </ul> </div>
This thus results in an item with two properties, both "flavor", having the values "Lemon sorbet" and "Apricot sorbet".
An element introducing a property can also introduce multiple properties at once, to avoid duplication when some of the properties have the same value.
Here we see an item with two properties, "favorite-color" and "favorite-fruit", both set to the value "orange":
<div itemscope> <span itemprop="favorite-color favorite-fruit">orange</span> </div>
It's important to note that there is no relationship between the microdata and the content of the document where the microdata is marked up.
There is no semantic difference, for instance, between the following two examples:
<figure> <img src="castle.jpeg"> <figcaption><span itemscope><span itemprop="name">The Castle</span></span> (1986)</figcaption> </figure>
<span itemscope><meta itemprop="name" content="The Castle"></span> <figure> <img src="castle.jpeg"> <figcaption>The Castle (1986)</figcaption> </figure>
Both have a figure with a caption, and both, completely unrelated to the figure, have an item with a name-value pair with the name "name" and the value "The Castle". The only difference is that if the user drags the caption out of the document, in the former case, the item will be included in the drag-and-drop data. In neither case is the image in any way associated with the item.
This section is non-normative.
The examples in the previous section show how information could be marked up on a page that doesn't expect its microdata to be re-used. Microdata is most useful, though, when it is used in contexts where other authors and readers are able to cooperate to make new uses of the markup.
For this purpose, it is necessary to give each item a type, such as "http://example.com/person", or "http://example.org/cat", or "http://band.example.net/". Types are identified as URLs.
The type for an item is given
as the value of an itemtype
attribute on the same element as the itemscope
attribute.
Here, the item's type is "http://example.org/animals#cat":
<section itemscope itemtype="http://example.org/animals#cat"> <h1 itemprop="name">Hedral</h1> <p itemprop="desc">Hedral is a male american domestic shorthair, with a fluffy black fur with white paws and belly.</p> <img itemprop="img" src="hedral.jpeg" alt="" title="Hedral, age 18 months"> </section>
In this example the "http://example.org/animals#cat" item has three properties, a "name" ("Hedral"), a "desc" ("Hedral is..."), and an "img" ("hedral.jpeg").
The type gives the context for the properties, thus defining a
vocabulary: a property named "class" given for an item with the type
"http://census.example/person" might refer to the economic class of
an individual, while a property named "class" given for an item with
the type "http://example.com/school/teacher" might refer to the
classroom a teacher has been assigned. Several types can share a
vocabulary. For example, the types "http://example.org/people/teacher
" and "http://example.org/people/engineer
" could be defined
to use the same vocabulary (though maybe some properties would not
be especially useful in both cases, e.g. maybe the "http://example.org/people/engineer
" type might not
typically be used with the "classroom
"
property). Multiple types defined to use the same vocabulary can be
given for a single item by listing the URLs as a space-separated
list in the attribute' value. An item cannot be given two types if
they do not use the same vocabulary, however.
This section is non-normative.
Sometimes, an item gives information about a topic that has a global identifier. For example, books can be identified by their ISBN number.
Vocabularies (as identified by the itemtype
attribute) can be designed
such that items get associated
with their global identifier in an unambiguous way by expressing the
global identifiers as URLs given in an
itemid
attribute.
The exact meaning of the URLs given in
itemid
attributes depends on the
vocabulary used.
Here, an item is talking about a particular book:
<dl itemscope itemtype="http://vocab.example.net/book" itemid="urn:isbn:0-330-34032-8"> <dt>Title <dd itemprop="title">The Reality Dysfunction <dt>Author <dd itemprop="author">Peter F. Hamilton <dt>Publication date <dd><time itemprop="pubdate" datetime="1996-01-26">26 January 1996</time> </dl>
The "http://vocab.example.net/book
"
vocabulary in this example would define that the itemid
attribute takes a urn:
URL pointing to the ISBN of the
book.
This section is non-normative.
Using microdata means using a vocabulary. For some purposes, an ad-hoc vocabulary is adequate. For others, a vocabulary will need to be designed. Where possible, authors are encouraged to re-use existing vocabularies, as this makes content re-use easier.
When designing new vocabularies, identifiers can be created either using URLs, or, for properties, as plain words (with no dots or colons). For URLs, conflicts with other vocabularies can be avoided by only using identifiers that correspond to pages that the author has control over.
For instance, if Jon and Adam both write content at example.com
, at http://example.com/~jon/...
and http://example.com/~adam/...
respectively, then
they could select identifiers of the form
"http://example.com/~jon/name" and "http://example.com/~adam/name"
respectively.
Properties whose names are just plain words can only be used within the context of the types for which they are intended; properties named using URLs can be reused in items of any type. If an item has no type, and is not part of another item, then if its properties have names that are just plain words, they are not intended to be globally unique, and are instead only intended for limited use. Generally speaking, authors are encouraged to use either properties with globally unique names (URLs) or ensure that their items are typed.
Here, an item is an "http://example.org/animals#cat", and most of the properties have names that are words defined in the context of that type. There are also a few additional properties whose names come from other vocabularies.
<section itemscope itemtype="http://example.org/animals#cat"> <h1 itemprop="name http://example.com/fn">Hedral</h1> <p itemprop="desc">Hedral is a male american domestic shorthair, with a fluffy <span itemprop="http://example.com/color">black</span> fur with <span itemprop="http://example.com/color">white</span> paws and belly.</p> <img itemprop="img" src="hedral.jpeg" alt="" title="Hedral, age 18 months"> </section>
This example has one item with the type "http://example.org/animals#cat" and the following properties:
Property | Value |
name | Hedral |
http://example.com/fn | Hedral |
desc | Hedral is a male american domestic shorthair, with a fluffy black fur with white paws and belly. |
http://example.com/color | black |
http://example.com/color | white |
img | .../hedral.jpeg |
This section is non-normative.
The microdata becomes even more useful when scripts can use it to expose information to the user, for example offering it in a form that can be used by other applications.
The document.getItems(typeNames)
method provides access to the
top-level microdata items. It returns a
NodeList
containing the items with the specified types,
or all types if no argument is specified.
Each item is represented in the
DOM by the element on which the relevant itemscope
attribute is found. These
elements have their element.itemScope
IDL attribute set to
true.
The type(s) of items can be
obtained using the element.itemType
IDL attribute on the
element with the itemscope
attribute.
This sample shows how the getItems()
method can be used
to obtain a list of all the top-level microdata items of a
particular type given in the document:
var cats = document.getItems("http://example.com/feline");
Once an element representing an item has been obtained, its properties
can be extracted using the properties
IDL attribute. This
attribute returns an HTMLPropertiesCollection
, which can
be enumerated to go through each element that adds one or more
properties to the item. It can also be indexed by name, which will
return an object with a list of the elements that add properties
with that name.
Each element that adds a property also has a itemValue
IDL attribute that returns
its value.
This sample gets the first item of type "http://example.net/user" and then pops up an alert using the "name" property from that item.
var user = document.getItems('http://example.net/user')[0]; alert('Hello ' + user.properties['name'][0].itemValue + '!');
The HTMLPropertiesCollection
object, when indexed by
name in this way, actually returns a PropertyNodeList
object with all the matching properties. The
PropertyNodeList
object can be used to obtain all the
values at once using its getValues
method,
which returns an array of all the values.
In an earlier example, a "http://example.org/animals#cat" item had two "http://example.com/color" values. This script looks up the first such item and then lists all its values.
var cat = document.getItems('http://example.org/animals#cat')[0]; var colors = cat.properties['http://example.com/color'].getValues(); var result; if (colors.length == 0) { result = 'Color unknown.'; } else if (colors.length == 1) { result = 'Color: ' + colors[0]; } else { result = 'Colors:'; for (var i = 0; i < colors.length; i += 1) result += ' ' + colors[i]; }
It's also possible to get a list of all the property
names using the object's names
IDL
attribute.
This example creates a big list with a nested list for each item on the page, each with of all the property names used in that item.
var outer = document.createElement('ul'); var items = document.getItems(); for (var item = 0; item < items.length; item += 1) { var itemLi = document.createElement('li'); var inner = document.createElement('ul'); for (var name = 0; name < items[item].properties.names.length; name += 1) { var propLi = document.createElement('li'); propLi.appendChild(document.createTextNode(items[item].properties.names[name])); inner.appendChild(propLi); } itemLi.appendChild(inner); outer.appendChild(itemLi); } document.body.appendChild(outer);
If faced with the following from an earlier example:
<section itemscope itemtype="http://example.org/animals#cat"> <h1 itemprop="name http://example.com/fn">Hedral</h1> <p itemprop="desc">Hedral is a male american domestic shorthair, with a fluffy <span itemprop="http://example.com/color">black</span> fur with <span itemprop="http://example.com/color">white</span> paws and belly.</p> <img itemprop="img" src="hedral.jpeg" alt="" title="Hedral, age 18 months"> </section>
...it would result in the following output:
(The duplicate occurrence of "http://example.com/color" is not included in the list.)
The microdata model consists of groups of name-value pairs known as items.
Each group is known as an item. Each item can have item types, a global identifier (if the vocabulary specified by the item types support global identifiers for items), and a list of name-value pairs. Each name in the name-value pair is known as a property, and each property has one or more values. Each value is either a string or itself a group of name-value pairs (an item). The names are unordered relative to each other, but if a particular name has multiple values, they do have a relative order.
An item is said to be a typed item when either it has an item type, or it is the value of a property of a typed item. The relevant types for a typed item is the item's item types, if it has one, or else is the relevant types of the item for which it is a property's value.
Every HTML element may have an
itemscope
attribute
specified. The itemscope
attribute is a boolean attribute.
An element with the itemscope
attribute specified creates a new item, a group of name-value pairs.
Elements with an itemscope
attribute may have an itemtype
attribute
specified, to give the item types of the item.
The itemtype
attribute, if
specified, must have a value that is an unordered set of
unique space-separated tokens that are
case-sensitive, each of which is a valid
URL that is an absolute URL, and all of which
are defined to use the same vocabulary. The attribute's value must
have at least one token.
The item types of an item are the tokens obtained by splitting the element's itemtype
attribute's value on
spaces. If the itemtype
attribute is missing or parsing it in this way finds no tokens, the
item is said to have no item
types.
The item types must all be types defined in applicable specifications and must all be defined to use the same vocabulary.
Except if otherwise specified by that specification, the URLs given as the item types should not be automatically dereferenced.
A specification could define that its item type can be derefenced to provide the user with help information, for example. In fact, vocabulary authors are encouraged to provide useful information at the given URL.
Item types are opaque identifiers, and user agents must not dereference unknown item types, or otherwise deconstruct them, in order to determine how to process items that use them.
The itemtype
attribute must
not be specified on elements that do not have an itemscope
attribute specified.
Elements with an itemscope
attribute and an itemtype
attribute that references a vocabulary that is defined to
support global identifiers for items may also have an
itemid
attribute
specified, to give a global identifier for the item, so that it can be related to other
items on pages elsewhere on the
Web.
The itemid
attribute, if
specified, must have a value that is a valid URL potentially
surrounded by spaces.
The global identifier of an item is the value of its element's itemid
attribute, if it has one, resolved relative to the element on
which the attribute is specified. If the itemid
attribute is missing or if
resolving it fails, it is said to have no global
identifier.
The itemid
attribute must not be
specified on elements that do not have both an itemscope
attribute and an itemtype
attribute specified, and must
not be specified on elements with an itemscope
attribute whose itemtype
attribute specifies a
vocabulary that does not support global identifiers for
items, as defined by that vocabulary's specification.
The exact meaning of a global identifier is determined by the vocabulary's specification. It is up to such specifications to define whether multiple items with the same global identifier (whether on the same page or on different pages) are allowed to exist, and what the processing rules for that vocabulary are with respect to handling the case of multiple items with the same ID.
Elements with an itemscope
attribute may have an itemref
attribute specified,
to give a list of additional elements to crawl to find the
name-value pairs of the item.
The itemref
attribute, if
specified, must have a value that is an unordered set of
unique space-separated tokens that are
case-sensitive, consisting of IDs of elements in the same home
subtree.
The itemref
attribute must not
be specified on elements that do not have an itemscope
attribute specified.
The itemref
attribute is not part of the microdata data model. It is merely a
syntactic construct to aid authors in adding annotations to pages
where the data to be annotated does not follow a convenient tree
structure. For example, it allows authors to mark up data in a table
so that each column defines a separate item, while keeping the properties in
the cells.
This example shows a simple vocabulary used to describe the products of a model railway manufacturer. The vocabulary has just five property names:
This vocabulary has four defined item types:
Each item that uses this vocabulary can be given one or more of these types, depending on what the product is.
Thus, a locomotive might be marked up as:
<dl itemscope itemtype="http://md.example.com/loco http://md.example.com/lighting"> <dt>Name: <dd itemprop="name">Tank Locomotive (DB 80) <dt>Product code: <dd itemprop="product-code">33041 <dt>Scale: <dd itemprop="scale">HO <dt>Digital: <dd itemprop="digital">Delta </dl>
A turnout lantern retrofit kit might be marked up as:
<dl itemscope itemtype="http://md.example.com/track http://md.example.com/lighting"> <dt>Name: <dd itemprop="name">Turnout Lantern Kit <dt>Product code: <dd itemprop="product-code">74470 <dt>Purpose: <dd>For retrofitting 2 <span itemprop="track-type">C</span> Track turnouts. <meta itemprop="scale" content="HO"> </dl>
A passenger car with no lighting might be marked up as:
<dl itemscope itemtype="http://md.example.com/passengers"> <dt>Name: <dd itemprop="name">Express Train Passenger Car (DB Am 203) <dt>Product code: <dd itemprop="product-code">8710 <dt>Scale: <dd itemprop="scale">Z </dl>
Great care is necessary when creating new vocabularies. Often, a hierarchical approach to types can be taken that results in a vocabulary where each item only ever has a single type, which is generally much simpler to manage.
itemprop
attributeEvery HTML element may have an
itemprop
attribute specified, if
doing so adds one or more
properties to one or more items (as defined below).
The itemprop
attribute, if
specified, must have a value that is an unordered set of
unique space-separated tokens that are
case-sensitive, representing the names of the
name-value pairs that it adds. The attribute's value must have at
least one token.
Each token must be either:
Specifications that introduce defined property names that are not absolute URLs must ensure all such property names contain no U+002E FULL STOP characters (.), no U+003A COLON characters (:), and no space characters.
When an element with an itemprop
attribute adds a property to multiple items, the requirement above regarding
the tokens applies for each item
individually.
The property names of an element are the tokens that
the element's itemprop
attribute
is found to contain when its value is split on spaces, with the order preserved but with
duplicates removed (leaving only the first occurrence of each
name).
Within an item, the properties are unordered with respect to each other, except for properties with the same name, which are ordered in the order they are given by the algorithm that defines the properties of an item.
In the following example, the "a" property has the values "1" and "2", in that order, but whether the "a" property comes before the "b" property or not is not important:
<div itemscope> <p itemprop="a">1</p> <p itemprop="a">2</p> <p itemprop="b">test</p> </div>
Thus, the following is equivalent:
<div itemscope> <p itemprop="b">test</p> <p itemprop="a">1</p> <p itemprop="a">2</p> </div>
As is the following:
<div itemscope> <p itemprop="a">1</p> <p itemprop="b">test</p> <p itemprop="a">2</p> </div>
And the following:
<div id="x"> <p itemprop="a">1</p> </div> <div itemscope itemref="x"> <p itemprop="b">test</p> <p itemprop="a">2</p> </div>
The property value of a
name-value pair added by an element with an itemprop
attribute is as given for the
first matching case in the following list:
itemscope
attributeThe value is the item created by the element.
meta
elementThe value is the value of the element's content
attribute, if any, or the
empty string if there is no such attribute.
audio
, embed
,
iframe
, img
, source
,
track
, or video
elementThe value is the absolute URL that results from
resolving the value of the
element's src
attribute relative to the
element at the time the attribute is set, or the empty string if
there is no such attribute or if resolving it results in an error.
a
, area
, or
link
elementThe value is the absolute URL that results from
resolving the value of the
element's href
attribute relative to the
element at the time the attribute is set, or the empty string if
there is no such attribute or if resolving it results in an error.
object
elementThe value is the absolute URL that results from
resolving the value of the
element's data
attribute relative to the
element at the time the attribute is set, or the empty string if
there is no such attribute or if resolving it results in an error.
data
elementThe value is the value of the element's value
attribute, if it has one, or
the empty string otherwise.
time
elementThe value is the element's datetime value.
The value is the element's textContent
.
The URL property elements are the a
,
area
, audio
, embed
,
iframe
, img
, link
,
object
, source
, track
, and
video
elements.
If a property's value, as defined by the property's definition, is an absolute URL, the property must be specified using a URL property element.
These requirements do not apply just because a property value happens to match the syntax for a URL. They only apply if the property is explicitly defined as taking such a value.
For example, a book about the first moon landing
could be called "mission:moon". A "title"
property from a vocabulary that defines a title as being a string
would not expect the title to be given in an a
element,
even though it looks like a URL. On the other hand, if
there was a (rather narrowly scoped!) vocabulary for "books whose
titles look like URLs" which had a "title" property defined to take
a URL, then the property would expect the title to be given
in an a
element (or one of the other URL property
elements), because of the requirement above.
To find the properties of an item defined by the element root, the user agent must run the following steps. These steps are also used to flag microdata errors.
Let results, memory, and pending be empty lists of elements.
Add the element root to memory.
Add the child elements of root, if any, to pending.
If root has an itemref
attribute, split the value of that itemref
attribute on spaces. For
each resulting token ID, if there is an element
in the home subtree of root with
the ID ID, then
add the first such element to pending.
Loop: If pending is empty, jump to the step labeled end of loop.
Remove an element from pending and let current be that element.
If current is already in memory, there is a microdata error; return to the step labeled loop.
Add current to memory.
If current does not
have an itemscope
attribute,
then: add all the child elements of current to
pending.
If current has an itemprop
attribute specified and the
element has one or more property names, then add the
element to results.
Return to the step labeled loop.
End of loop: Sort results in tree order.
Return results.
A document must not contain any items for which the algorithm to find the properties of an item finds any microdata errors.
An item is a top-level microdata item if
its element does not have an itemprop
attribute.
All itemref
attributes in a
Document
must be such that there are no cycles in the
graph formed from representing each item in the Document
as a
node in the graph and each property of an item whose value is another item as an
edge in the graph connecting those two items.
A document must not contain any elements that have an itemprop
attribute that would not be
found to be a property of any of the items in that document were their properties all to be
determined.
In this example, a single license statement is applied to two
works, using itemref
from the
items representing the works:
<!DOCTYPE HTML> <html> <head> <title>Photo gallery</title> </head> <body> <h1>My photos</h1> <figure itemscope itemtype="http://n.whatwg.org/work" itemref="licenses"> <img itemprop="work" src="images/house.jpeg" alt="A white house, boarded up, sits in a forest."> <figcaption itemprop="title">The house I found.</figcaption> </figure> <figure itemscope itemtype="http://n.whatwg.org/work" itemref="licenses"> <img itemprop="work" src="images/mailbox.jpeg" alt="Outside the house is a mailbox. It has a leaflet inside."> <figcaption itemprop="title">The mailbox.</figcaption> </figure> <footer> <p id="licenses">All images licensed under the <a itemprop="license" href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</p> </footer> </body> </html>
The above results in two items with the type "http://n.whatwg.org/work
", one with:
images/house.jpeg
http://www.opensource.org/licenses/mit-license.php
...and one with:
images/mailbox.jpeg
http://www.opensource.org/licenses/mit-license.php
Currently, the itemscope
,
itemprop
, and other microdata
attributes are only defined for HTML elements. This
means that attributes with the literal names "itemscope
", "itemprop
", etc,
do not cause microdata processing to occur on elements in other
namespaces, such as SVG.
Thus, in the following example there is only one item, not two.
<p itemscope></p> <!-- this is an item (with no properties and no type) -->
<svg itemscope></svg> <!-- this is not, it's just an svg
element with an invalid unknown attribute -->
getItems
( [ types ] )Returns a NodeList
of the elements in the Document
that create items, that are not part of other items, and that are of the types given in the argument, if any are listed.
The types argument is interpreted as a space-separated list of types.
properties
If the element has an itemscope
attribute, returns an
HTMLPropertiesCollection
object with all the element's
properties. Otherwise, an empty
HTMLPropertiesCollection
object.
itemValue
[ = value ]Returns the element's value.
Can be set, to change the element's value. Setting the value when the element has
no itemprop
attribute or when
the element's value is an item
throws an InvalidAccessError
exception.
The document.getItems(typeNames)
method takes an optional
string that contains an unordered set of unique
space-separated tokens that are case-sensitive,
representing types. When called, the method must return a
live NodeList
object containing all the
elements in the document, in tree order, that are each
top-level microdata items whose types include all the types specified in the method's
argument, having obtained the types by splitting the string on spaces. If there are no
tokens specified in the argument, or if the argument is missing,
then the method must return a NodeList
containing all
the top-level microdata items in the document. When the
method is invoked on a Document
object again with the
same argument, the user agent may return the same object as the
object returned by the earlier call. In other cases, a new
NodeList
object must be returned.
The itemScope
IDL
attribute on HTML elements must reflect
the itemscope
content attribute.
The itemType
IDL
attribute on HTML elements must reflect
the itemtype
content attribute.
The itemId
IDL attribute
on HTML elements must reflect the itemid
content attribute. The itemProp
IDL attribute on
HTML elements must reflect the itemprop
content attribute. The itemRef
IDL attribute on
HTML elements must reflect the itemref
content attribute.
The properties
IDL
attribute on HTML elements must return an
HTMLPropertiesCollection
rooted at the
Document
node, whose filter matches only elements that
are the properties of the
item created by the element on which the attribute was
invoked, while that element is an item, and matches nothing the rest of
the time.
The itemValue
IDL
attribute's behavior depends on the element, as follows:
itemprop
attributeThe attribute must return null on getting and must throw an
InvalidAccessError
exception on setting.
itemscope
attributeThe attribute must return the element itself on getting and
must throw an InvalidAccessError
exception on
setting.
meta
elementThe attribute must act as it would if it was reflecting the element's content
content
attribute.
audio
, embed
,
iframe
, img
, source
,
track
, or video
elementThe attribute must act as it would if it was reflecting the element's src
content attribute.
a
, area
, or
link
elementThe attribute must act as it would if it was reflecting the element's href
content attribute.
object
elementThe attribute must act as it would if it was reflecting the element's data
content attribute.
data
elementThe attribute must act as it would if it was reflecting the element's value
content attribute.
time
elementOn getting, if the element has a datetime
content attribute, the
IDL attribute must return that content attribute's value;
otherwise, it must return the element's textContent
.
On setting, the IDL attribute must act as it would if it was reflecting the element's datetime
content
attribute.
The attribute must act the same as the element's
textContent
attribute.
When the itemValue
IDL
attribute is reflecting a content
attribute or acting like the element's textContent
attribute, the user agent must, on setting, convert the new value to
the IDL DOMString
value before using it
according to the mappings described above.
In this example, a script checks to see if a particular element element is declaring a particular property, and if it is, it increments a counter:
if (element.itemProp.contains('color')) count += 1;
This script iterates over each of the values of an element's
itemref
attribute, calling a
function for each referenced element:
for (var index = 0; index < element.itemRef.length; index += 1) process(document.getElementById(element.itemRef[index]));
An item with the item type http://microformats.org/profile/hcard
represents a person's or organization's contact information.
This vocabulary does not support global identifiers for items.
The following are the type's defined property names. They are based on the vocabulary defined in the vCard specification and its extensions, where more information on how to interpret the values can be found. [RFC6350]
kind
Describes what kind of contact the item represents.
The value must be text that, when compared in a case-sensitive manner, is equal to one of the kind strings.
A single property with the name kind
may be present within each item with the type http://microformats.org/profile/hcard
.
fn
Gives the formatted text corresponding to the name of the person or organization.
The value must be text.
Exactly one property with the name fn
must be present within each item with the type http://microformats.org/profile/hcard
.
n
Gives the structured name of the person or organization.
The value must be
an item with zero or more of
each of the family-name
, given-name
, additional-name
, honorific-prefix
, and
honorific-suffix
properties.
Exactly one property with the name n
must be present within each item with the type http://microformats.org/profile/hcard
.
family-name
(inside n
)Gives the family name of the person, or the full name of the organization.
The value must be text.
Any number of properties with the name family-name
may be present
within the item that forms the
value of the n
property of an item with the type http://microformats.org/profile/hcard
.
given-name
(inside n
)Gives the given-name of the person.
The value must be text.
Any number of properties with the name given-name
may be present
within the item that forms the
value of the n
property of an item with the type http://microformats.org/profile/hcard
.
additional-name
(inside n
)Gives the any additional names of the person.
The value must be text.
Any number of properties with the name additional-name
may be
present within the item that
forms the value of the
n
property of an item with the type http://microformats.org/profile/hcard
.
honorific-prefix
(inside n
)Gives the honorific prefix of the person.
The value must be text.
Any number of properties with the name honorific-prefix
may be
present within the item that
forms the value of the
n
property of an item with the type http://microformats.org/profile/hcard
.
honorific-suffix
(inside n
)Gives the honorific suffix of the person.
The value must be text.
Any number of properties with the name honorific-suffix
may be
present within the item that
forms the value of the
n
property of an item with the type http://microformats.org/profile/hcard
.
nickname
Gives the nickname of the person or organization.
The nickname is the descriptive name given instead
of or in addition to the one belonging to a person, place, or
thing. It can also be used to specify a familiar form of a proper
name specified by the fn
or n
properties.
The value must be text.
Any number of properties with the name nickname
may be present within
each item with the type http://microformats.org/profile/hcard
.
photo
Gives a photograph of the person or organization.
The value must be an absolute URL.
Any number of properties with the name photo
may be present within each
item with the type http://microformats.org/profile/hcard
.
bday
Gives the birth date of the person or organization.
The value must be a valid date string.
A single property with the name bday
may be present within each item with the type http://microformats.org/profile/hcard
.
anniversary
Gives the birth date of the person or organization.
The value must be a valid date string.
A single property with the name anniversary
may be present
within each item with the type
http://microformats.org/profile/hcard
.
sex
Gives the biological sex of the person.
The value must be one of
F
, meaning "female",
M
, meaning "male",
N
, meaning "none or not applicable",
O
, meaning "other", or
U
, meaning "unknown".
A single property with the name sex
may be present within each item with the type http://microformats.org/profile/hcard
.
gender-identity
Gives the gender identity of the person.
The value must be text.
A single property with the name gender-identity
may be
present within each item with
the type http://microformats.org/profile/hcard
.
adr
Gives the delivery address of the person or organization.
The value must be
an item with zero or more type
, post-office-box
, extended-address
, and
street-address
properties, and optionally a locality
property, optionally
a region
property,
optionally a postal-code
property, and
optionally a country-name
property.
If no type
properties
are present within an item that
forms the value of an
adr
property of an item with the type http://microformats.org/profile/hcard
, then the address type
strings intl
,
postal
, parcel
, and work
are implied.
Any number of properties with the name adr
may be present within each item with the type http://microformats.org/profile/hcard
.
type
(inside adr
)Gives the type of delivery address.
The value must be text that, when compared in a case-sensitive manner, is equal to one of the address type strings.
Within each item with the
type http://microformats.org/profile/hcard
, there must be no more
than one adr
property item with a type
property whose value is
pref
.
Any number of properties with the name type
may be present within the
item that forms the value of an adr
property of an item with the type http://microformats.org/profile/hcard
, but within each such adr
property item there must only be one type
property per distinct
value.
post-office-box
(inside adr
)Gives the post office box component of the delivery address of the person or organization.
The value must be text.
Any number of properties with the name post-office-box
may be
present within the item that
forms the value of an
adr
property of an item with the type http://microformats.org/profile/hcard
.
extended-address
(inside adr
)Gives an additional component of the delivery address of the person or organization.
The value must be text.
Any number of properties with the name extended-address
may
be present within the item that
forms the value of an
adr
property of an item with the type http://microformats.org/profile/hcard
.
street-address
(inside adr
)Gives the street address component of the delivery address of the person or organization.
The value must be text.
Any number of properties with the name street-address
may be
present within the item that
forms the value of an
adr
property of an item with the type http://microformats.org/profile/hcard
.
locality
(inside adr
)Gives the locality component (e.g. city) of the delivery address of the person or organization.
The value must be text.
A single property with the name locality
may be present
within the item that forms the
value of an adr
property of an item with the type http://microformats.org/profile/hcard
.
region
(inside adr
)Gives the region component (e.g. state or province) of the delivery address of the person or organization.
The value must be text.
A single property with the name region
may be present within
the item that forms the value of an adr
property of an item with the type http://microformats.org/profile/hcard
.
postal-code
(inside adr
)Gives the postal code component of the delivery address of the person or organization.
The value must be text.
A single property with the name postal-code
may be present
within the item that forms the
value of an adr
property of an item with the type http://microformats.org/profile/hcard
.
country-name
(inside adr
)Gives the country name component of the delivery address of the person or organization.
The value must be text.
A single property with the name country-name
may be
present within the item that
forms the value of an
adr
property of an item with the type http://microformats.org/profile/hcard
.
label
Gives the formatted text corresponding to the delivery address of the person or organization.
The value must be
either text or an item with zero
or more type
properties
and exactly one value
property.
If no type
properties
are present within an item that
forms the value of a
label
property of an item with the type http://microformats.org/profile/hcard
, or if the value of such a label
property is text, then the
address type strings intl
, postal
, parcel
, and work
are implied.
Any number of properties with the name label
may be present within each
item with the type http://microformats.org/profile/hcard
.
type
(inside label
)Gives the type of delivery address.
The value must be text that, when compared in a case-sensitive manner, is equal to one of the address type strings.
Within each item with the
type http://microformats.org/profile/hcard
, there must be no more
than one label
property item with a type
property whose value is
pref
.
Any number of properties with the name type
may be present within the
item that forms the value of a label
property of an item with the type http://microformats.org/profile/hcard
, but within each such label
property item there must only be one type
property per distinct
value.
value
(inside label
)Gives the actual formatted text corresponding to the delivery address of the person or organization.
The value must be text.
Exactly one property with the name value
must be present within
the item that forms the value of a label
property of an item with the type http://microformats.org/profile/hcard
.
tel
Gives the telephone number of the person or organization.
The value must be
either text that can be interpreted as a telephone number as
defined in the CCITT specifications E.163 and X.121, or an item with zero or more type
properties and exactly one
value
property. [E163] [X121]
If no type
properties
are present within an item that
forms the value of a
tel
property of an item with the type http://microformats.org/profile/hcard
, or if the value of such a tel
property is text, then the telephone type string voice
is implied.
Any number of properties with the name tel
may be present within each
item with the type http://microformats.org/profile/hcard
.
type
(inside tel
)Gives the type of telephone number.
The value must be text that, when compared in a case-sensitive manner, is equal to one of the telephone type strings.
Within each item with the
type http://microformats.org/profile/hcard
, there must be no more
than one tel
property item with a type
property whose value is
pref
.
Any number of properties with the name type
may be present within the
item that forms the value of a tel
property of an item with the type http://microformats.org/profile/hcard
, but within each such tel
property item there must only be one type
property per distinct
value.
value
(inside tel
)Gives the actual telephone number of the person or organization.
The value must be text that can be interpreted as a telephone number as defined in the CCITT specifications E.163 and X.121. [E163] [X121]
Exactly one property with the name value
must be present within the
item that forms the value of a tel
property of an item with the type http://microformats.org/profile/hcard
.
email
Gives the e-mail address of the person or organization.
The value must be text.
Any number of properties with the name email
may be present within each
item with the type http://microformats.org/profile/hcard
.
impp
Gives a URL for instant messaging and presence protocol communications with the person or organization.
The value must be an absolute URL.
Any number of properties with the name impp
may be present within each
item with the type http://microformats.org/profile/hcard
.
lang
Gives a language understood by the person or organization.
The value must be a valid BCP 47 language tag. [BCP47].
Any number of properties with the name lang
may be present within each
item with the type http://microformats.org/profile/hcard
.
tz
Gives the time zone of the person or organization.
The value must be text and must match the following syntax:
Any number of properties with the name tz
may be present within each item with the type http://microformats.org/profile/hcard
.
geo
Gives the geographical position of the person or organization.
The value must be text and must match the following syntax:
The optional components marked with an asterisk (*) should be included, and should have six digits each.
The value specifies latitude and longitude, in that order (i.e., "LAT LON" ordering), in decimal degrees. The longitude represents the location east and west of the prime meridian as a positive or negative real number, respectively. The latitude represents the location north and south of the equator as a positive or negative real number, respectively.
Any number of properties with the name geo
may be present within each item with the type http://microformats.org/profile/hcard
.
title
Gives the job title, functional position or function of the person or organization.
The value must be text.
Any number of properties with the name title
may be present within each
item with the type http://microformats.org/profile/hcard
.
role
Gives the role, occupation, or business category of the person or organization.
The value must be text.
Any number of properties with the name role
may be present within each
item with the type http://microformats.org/profile/hcard
.
logo
Gives the logo of the person or organization.
The value must be an absolute URL.
Any number of properties with the name logo
may be present within each
item with the type http://microformats.org/profile/hcard
.
agent
Gives the contact information of another person who will act on behalf of the person or organization.
The value must be
either an item with the type
http://microformats.org/profile/hcard
, or an absolute
URL, or text.
Any number of properties with the name agent
may be present within each
item with the type http://microformats.org/profile/hcard
.
org
Gives the name and units of the organization.
The value must be
either text or an item with one
organization-name
property and zero or more organization-unit
properties.
Any number of properties with the name org
may be present within each item with the type http://microformats.org/profile/hcard
.
organization-name
(inside org
)Gives the name of the organization.
The value must be text.
Exactly one property with the name organization-name
must be present within the item
that forms the value
of an org
property of an item with the type http://microformats.org/profile/hcard
.
organization-unit
(inside org
)Gives the name of the organization unit.
The value must be text.
Any number of properties with the name organization-unit
may be present within the item
that forms the value
of the org
property of an item with the type http://microformats.org/profile/hcard
.
member
Gives a URL that represents a member of the group.
The value must be an absolute URL.
Any number of properties with the name member
may be present within each
item with the type http://microformats.org/profile/hcard
if
the item also has a property
with the name kind
whose value
is "group
".
related
Gives a relationship to another entity.
The value must an
item with one url
property and one rel
properties.
Any number of properties with the name orrelated
may be present within
each item with the type http://microformats.org/profile/hcard
.
url
(inside related
)Gives the URL for the related entity.
The value must be an absolute URL.
Exactly one property with the name url
must be present within the
item that forms the value of an related
property of an item with the type http://microformats.org/profile/hcard
.
rel
(inside related
)Gives the relationship between the entity and the related entity.
The value must be text that, when compared in a case-sensitive manner, is equal to one of the relationship strings.
Exactly one property with the name rel
must be present within the
item that forms the value of an related
property of an item with the type http://microformats.org/profile/hcard
.
categories
Gives the name of a category or tag that the person or organization could be classified as.
The value must be text.
Any number of properties with the name categories
may be present
within each item with the type
http://microformats.org/profile/hcard
.
note
Gives supplemental information or a comment about the person or organization.
The value must be text.
Any number of properties with the name note
may be present
within each item with the type
http://microformats.org/profile/hcard
.
rev
Gives the revision date and time of the contact information.
The value must be text that is a valid global date and time string.
The value distinguishes the current revision of the information for other renditions of the information.
Any number of properties with the name rev
may be present within each item with the type http://microformats.org/profile/hcard
.
sound
Gives a sound file relating to the person or organization.
The value must be an absolute URL.
Any number of properties with the name sound
may be present within each
item with the type http://microformats.org/profile/hcard
.
uid
Gives a globally unique identifier corresponding to the person or organization.
The value must be text.
A single property with the name uid
may be present within each item with the type http://microformats.org/profile/hcard
.
url
Gives a URL relating to the person or organization.
The value must be an absolute URL.
Any number of properties with the name url
may be present within each item with the type http://microformats.org/profile/hcard
.
The kind strings are:
individual
Indicates a single entity (e.g. a person).
group
Indicates multiple entities (e.g. a mailing list).
org
Indicates a single entity that is not a person (e.g. a company).
location
Indicates a geographical place (e.g. an office building).
The address type strings are:
home
Indicates a residential delivery address.
work
Indicates a delivery address for a place of work.
The telephone type strings are:
home
Indicates a residential number.
work
Indicates a telephone number for a place of work.
text
Indicates that the telephone number supports text messages (SMS).
voice
Indicates a voice telephone number.
fax
Indicates a facsimile telephone number.
cell
Indicates a cellular telephone number.
video
Indicates a video conferencing telephone number.
pager
Indicates a paging device telephone number.
textphone
Indicates a telecommunication device for people with hearing or speech difficulties.
The relationship strings are:
emergency
An emergency contact.
agent
Another entity that acts on behalf of this entity.
Has the meaning defined in XFN. [XFN]
Given a list of nodes nodes in a
Document
, a user agent must run the following algorithm
to extract any vCard data
represented by those nodes (only the first vCard is
returned):
If none of the nodes in nodes are items with the item type http://microformats.org/profile/hcard
, then
there is no vCard. Abort the algorithm, returning nothing.
Let node be the first node in nodes that is an item with the item type http://microformats.org/profile/hcard
.
Let output be an empty string.
Add a vCard line with the type "BEGIN
" and the value "VCARD
"
to output.
Add a vCard line with the type "PROFILE
" and the value "VCARD
" to output.
Add a vCard line with the type "VERSION
" and the value "4.0
"
to output.
Add a vCard line with the type "SOURCE
" and the result of escaping the vCard
text string that is the document's address as
the value to output.
If the title
element is not null,
add a vCard line with the type "NAME
" and with the result of escaping the
vCard text string obtained from the textContent
of the title
element as the value to output.
Let sex be the empty string.
Let gender-identity be the empty string.
For each element element that is a property of the item node: for each name name in element's property names, run the following substeps:
Let parameters be an empty set of name-value pairs.
Run the appropriate set of substeps from the following list. The steps will set a variable value, which is used in the next step.
n
Let value be the empty string.
Append to value the result of
collecting the first vCard subproperty named
family-name
in
subitem.
Append to value the result of
collecting the first vCard subproperty named
given-name
in subitem.
Append to value the result of
collecting the first vCard subproperty named
additional-name
in
subitem.
Append to value the result of
collecting the first vCard subproperty named
honorific-prefix
in subitem.
Append to value the result of
collecting the first vCard subproperty named
honorific-suffix
in subitem.
adr
Let value be the empty string.
Append to value the result of
collecting vCard subproperties named post-office-box
in subitem.
Append to value the result of
collecting vCard subproperties named extended-address
in subitem.
Append to value the result of
collecting vCard subproperties named street-address
in
subitem.
Append to value the result of
collecting the first vCard subproperty named
locality
in subitem.
Append to value the result of
collecting the first vCard subproperty named
region
in subitem.
Append to value the result of
collecting the first vCard subproperty named
postal-code
in
subitem.
Append to value the result of
collecting the first vCard subproperty named
country-name
in subitem.
If there is a property named type
in subitem, and the first such property has a
value that is not
an item and whose value
consists only of alphanumeric ASCII characters,
then add a parameter named "TYPE
" whose
value is the value of that property
to parameters.
org
Let value be the empty string.
Append to value the result of
collecting the first vCard subproperty named
organization-name
in subitem.
For each property named organization-unit
in subitem, run the following steps:
If the value of the property is an item, then skip this property.
Append a U+003B SEMICOLON character (;) to value.
Append the result of escaping the vCard text string given by the value of the property to value.
http://microformats.org/profile/hcard
and name is related
Let value be the empty string.
If there is a property named url
in subitem, and its element is a URL property element, then append
the result of escaping the vCard text string
given by the value of the first such
property to value, and add a parameter
with the name "VALUE
" and the value
"URI
" to parameters.
If there is a property named rel
in subitem, and the first such property has a
value that is not
an item and whose value
consists only of alphanumeric ASCII characters,
then add a parameter named "RELATION
"
whose value is the value of that property
to parameters.
Let value be the result of
collecting the first vCard subproperty named
value
in subitem.
If there is a property named type
in subitem, and the
first such property has a value that is not an
item and whose value
consists only of alphanumeric ASCII characters,
then add a parameter named "TYPE
" whose
value is the value of that property
to parameters.
sex
If this is the first such property to be found, set sex to the property's value.
gender-identity
If this is the first such property to be found, set gender-identity to the property's value.
Let value be the property's value.
If element is one of the URL
property elements, add a parameter with the name "VALUE
" and the value "URI
" to parameters.
Otherwise, if name is bday
or anniversary
and the value is a valid date string, add
a parameter with the name "VALUE
" and
the value "DATE
" to parameters.
Otherwise, if name is rev
and the value is a valid global date and time
string, add a parameter with the name "VALUE
" and the value "DATE-TIME
" to parameters.
Prefix every U+005C REVERSE SOLIDUS character (\) in value with another U+005C REVERSE SOLIDUS character (\).
Prefix every U+002C COMMA character (,) in value with a U+005C REVERSE SOLIDUS character (\).
Unless name is geo
, prefix every U+003B SEMICOLON
character (;) in value with a U+005C
REVERSE SOLIDUS character (\).
Replace every U+000D CARRIAGE RETURN U+000A LINE FEED character pair (CRLF) in value with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL LETTER N character (n).
Replace every remaining U+000D CARRIAGE RETURN (CR) or U+000A LINE FEED (LF) character in value with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL LETTER N character (n).
Add a vCard line with the type name, the parameters parameters, and the value value to output.
If either of sex or gender-identity have a value that is not the empty
string, add a vCard line with the type "GENDER
" and the value consisting of the
concatenation of sex, a U+003B SEMICOLON
character (;), and gender-identity to output.
Add a vCard line with the type "END
" and the value "VCARD
"
to output.
When the above algorithm says that the user agent is to add a vCard line consisting of a type type, optionally some parameters, and a value value to a string output, it must run the following steps:
Let line be an empty string.
Append type, converted to ASCII uppercase, to line.
If there are any parameters, then for each parameter, in the order that they were added, run these substeps:
Append a U+003B SEMICOLON character (;) to line.
Append the parameter's name to line.
Append a U+003D EQUALS SIGN character (=) to line.
Append the parameter's value to line.
Append a U+003A COLON character (:) to line.
Append value to line.
Let maximum length be 75.
If and while line is longer than maximum length Unicode code points long, run the following substeps:
Append the first maximum length Unicode code points of line to output.
Remove the first maximum length Unicode code points from line.
Append a U+000D CARRIAGE RETURN character (CR) to output.
Append a U+000A LINE FEED character (LF) to output.
Append a U+0020 SPACE character to output.
Let maximum length be 74.
Append (what remains of) line to output.
Append a U+000D CARRIAGE RETURN character (CR) to output.
Append a U+000A LINE FEED character (LF) to output.
When the steps above require the user agent to obtain the result of collecting vCard subproperties named subname in subitem, the user agent must run the following steps:
Let value be the empty string.
For each property named subname in the item subitem, run the following substeps:
If the value of the property is itself an item, then skip this property.
If this is not the first property named subname in subitem (ignoring any that were skipped by the previous step), then append a U+002C COMMA character (,) to value.
Append the result of escaping the vCard text string given by the value of the property to value.
Return value.
When the steps above require the user agent to obtain the result of collecting the first vCard subproperty named subname in subitem, the user agent must run the following steps:
If there are no properties named subname in subitem, then abort these substeps, returning the empty string.
If the value of the first property named subname in subitem is an item, then abort these substeps, returning the empty string.
Return the result of escaping the vCard text string given by the value of the first property named subname in subitem.
When the above algorithms say the user agent is to escape the vCard text string value, the user agent must use the following steps:
Prefix every U+005C REVERSE SOLIDUS character (\) in value with another U+005C REVERSE SOLIDUS character (\).
Prefix every U+002C COMMA character (,) in value with a U+005C REVERSE SOLIDUS character (\).
Prefix every U+003B SEMICOLON character (;) in value with a U+005C REVERSE SOLIDUS character (\).
Replace every U+000D CARRIAGE RETURN U+000A LINE FEED character pair (CRLF) in value with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL LETTER N character (n).
Replace every remaining U+000D CARRIAGE RETURN (CR) or U+000A LINE FEED (LF) character in value with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL LETTER N character (n).
Return the mutated value.
This algorithm can generate invalid vCard output, if
the input does not conform to the rules described for the http://microformats.org/profile/hcard
item type and defined property names.
This section is non-normative.
Here is a long example vCard for a fictional character called "Jack Bauer":
<section id="jack" itemscope itemtype="http://microformats.org/profile/hcard"> <h1 itemprop="fn"> <span itemprop="n" itemscope> <span itemprop="given-name">Jack</span> <span itemprop="family-name">Bauer</span> </span> </h1> <img itemprop="photo" alt="" src="jack-bauer.jpg"> <p itemprop="org" itemscope> <span itemprop="organization-name">Counter-Terrorist Unit</span> (<span itemprop="organization-unit">Los Angeles Division</span>) </p> <p> <span itemprop="adr" itemscope> <span itemprop="street-address">10201 W. Pico Blvd.</span><br> <span itemprop="locality">Los Angeles</span>, <span itemprop="region">CA</span> <span itemprop="postal-code">90064</span><br> <span itemprop="country-name">United States</span><br> </span> <span itemprop="geo">34.052339;-118.410623</span> </p> <h2>Assorted Contact Methods</h2> <ul> <li itemprop="tel" itemscope> <span itemprop="value">+1 (310) 597 3781</span> <span itemprop="type">work</span> <meta itemprop="type" content="voice"> </li> <li><a itemprop="url" href="http://en.wikipedia.org/wiki/Jack_Bauer">I'm on Wikipedia</a> so you can leave a message on my user talk page.</li> <li><a itemprop="url" href="http://www.jackbauerfacts.com/">Jack Bauer Facts</a></li> <li itemprop="email"><a href="mailto:j.bauer@la.ctu.gov.invalid">j.bauer@la.ctu.gov.invalid</a></li> <li itemprop="tel" itemscope> <span itemprop="value">+1 (310) 555 3781</span> <span> <meta itemprop="type" content="cell">mobile phone</span> </li> </ul> <ins datetime="2008-07-20 21:00:00+01:00"> <meta itemprop="rev" content="2008-07-20 21:00:00+01:00"> <p itemprop="tel" itemscope><strong>Update!</strong> My new <span itemprop="type">home</span> phone number is <span itemprop="value">01632 960 123</span>.</p> </ins> </section>
The odd line wrapping is needed because newlines are meaningful in microdata: newlines would be preserved in a conversion to, for example, the vCard format.
This example shows a site's contact details (using the
address
element) containing an address with two street
components:
<address itemscope itemtype="http://microformats.org/profile/hcard"> <strong itemprop="fn"><span itemprop="n" itemscope><span itemprop="given-name">Alfred</span> <span itemprop="family-name">Person</span></span></strong> <br> <span itemprop="adr" itemscope> <span itemprop="street-address">1600 Amphitheatre Parkway</span> <br> <span itemprop="street-address">Building 43, Second Floor</span> <br> <span itemprop="locality">Mountain View</span>, <span itemprop="region">CA</span> <span itemprop="postal-code">94043</span> </span> </address>
The vCard vocabulary can be used to just mark up people's names:
<span itemscope itemtype="http://microformats.org/profile/hcard" ><span itemprop=fn><span itemprop="n" itemscope><span itemprop="given-name" >George</span> <span itemprop="family-name">Washington</span></span ></span></span>
This creates a single item with a two name-value pairs, one with the name "fn" and the value "George Washington", and the other with the name "n" and a second item as its value, the second item having the two name-value pairs "given-name" and "family-name" with the values "George" and "Washington" respectively. This is defined to map to the following vCard:
BEGIN:VCARD PROFILE:VCARD VERSION:4.0 SOURCE:document's address FN:George Washington N:Washington;George;;; END:VCARD
An item with the item type http://microformats.org/profile/hcalendar#vevent
represents an event.
This vocabulary does not support global identifiers for items.
The following are the type's defined property names. They are based on the vocabulary defined in the iCalendar specification, where more information on how to interpret the values can be found. [RFC2445]
Only the parts of the iCalendar vocabulary relating to events are used here; this vocabulary cannot express a complete iCalendar instance.
attach
Gives the address of an associated document for the event.
The value must be an absolute URL.
Any number of properties with the name attach
may be present within each
item with the type http://microformats.org/profile/hcalendar#vevent
.
categories
Gives the name of a category or tag that the event could be classified as.
The value must be text.
Any number of properties with the name categories
may be present
within each item with the type
http://microformats.org/profile/hcalendar#vevent
.
class
Gives the access classification of the information regarding the event.
The value must be text with one of the following values:
public
private
confidential
This is merely advisory and cannot be considered a confidentiality measure.
A single property with the name class
may be present within each
item with the type http://microformats.org/profile/hcalendar#vevent
.
comment
Gives a comment regarding the event.
The value must be text.
Any number of properties with the name comment
may be present within each
item with the type http://microformats.org/profile/hcalendar#vevent
.
description
Gives a detailed description of the event.
The value must be text.
A single property with the name description
may be present
within each item with the type
http://microformats.org/profile/hcalendar#vevent
.
geo
Gives the geographical position of the event.
The value must be text and must match the following syntax:
The optional components marked with an asterisk (*) should be included, and should have six digits each.
The value specifies latitude and longitude, in that order (i.e., "LAT LON" ordering), in decimal degrees. The longitude represents the location east and west of the prime meridian as a positive or negative real number, respectively. The latitude represents the location north and south of the equator as a positive or negative real number, respectively.
A single property with the name geo
may be present within each item with the type http://microformats.org/profile/hcalendar#vevent
.
location
Gives the location of the event.
The value must be text.
A single property with the name location
may be present within
each item with the type http://microformats.org/profile/hcalendar#vevent
.
resources
Gives a resource that will be needed for the event.
The value must be text.
Any number of properties with the name resources
may be present within
each item with the type http://microformats.org/profile/hcalendar#vevent
.
status
Gives the confirmation status of the event.
The value must be text with one of the following values:
tentative
confirmed
cancelled
A single property with the name status
may be present within each
item with the type http://microformats.org/profile/hcalendar#vevent
.
summary
Gives a short summary of the event.
The value must be text.
User agents should replace U+000A LINE FEED (LF) characters in the value by U+0020 SPACE characters when using the value.
A single property with the name summary
may be present within
each item with the type http://microformats.org/profile/hcalendar#vevent
.
dtend
Gives the date and time by which the event ends.
If the property with the name dtend
is present within an item with the type http://microformats.org/profile/hcalendar#vevent
that has a property with the name dtstart
whose value is a
valid date string, then the value of the property with
the name dtend
must be text
that is a valid date string also. Otherwise, the
value of the property
must be text that is a valid global date and time
string.
In either case, the value be later in time than
the value of the dtstart
property of the same item.
The time given by the dtend
property is not
inclusive. For day-long events, therefore, the dtend
property's value will be the day
after the end of the event.
A single property with the name dtend
may be present within each
item with the type http://microformats.org/profile/hcalendar#vevent
,
so long as that http://microformats.org/profile/hcalendar#vevent
does not have a property with the name duration
.
dtstart
Gives the date and time at which the event starts.
The value must be text that is either a valid date string or a valid global date and time string.
Exactly one property with the name dtstart
must be present within
each item with the type http://microformats.org/profile/hcalendar#vevent
.
duration
Gives the duration of the event.
The value must be text that is a valid vevent duration string.
The duration represented is the sum of all the durations represented by integers in the value.
A single property with the name duration
may be present within
each item with the type http://microformats.org/profile/hcalendar#vevent
,
so long as that http://microformats.org/profile/hcalendar#vevent
does not have a property with the name dtend
.
transp
Gives whether the event is to be considered as consuming time on a calendar, for the purpose of free-busy time searches.
The value must be text with one of the following values:
opaque
transparent
A single property with the name transp
may be present within each
item with the type http://microformats.org/profile/hcalendar#vevent
.
contact
Gives the contact information for the event.
The value must be text.
Any number of properties with the name contact
may be present within
each item with the type http://microformats.org/profile/hcalendar#vevent
.
url
Gives a URL for the event.
The value must be an absolute URL.
A single property with the name url
may be present within each
item with the type http://microformats.org/profile/hcalendar#vevent
.
uid
Gives a globally unique identifier corresponding to the event.
The value must be text.
A single property with the name uid
may be present within each item with the type http://microformats.org/profile/hcalendar#vevent
.
exdate
Gives a date and time at which the event does not occur despite the recurrence rules.
The value must be text that is either a valid date string or a valid global date and time string.
Any number of properties with the name exdate
may be present within
each item with the type http://microformats.org/profile/hcalendar#vevent
.
exrule
Gives a rule for finding dates and times at which the event does not occur despite the recurrence rules.
The value must be text that matches the RECUR value type defined in the iCalendar specification. [RFC2445]
Any number of properties with the name exrule
may be present within
each item with the type http://microformats.org/profile/hcalendar#vevent
.
rdate
Gives a date and time at which the event recurs.
The value must be text that is one of the following:
Any number of properties with the name rdate
may be present within
each item with the type http://microformats.org/profile/hcalendar#vevent
.
rrule
Gives a rule for finding dates and times at which the event occurs.
The value must be text that matches the RECUR value type defined in the iCalendar specification. [RFC2445]
Any number of properties with the name rrule
may be present within
each item with the type http://microformats.org/profile/hcalendar#vevent
.
created
Gives the date and time at which the event information was first created in a calendaring system.
The value must be text that is a valid global date and time string.
A single property with the name created
may be present within
each item with the type http://microformats.org/profile/hcalendar#vevent
.
last-modified
Gives the date and time at which the event information was last modified in a calendaring system.
The value must be text that is a valid global date and time string.
A single property with the name last-modified
may be present within
each item with the type http://microformats.org/profile/hcalendar#vevent
.
sequence
Gives a revision number for the event information.
The value must be text that is a valid non-negative integer.
A single property with the name sequence
may be present within
each item with the type http://microformats.org/profile/hcalendar#vevent
.
A string is a valid vevent duration string if it matches the following pattern:
Given a list of nodes nodes in a
Document
, a user agent must run the following algorithm
to extract any vEvent data
represented by those nodes:
If none of the nodes in nodes are items with the type http://microformats.org/profile/hcalendar#vevent
,
then there is no vEvent data. Abort the algorithm, returning
nothing.
Let output be an empty string.
Add an iCalendar line with the type "BEGIN
" and the value "VCALENDAR
" to output.
Add an iCalendar line with the type "PRODID
" and the value equal to a
user-agent-specific string representing the user agent to output.
Add an iCalendar line with the type "VERSION
" and the value "2.0
"
to output.
For each node node in nodes that is an item with the type http://microformats.org/profile/hcalendar#vevent
,
run the following steps:
Add an iCalendar line with the type "BEGIN
" and the value "VEVENT
" to output.
Add an iCalendar line with the type "DTSTAMP
" and a value consisting of an iCalendar
DATE-TIME string representing the current date and time, with the
annotation "VALUE=DATE-TIME
", to output. [RFC2445]
For each element element that is a property of the item node: for each name name in element's property names, run the appropriate set of substeps from the following list:
Skip the property.
dtend
dtstart
exdate
rdate
created
last-modified
Let value be the result of stripping all U+002D HYPHEN-MINUS (-) and U+003A COLON (:) characters from the property's value.
If the property's value is a valid
date string then add an iCalendar line
with the type name and the value value to output, with the
annotation "VALUE=DATE
".
Otherwise, if the property's value is a valid
global date and time string then add an iCalendar
line with the type name and the
value value to output,
with the annotation "VALUE=DATE-TIME
".
Otherwise skip the property.
Add an iCalendar line with the type name and the property's value to output.
Add an iCalendar line with the type "END
" and the value "VEVENT
"
to output.
Add an iCalendar line with the type "END
" and the value "VCALENDAR
" to output.
When the above algorithm says that the user agent is to add an iCalendar line consisting of a type type, a value value, and optionally an annotation, to a string output, it must run the following steps:
Let line be an empty string.
Append type, converted to ASCII uppercase, to line.
If there is an annotation:
Append a U+003B SEMICOLON character (;) to line.
Append the annotation to line.
Append a U+003A COLON character (:) to line.
Prefix every U+005C REVERSE SOLIDUS character (\) in value with another U+005C REVERSE SOLIDUS character (\).
Prefix every U+002C COMMA character (,) in value with a U+005C REVERSE SOLIDUS character (\).
Prefix every U+003B SEMICOLON character (;) in value with a U+005C REVERSE SOLIDUS character (\).
Replace every U+000D CARRIAGE RETURN U+000A LINE FEED character pair (CRLF) in value with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL LETTER N character (n).
Replace every remaining U+000D CARRIAGE RETURN (CR) or U+000A LINE FEED (LF) character in value with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL LETTER N character (n).
Append value to line.
Let maximum length be 75.
If and while line is longer than maximum length Unicode code points long, run the following substeps:
Append the first maximum length Unicode code points of line to output.
Remove the first maximum length Unicode code points from line.
Append a U+000D CARRIAGE RETURN character (CR) to output.
Append a U+000A LINE FEED character (LF) to output.
Append a U+0020 SPACE character to output.
Let maximum length be 74.
Append (what remains of) line to output.
Append a U+000D CARRIAGE RETURN character (CR) to output.
Append a U+000A LINE FEED character (LF) to output.
This algorithm can generate invalid iCalendar
output, if the input does not conform to the rules described for the
http://microformats.org/profile/hcalendar#vevent
item type and defined property names.
This section is non-normative.
Here is an example of a page that uses the vEvent vocabulary to mark up an event:
<body itemscope itemtype="http://microformats.org/profile/hcalendar#vevent"> ... <h1 itemprop="summary">Bluesday Tuesday: Money Road</h1> ... <time itemprop="dtstart" datetime="2009-05-05T19:00:00Z">May 5th @ 7pm</time> (until <time itemprop="dtend" datetime="2009-05-05T21:00:00Z">9pm</time>) ... <a href="http://livebrum.co.uk/2009/05/05/bluesday-tuesday-money-road" rel="bookmark" itemprop="url">Link to this page</a> ... <p>Location: <span itemprop="location">The RoadHouse</span></p> ... <p><input type=button value="Add to Calendar" onclick="location = getCalendar(this)"></p> ... <meta itemprop="description" content="via livebrum.co.uk"> </body>
The "getCalendar()
" method could look like
this:
function getCalendar(node) { // This function assumes the content is valid. // It is not a compliant implementation of the algorithm for extracting vEvent data. while (node && (!node.itemScope || !node.itemType.contains('http://microformats.org/profile/hcalendar#vevent'))) node = node.parentNode; if (!node) { alert('No event data found.'); return; } var stamp = new Date(); var stampString = '' + stamp.getUTCFullYear() + (stamp.getUTCMonth() + 1) + stamp.getUTCDate() + 'T' + stamp.getUTCHours() + stamp.getUTCMinutes() + stamp.getUTCSeconds() + 'Z'; var calendar = 'BEGIN:VCALENDAR\r\nPRODID:HTML\r\nVERSION:2.0\r\nBEGIN:VEVENT\r\nDTSTAMP:' + stampString + '\r\n'; for (var propIndex = 0; propIndex < node.properties.length; propIndex += 1) { var prop = node.properties[propIndex]; var value = prop.itemValue; var parameters = ''; if (prop.localName == 'time') { value = value.replace(/[:-]/g, ''); if (value.match(/T/)) parameters = ';VALUE=DATE'; else parameters = ';VALUE=DATE-TIME'; } else { value = value.replace(/\\/g, '\\n'); value = value.replace(/;/g, '\\;'); value = value.replace(/,/g, '\\,'); value = value.replace(/\n/g, '\\n'); } for (var nameIndex = 0; nameIndex < prop.itemProp.length; nameIndex += 1) { var name = prop.itemProp[nameIndex]; if (!name.match(/:/) && !name.match(/\./)) calendar += name.toUpperCase() + parameters + ':' + value + '\r\n'; } } calendar += 'END:VEVENT\r\nEND:VCALENDAR\r\n'; return 'data:text/calendar;component=vevent,' + encodeURI(calendar); }
The same page could offer some markup, such as the following, for copy-and-pasting into blogs:
<div itemscope itemtype="http://microformats.org/profile/hcalendar#vevent"> <p>I'm going to <strong itemprop="summary">Bluesday Tuesday: Money Road</strong>, <time itemprop="dtstart" datetime="2009-05-05T19:00:00Z">May 5th at 7pm</time> to <time itemprop="dtend" datetime="2009-05-05T21:00:00Z">9pm</time>, at <span itemprop="location">The RoadHouse</span>!</p> <p><a href="http://livebrum.co.uk/2009/05/05/bluesday-tuesday-money-road" itemprop="url">See this event on livebrum.co.uk</a>.</p> <meta itemprop="description" content="via livebrum.co.uk"> </div>
An item with the item type http://n.whatwg.org/work
represents a work (e.g. an article, an image, a video, a song,
etc). This type is primarily intended to allow authors to include
licensing information for works.
The following are the type's defined property names.
work
Identifies the work being described.
The value must be an absolute URL.
Exactly one property with the name work
must be present within each item with the type http://n.whatwg.org/work
.
title
Gives the name of the work.
A single property with the name title
may be present within each
item with the type http://n.whatwg.org/work
.
author
Gives the name or contact information of one of the authors or creators of the work.
The value must be
either an item with the type
http://microformats.org/profile/hcard
, or
text.
Any number of properties with the name author
may be present within each
item with the type http://n.whatwg.org/work
.
license
Identifies one of the licenses under which the work is available.
The value must be an absolute URL.
Any number of properties with the name license
may be present within each
item with the type http://n.whatwg.org/work
.
This section is non-normative.
This example shows an embedded image entitled My Pond, licensed under the Creative Commons Attribution-Share Alike 3.0 United States License and the MIT license simultaneously.
<figure itemscope itemtype="http://n.whatwg.org/work"> <img itemprop="work" src="mypond.jpeg"> <figcaption> <p><cite itemprop="title">My Pond</cite></p> <p><small>Licensed under the <a itemprop="license" href="http://creativecommons.org/licenses/by-sa/3.0/us/">Creative Commons Attribution-Share Alike 3.0 United States License</a> and the <a itemprop="license" href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</small> </figcaption> </figure>
Given a list of nodes nodes in a
Document
, a user agent must run the following algorithm
to extract the microdata from those
nodes into a JSON form:
Let result be an empty object.
Let items be an empty array.
For each node in nodes, check if the element is a top-level microdata item, and if it is then get the object for that element and add it to items.
Add an entry to result called "items
" whose value is the array items.
Return the result of serializing result
to JSON in the shortest possible way (meaning no whitespace between
tokens, no unnecessary zero digits in numbers, and only using
Unicode escapes in strings for characters that do not have a
dedicated escape sequence), and with a lowercase "e
" used, when appropriate, in the representation of
any numbers. [JSON]
This algorithm returns an object with a single property that is an array, instead of just returning an array, so that it is possible to extend the algorithm in the future if necessary.
When the user agent is to get the object for an item item, optionally with a list of elements memory, it must run the following substeps:
Let result be an empty object.
Add item to memory.
If the item has any item
types, add an entry to result called
"type
" whose value is an array listing the
item types of item, in the order
they were specified on the itemtype
attribute.
If the item has a global
identifier, add an entry to result
called "id
" whose value is the global
identifier of item.
Let properties be an empty object.
For each element element that has one or more property names and is one of the properties of the item item, in the order those elements are given by the algorithm that returns the properties of an item, run the following substeps:
Let value be the property value of element.
If value is an item, then: If value is in memory, then let
value be the string "ERROR
". Otherwise, get the object
for value, passing a copy of memory, and then replace value
with the object returned from those steps.
For each name name in element's property names, run the following substeps:
If there is no entry named name in properties, then add an entry named name to properties whose value is an empty array.
Append value to the entry named name in properties.
Add an entry to result called "properties
" whose value is the object properties.
Return result.