iframe
elementsrc
srcdoc
name
sandbox
seamless
width
height
interface HTMLIFrameElement : HTMLElement { attribute DOMString src; attribute DOMString srcdoc; attribute DOMString name; [PutForwards=value] readonly attribute DOMSettableTokenList sandbox; attribute boolean seamless; attribute DOMString width; attribute DOMString height; readonly attribute Document contentDocument; readonly attribute WindowProxy contentWindow; };
The iframe
element represents a
nested browsing context.
The src
attribute
gives the address of a page that the nested browsing
context is to contain. The attribute, if present, must be a
valid non-empty URL potentially surrounded by
spaces.
The srcdoc
attribute gives the content of the page that the nested
browsing context is to contain. The value of the attribute is
the source of an iframe
srcdoc
document.
For iframe
elements in HTML documents,
the attribute, if present, must have a value using the HTML
syntax that consists of the following syntactic components,
in the given order:
html
element.For iframe
elements in XML documents,
the attribute, if present, must have a value that matches the
production labeled document
in the XML
specification. [XML]
If the src
attribute and the
srcdoc
attribute are both
specified together, the srcdoc
attribute takes priority. This allows authors to provide a fallback
URL for legacy user agents that do not support the
srcdoc
attribute.
When an iframe
element is first inserted into a document, the
user agent must create a nested browsing context, and
then process the iframe
attributes for the
first time.
Whenever an iframe
element with a nested
browsing context has its srcdoc
attribute set, changed, or
removed, the user agent must process the iframe
attributes.
Similarly, whenever an iframe
element with a
nested browsing context but with no srcdoc
attribute specified has its
src
attribute set, changed, or
removed, the user agent must process the iframe
attributes.
When the user agent is to process the iframe
attributes, it must run the first appropriate steps from the
following list:
srcdoc
attribute
is specifiedNavigate the element's
browsing context to a resource whose
Content-Type is text/html
, whose
URL is about:srcdoc
, and whose data
consists of the value of the attribute. The resulting
Document
must be considered an
iframe
srcdoc
document.
src
attribute is specified but the srcdoc
attribute is notIf the value of the src
attribute is the empty string,
jump to the empty step below.
Resolve the value of
the src
attribute, relative
to the iframe
element.
If that is not successful, then jump to the empty step below.
If the resulting absolute URL is an
ASCII case-insensitive match for the string
"about:blank
", and the user agent is processing this
iframe
's attributes for the first time, then jump to
the empty step below. (In cases other than the
first time, about:blank
is loaded
normally.)
Navigate the element's browsing context to the resulting absolute URL.
Empty: When the steps above require the user agent to
jump to the empty step, if the user agent is
processing this iframe
's attributes for the first
time, then the user agent must queue a task to
fire a simple event named load
at the iframe
element. (After jumping to this step, the above steps are not
resumed.)
Queue a task to fire a simple event
named load
at the
iframe
element.
Any navigation required of the user
agent in the process the iframe
attributes
algorithm must be completed with the iframe
element's
document's browsing context as the source
browsing context.
Furthermore, if the browsing context's session
history contained only one Document
when the
process the iframe
attributes algorithm
was invoked, and that was the about:blank
Document
created when the browsing context
was created, then any navigation
required of the user agent in that algorithm must be completed with
replacement enabled.
If, when the element is created, the srcdoc
attribute is not set, and
the src
attribute is either
also not set or set but its value cannot be resolved, the browsing context will remain at the
initial about:blank
page.
If the user navigates
away from this page, the iframe
's corresponding
WindowProxy
object will proxy new Window
objects for new Document
objects, but the src
attribute will not change.
Removing
an iframe
from a Document
does not cause
its browsing context to be discarded. Indeed, an
iframe
's browsing context can survive its
original parent Document
if its iframe
is
moved to another Document
.
On the other hand, if an iframe
is removed from a
Document
and is then subsequently garbage collected,
this will likely mean (in the absence of other references) that the
child browsing context's WindowProxy
object will become eligble for garbage collection, which will then
lead to that browsing context being discarded, which will then
lead to its Document
being discarded also. This happens without notice to any
scripts running in that Document
; for example, no
unload
events are fired (the
"unload a document" steps are not run).
Here a blog uses the srcdoc
attribute in conjunction
with the sandbox
and seamless
attributes described
below to provide users of user agents that support this feature
with an extra layer of protection from script injection in the blog
post comments:
<article> <h1>I got my own magazine!</h1> <p>After much effort, I've finally found a publisher, and so now I have my own magazine! Isn't that awesome?! The first issue will come out in September, and we have articles about getting food, and about getting in boxes, it's going to be great!</p> <footer> <p>Written by <a href="/users/cap">cap</a>. <time pubdate>2009-08-21T23:32Z</time></p> </footer> <article> <footer> At <time pubdate>2009-08-21T23:35Z</time>, <a href="/users/ch">ch</a> writes: </footer> <iframe seamless sandbox srcdoc="<p>did you get a cover picture yet?"></iframe> </article> <article> <footer> At <time pubdate>2009-08-21T23:44Z</time>, <a href="/users/cap">cap</a> writes: </footer> <iframe seamless sandbox srcdoc="<p>Yeah, you can see it <a href="/gallery?mode=cover&amp;page=1">in my gallery</a>."></iframe> </article> <article> <footer> At <time pubdate>2009-08-21T23:58Z</time>, <a href="/users/ch">ch</a> writes: </footer> <iframe seamless sandbox srcdoc="<p>hey that's earl's table. <p>you should get earl&amp;me on the next cover."></iframe> </article>
Notice the way that quotes have to be escaped (otherwise the
sandbox
attribute would
end prematurely), and the way raw ampersands (e.g. in URLs or in
prose) mentioned in the sandboxed content have to be
doubly escaped — once so that the ampersand is
preserved when originally parsing the sandbox
attribute, and once more
to prevent the ampersand from being misinterpreted when parsing the
sandboxed content.
In the HTML syntax, authors need only
remember to use U+0022 QUOTATION MARK characters (") to wrap the
attribute contents and then to escape all U+0022 QUOTATION MARK (")
and U+0026 AMPERSAND (&) characters, and to specify the sandbox
attribute, to ensure safe
embedding of content.
Due to restrictions of the XML syntax, in XML the U+003C LESS-THAN SIGN character (<) needs to be escaped as well. In order to prevent attribute-value normalization, some of XML's whitespace characters — specifically U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF), and U+000D CARRIAGE RETURN (CR) — also need to be escaped. [XML]
The name
attribute, if present, must be a valid browsing context
name. The given value is used to name the nested
browsing context. When the browsing
context is created, if the attribute is present, the browsing
context name must be set to the value of this attribute;
otherwise, the browsing context name must be set to the
empty string.
Whenever the name
attribute
is set, the nested browsing context's name must be changed to the new
value. If the attribute is removed, the browsing context
name must be set to the empty string.
When content loads in an iframe
, after any load
events are fired within the content
itself, the user agent must queue a task to fire
a simple event named load
at
the iframe
element. When content whose URL
has the same origin as the iframe
element's Document
fails to load (e.g. due to a DNS
error, network error, or if the server returned a 4xx or 5xx status
code or
equivalent), then the user agent must queue a
task to fire a simple event named error
at the element instead. (This event
does not fire for parse errors,
script errors, or any errors for cross-origin resources.)
The task source for these tasks is the DOM manipulation task source.
A load
event is also
fired at the iframe
element when it is created if no
other data is loaded in it.
When there is an active parser in the
iframe
, and when anything in the iframe
is
delaying the load event of
the iframe
's browsing context's
active document, the iframe
must
delay the load event of its document.
If, during the handling of the load
event, the browsing
context in the iframe
is again navigated, that will further delay the
load event.
The sandbox
attribute, when specified, enables a set of extra restrictions on
any content hosted by the iframe
. Its value must be an
unordered set of unique space-separated tokens that are
ASCII case-insensitive. The allowed values are allow-same-origin
,
allow-top-navigation
,
allow-forms
,
and allow-scripts
. When
the attribute is set, the content is treated as being from a unique
origin, forms and scripts are disabled, links are
prevented from targeting other browsing contexts, and plugins are disabled. The
allow-same-origin
keyword allows the content to be treated as being from the same
origin instead of forcing it into a unique origin, the allow-top-navigation
keyword allows the content to navigate its
top-level browsing context, and the allow-forms
and allow-scripts
keywords re-enable forms and scripts respectively (though scripts
are still prevented from creating popups).
Setting both the allow-scripts
and
allow-same-origin
keywords together when the embedded page has the same
origin as the page containing the iframe
allows
the embedded page to simply remove the sandbox
attribute.
Sandboxing hostile content is of minimal help if
an attacker can convince the user to just visit the hostile content
directly, rather than in the iframe
. To limit the
damage that can be caused by hostile HTML content, it should be
served using the text/html-sandboxed
MIME type.
While the sandbox
attribute is specified, the iframe
element's
nested browsing context must have the flags given in
the following list set. In addition, any browsing contexts nested within an
iframe
, either directly or indirectly, must have all
the flags set on them as were set on the iframe
's
Document
's browsing context when the
iframe
's Document
was created.
This flag prevents content from navigating browsing contexts other than the sandboxed browsing context itself (or browsing contexts further nested inside it), and the top-level browsing context (which is protected by the sandboxed top-level navigation browsing context flag defined next).
This flag also prevents content
from creating new auxiliary browsing contexts, e.g. using the
target
attribute or the
window.open()
method.
sandbox
attribute's value, when
split on spaces, is
found to have the allow-top-navigation
keyword setThis flag prevents content from navigating their top-level browsing context.
When the allow-top-navigation
is set, content can navigate its top-level browsing
context, but other browsing
contexts are still protected by the sandboxed
navigation browsing context flag defined above.
This flag prevents content from instantiating plugins, whether using the embed
element, the object
element,
the applet
element, or through navigation of a nested
browsing context.
This flag prevents content from using the seamless
attribute on
descendant iframe
elements.
This prevents a page inserted using the allow-same-origin
keyword from using a CSS-selector-based method of probing the DOM
of other pages on the same site (in particular, pages that contain
user-sensitive information).
sandbox
attribute's
value, when split on
spaces, is found to have the allow-same-origin
keyword setThis flag forces content into a unique origin, thus preventing it from accessing other content from the same origin.
This flag also prevents script from
reading from or writing to the document.cookie
IDL
attribute, and blocks access to localStorage
.
[WEBSTORAGE]
The allow-same-origin
attribute is intended for two cases.
First, it can be used to allow content from the same site to be sandboxed to disable scripting, while still allowing access to the DOM of the sandboxed content.
Second, it can be used to embed content from a third-party site, sandboxed to prevent that site from opening popup windows, etc, without preventing the embedded page from communicating back to its originating site, using the database APIs to store data, etc.
sandbox
attribute's
value, when split on
spaces, is found to have the allow-forms
keyword setThis flag blocks form submission.
sandbox
attribute's
value, when split on
spaces, is found to have the allow-scripts
keyword setThis flag blocks script execution.
sandbox
attribute's value, when
split on spaces, is
found to have the allow-scripts
keyword (defined above) setThis flag blocks features that trigger automatically, such as automatically playing a video or automatically focusing a form control. It is relaxed by the same flag as scripts, because when scripts are enabled these features are trivially possible anyway, and it would be unfortunate to force authors to use script to do them when sandboxed rather than allowing them to use the declarative features.
These flags must not be set unless the conditions listed above define them as being set.
These flags only take effect when the
nested browsing context of the iframe
is
navigated. Removing them, or removing
the entire sandbox
attribute, has no effect on an already-loaded page.
In this example, some completely-unknown, potentially hostile, user-provided HTML content is embedded in a page. Because it is sandboxed, it is treated by the user agent as being from a unique origin, despite the content being served from the same site. Thus it is affected by all the normal cross-site restrictions. In addition, the embedded page has scripting disabled, plugins disabled, forms disabled, and it cannot navigate any frames or windows other than itself (or any frames or windows it itself embeds).
<p>We're not scared of you! Here is your content, unedited:</p> <iframe sandbox src="getusercontent.cgi?id=12193"></iframe>
Note that cookies are still sent to the server in the getusercontent.cgi
request, though they are not
visible in the document.cookie
IDL
attribute.
It is important that the server serve the
user-provided HTML using the text/html-sandboxed
MIME
type so that if the attacker convinces the user to visit that page
directly, the page doesn't run in the context of the site's origin,
which would make the user vulnerable to any attack found in the
page.
In this example, a gadget from another site is embedded. The gadget has scripting and forms enabled, and the origin sandbox restrictions are lifted, allowing the gadget to communicate with its originating server. The sandbox is still useful, however, as it disables plugins and popups, thus reducing the risk of the user being exposed to malware and other annoyances.
<iframe sandbox="allow-same-origin allow-forms allow-scripts" src="http://maps.example.com/embedded.html"></iframe>
Suppose a file A contained the following fragment:
<iframe sandbox="allow-same-origin allow-forms" src=B></iframe>
Suppose that file B contained an iframe also:
<iframe sandbox="allow-scripts" src=C></iframe>
Further, suppose that file C contained a link:
<a href=D>Link</a>
For this example, suppose all the files were served as
text/html
.
Page C in this scenario has all the sandboxing flags
set. Scripts are disabled, because the iframe
in A has
scripts disabled, and this overrides the allow-scripts
keyword set on the iframe
in B. Forms are also
disabled, because the inner iframe
(in B) does not
have the allow-forms
keyword
set.
Suppose now that a script in A removes all the sandbox
attributes in A and
B. This would change nothing immediately. If the user clicked the
link in C, loading page D into the iframe
in B, page D
would now act as if the iframe
in B had the allow-same-origin
and allow-forms
keywords
set, because that was the state of the nested browsing
context in the iframe
in A when page B was
loaded.
Generally speaking, dynamically removing or changing the sandbox
attribute is
ill-advised, because it can make it quite hard to reason about what
will be allowed and what will not.
Potentially hostile files can be served from the
same server as the file containing the iframe
element
by labeling them as text/html-sandboxed
instead of
text/html
. This ensures that scripts in the files are
unable to attack the site (as if they were actually served from
another server), even if the user is tricked into visiting those
pages directly, without the protection of the sandbox
attribute.
If the allow-scripts
keyword is set along with allow-same-origin
keyword, and the file is from the same origin as the
iframe
's Document
, then a script in the
"sandboxed" iframe could just reach out, remove the sandbox
attribute, and then
reload itself, effectively breaking out of the sandbox
altogether.
The seamless
attribute is a boolean attribute. When specified, it
indicates that the iframe
element's browsing
context is to be rendered in a manner that makes it appear to
be part of the containing document (seamlessly included in the
parent document). Specifically, when the
attribute is set on an iframe
element whose owner
Document
's browsing context did not have
the sandboxed seamless iframes flag set when that
Document
was created, and while either the
browsing context's active document has the
same origin as the iframe
element's
document, or the browsing context's active
document's address has the same origin as the
iframe
element's document, or the browsing
context's active document is an
iframe
srcdoc
document, the following requirements apply:
The user agent must set the seamless browsing context
flag to true for that browsing context. This
will cause links to open in the parent
browsing context unless an explicit self-navigation
override is used (target="_self"
).
In a CSS-supporting user agent: the user agent must add all
the style sheets that apply to the iframe
element to
the cascade of the active document of the
iframe
element's nested browsing context,
at the appropriate cascade levels, before any style sheets
specified by the document itself.
In a CSS-supporting user agent: the user agent must, for the
purpose of CSS property inheritance only, treat the root element of
the active document of the iframe
element's nested browsing context as being a child of
the iframe
element. (Thus inherited properties on the
root element of the document in the iframe
will
inherit the computed values of those properties on the
iframe
element instead of taking their initial
values.)
In visual media, in a CSS-supporting user agent: the user agent
should set the intrinsic width of the iframe
to the
width that the element would have if it was a non-replaced
block-level element with 'width: auto'.
In visual media, in a CSS-supporting user agent: the user
agent should set the intrinsic height of the iframe
to
the height of the bounding box around the content rendered in the
iframe
at its current width (as given in the previous
bullet point), as it would be if the scrolling position was such
that the top of the viewport for the content rendered in the
iframe
was aligned with the origin of that content's
canvas.
In visual media, in a CSS-supporting user agent: the user agent
must force the height of the initial containing block of the
active document of the nested browsing
context of the iframe
to zero.
This is intended to get around the otherwise circular dependency of percentage dimensions that depend on the height of the containing block, thus affecting the height of the document's bounding box, thus affecting the height of the viewport, thus affecting the size of the initial containing block.
In speech media, the user agent should render the nested browsing context without announcing that it is a separate document.
User agents should, in general, act as if the active
document of the iframe
's nested browsing
context was part of the document that the
iframe
is in, if any.
For example if the user agent supports listing all the links in a document, links in "seamlessly" nested documents would be included in that list without being significantly distinguished from links in the document itself.
If the attribute is not specified, or if the origin conditions listed above are not met, then the user agent should render the nested browsing context in a manner that is clearly distinguishable as a separate browsing context, and the seamless browsing context flag must be set to false for that browsing context.
It is important that user agents recheck the
above conditions whenever the active document of the
nested browsing context of the iframe
changes, such that the seamless browsing context flag
gets unset if the nested browsing context is navigated to another origin.
The attribute can be set or removed dynamically, with the rendering updating in tandem.
In this example, the site's navigation is embedded using a
client-side include using an iframe
. Any links in the
iframe
will, in new user agents, be automatically
opened in the iframe
's parent browsing context; for
legacy user agents, the site could also include a base
element with a target
attribute with the value _parent
. Similarly,
in new user agents the styles of the parent page will be
automatically applied to the contents of the frame, but to support
legacy user agents authors might wish to include the styles
explicitly.
<nav><iframe seamless src="nav.include.html"></iframe></nav>
The iframe
element supports dimension
attributes for cases where the embedded content has specific
dimensions (e.g. ad units have well-defined dimensions).
An iframe
element never has fallback
content, as it will always create a nested browsing
context, regardless of whether the specified initial contents
are successfully used.
Descendants of iframe
elements represent
nothing. (In legacy user agents that do not support
iframe
elements, the contents would be parsed as markup
that could act as fallback content.)
When used in HTML
documents, the allowed content model of iframe
elements is text, except that invoking the HTML fragment
parsing algorithm with the iframe
element as the
context element and the text contents as the
input must result in a list of nodes that are
all phrasing content, with no parse errors having occurred, with no
script
elements being anywhere in the list or as
descendants of elements in the list, and with all the elements in
the list (including their descendants) being themselves
conforming.
The iframe
element must be empty in XML
documents.
The HTML parser treats markup inside
iframe
elements as text.
The IDL attributes src
, srcdoc
, name
, sandbox
, and seamless
must
reflect the respective content attributes of the same
name.
The contentDocument
IDL attribute must return the Document
object of the
active document of the iframe
element's
nested browsing context.
The contentWindow
IDL attribute must return the WindowProxy
object of the
iframe
element's nested browsing
context.
Here is an example of a page using an iframe
to
include advertising from an advertising broker:
<iframe src="http://ads.example.com/?customerid=923513721&format=banner" width="468" height="60"></iframe>
embed
elementsrc
type
width
height
interface HTMLEmbedElement : HTMLElement { attribute DOMString src; attribute DOMString type; attribute DOMString width; attribute DOMString height; };
Depending on the type of content instantiated by the
embed
element, the node may also support other
interfaces.
The embed
element represents an
integration point for an external (typically non-HTML) application
or interactive content.
The src
attribute
gives the address of the resource being embedded. The attribute, if
present, must contain a valid non-empty URL potentially
surrounded by spaces.
The type
attribute, if present, gives the MIME type by which the
plugin to instantiate is selected. The value must be a valid
MIME type. If both the type
attribute and the src
attribute are present, then the
type
attribute must specify the
same type as the explicit Content-Type
metadata of the resource given by the src
attribute.
When the element is created with neither a src
attribute nor a type
attribute, and when attributes
are removed such that neither attribute is present on the element
anymore, and when the element has a media element
ancestor, and when the element has an ancestor object
element that is not showing its fallback
content, any plugins instantiated for the element must be
removed, and the embed
element represents nothing.
If either:
embed
element's Document
is the
active document when that Document
was
created, orembed
element's Document
was
parsed from a resource whose sniffed type as determined during navigation is
text/html-sandboxed
...then the user agent must render the embed
element
in a manner that conveys that the plugin was
disabled. The user agent may offer the user the option to override
the sandbox and instantiate the plugin anyway; if the
user invokes such an option, the user agent must act as if the
conditions above did not apply for the purposes of this element.
Plugins are disabled in sandboxed browsing contexts because they might not honor the restrictions imposed by the sandbox (e.g. they might allow scripting even when scripting in the sandbox is disabled). User agents should convey the danger of overriding the sandbox to the user if an option to do so is provided.
An embed
element is said to be potentially active when the
following conditions are all met simultaneously:
Document
.Document
is fully active.src
attribute set or a type
attribute set (or both).src
attribute is either absent or its value is the empty string.Document
whose browsing context had the sandboxed plugins browsing context flag set when the Document
was created (unless this has been overridden as described above).Document
was not parsed from a resource whose sniffed type as determined during navigation is text/html-sandboxed
(unless this has been overridden as described above).object
element that is not showing its fallback content.Whenever an embed
element that was not potentially active becomes potentially active, and whenever
a potentially active
embed
element's src
attribute is set, changed, or
removed, and whenever a potentially active
embed
element's type
attribute is set, changed, or
removed, the appropriate set of steps from the following is then
applied:
src
attribute setThe user agent must resolve
the value of the element's src
attribute, relative to the element. If that is successful, the
user agent should fetch the resulting absolute
URL, from the element's browsing context scope
origin if it has one. The task that is
queued by the networking
task source once the resource has been fetched must find and instantiate an
appropriate plugin based on the content's type, and hand that
plugin the content of the resource, replacing any
previously instantiated plugin for the element.
Fetching the resource must delay the load event of the element's document.
src
attribute setThe user agent should find and instantiate an appropriate
plugin based on the value of the type
attribute.
Whenever an embed
element that was potentially active stops being
potentially active, any
plugin that had been instantiated for that element must
be unloaded.
The embed
element is unaffected by the
CSS 'display' property. The selected plugin is instantiated even if
the element is hidden with a 'display:none' CSS style.
The type of the content being embedded is defined as follows:
If the element has a type
attribute, and that attribute's
value is a type that a plugin supports, then the value
of the type
attribute is the
content's type.
Otherwise, if the <path> component of the URL of the specified resource (after any redirects) matches a pattern that a plugin supports, then the content's type is the type that that plugin can handle.
For example, a plugin might say that it can
handle resources with <path>
components that end with the four character string ".swf
".
Otherwise, if the specified resource has explicit Content-Type metadata, then that is the content's type.
Otherwise, the content has no type and there can be no appropriate plugin for it.
The embed
element has no fallback
content. If the user agent can't find a suitable plugin, then
the user agent must use a default plugin. (This default could be as
simple as saying "Unsupported Format".)
Whether the resource is fetched successfully or not (e.g. whether the response code was a 2xx code or equivalent) must be ignored when determining the resource's type and when handing the resource to the plugin.
This allows servers to return data for plugins even with error responses (e.g. HTTP 500 Internal Server Error codes can still contain plugin data).
Any namespace-less attribute other than name
, align
, hspace
, and vspace
may be specified on the embed
element,
so long as its name is XML-compatible and contains no
characters in the range U+0041 to U+005A (LATIN CAPITAL LETTER A to
LATIN CAPITAL LETTER Z). These attributes are then passed as
parameters to the plugin.
All attributes in HTML documents get lowercased automatically, so the restriction on uppercase letters doesn't affect such documents.
The four exceptions are to exclude legacy attributes that have side-effects beyond just sending parameters to the plugin.
The user agent should pass the names and values of all the
attributes of the embed
element that have no namespace
to the plugin used, when it is instantiated.
If the plugin instantiated for the
embed
element supports a scriptable interface, the
HTMLEmbedElement
object representing the element should
expose that interface while the element is instantiated.
The embed
element supports dimension
attributes.
The IDL attributes src
and type
each must
reflect the respective content attributes of the same
name.
Here's a way to embed a resource that requires a proprietary plug-in, like Flash:
<embed src="catgame.swf">
If the user does not have the plug-in (for example if the plug-in vendor doesn't support the user's platform), then the user will be unable to use the resource.
To pass the plugin a parameter "quality" with the value "high", an attribute can be specified:
<embed src="catgame.swf" quality="high">
This would be equivalent to the following, when using an
object
element instead:
<object data="catgame.swf"> <param name="quality" value="high"> </object>
object
elementusemap
attribute: Interactive content.param
elements, then, transparent.data
type
name
usemap
form
width
height
interface HTMLObjectElement : HTMLElement { attribute DOMString data; attribute DOMString type; attribute DOMString name; attribute DOMString useMap; readonly attribute HTMLFormElement form; attribute DOMString width; attribute DOMString height; readonly attribute Document contentDocument; readonly attribute WindowProxy contentWindow; readonly attribute boolean willValidate; readonly attribute ValidityState validity; readonly attribute DOMString validationMessage; boolean checkValidity(); void setCustomValidity(in DOMString error); };
Depending on the type of content instantiated by the
object
element, the node also supports other
interfaces.
The object
element can represent an external
resource, which, depending on the type of the resource, will either
be treated as an image, as a nested browsing context,
or as an external resource to be processed by a
plugin.
The data
attribute, if present, specifies the address of the resource. If
present, the attribute must be a valid non-empty
URL potentially surrounded by spaces.
The type
attribute, if present, specifies the type of the resource. If
present, the attribute must be a valid MIME type.
At least one of either the data
attribute or the type
attribute must be present.
The name
attribute, if present, must be a valid browsing context
name. The given value is used to name the nested
browsing context, if applicable.
When the element is created, when it is popped off the
stack of open elements of an HTML parser
or XML parser, and subsequently whenever the element is
inserted into a
document or removed from a document; and whenever the element's
Document
changes whether it is fully
active; and whenever an ancestor object
element
changes to or from showing its fallback content; and
whenever the element's classid
attribute is set,
changed, or removed; and, when its classid
attribute is not present,
whenever its data
attribute is
set, changed, or removed; and, when neither its classid
attribute nor its data
attribute are present, whenever
its type
attribute is set,
changed, or removed: the user agent must queue a task
to run the following steps to (re)determine what the
object
element represents. The task source
for this task is the DOM
manipulation task source.
If the user has indicated a preference that this
object
element's fallback content be
shown instead of the element's usual behavior, then jump to the
last step in the overall set of steps (fallback).
For example, a user could ask for the element's fallback content to be shown because that content uses a format that the user finds more accessible.
If the element has an ancestor media element, or
has an ancestor object
element that is not
showing its fallback content, or if the element is
not in a Document
with a browsing context, or if the element's
Document
is not fully active, or if the
element is still in the stack of open elements of an
HTML parser or XML parser, then jump to
the last step in the overall set of steps (fallback).
If the classid
attribute is present, and has a value that isn't the empty string,
then: if the user agent can find a plugin suitable
according to the value of the classid
attribute, and plugins aren't being sandboxed,
then that plugin should be
used, and the value of the data
attribute, if any, should be
passed to the plugin. If no suitable
plugin can be found, or if the plugin
reports an error, jump to the last step in the overall set of
steps (fallback).
If the data
attribute
is present and its value is not the empty string, then:
If the type
attribute is present and its value is not a type that the user
agent supports, and is not a type that the user agent can find a
plugin for, then the user agent may jump to the last
step in the overall set of steps (fallback) without fetching the
content to examine its real type.
Resolve the
URL specified by the data
attribute, relative to the
element.
If that failed, fire a simple event named
error
at the element, then jump
to the last step in the overall set of steps (fallback).
Fetch the resulting absolute URL, from the element's browsing context scope origin if it has one.
Fetching the resource must delay the load event of the element's document until the task that is queued by the networking task source once the resource has been fetched (defined next) has been run.
For the purposes of the application cache networking model, this fetch operation is not for a child browsing context (though it might end up being used for one after all, as defined below).
If the resource is not yet available (e.g. because the resource was not available in the cache, so that loading the resource required making a request over the network), then jump to the last step in the overall set of steps (fallback). The task that is queued by the networking task source once the resource is available must restart this algorithm from this step. Resources can load incrementally; user agents may opt to consider a resource "available" whenever enough data has been obtained to begin processing the resource.
If the load failed (e.g. there was an HTTP 404 error,
there was a DNS error), fire a simple event named
error
at the element, then jump
to the last step in the overall set of steps (fallback).
Determine the resource type, as follows:
Let the resource type be unknown.
If the user agent is configured to strictly obey Content-Type headers for this resource, and the resource has associated Content-Type metadata, then let the resource type be the type specified in the resource's Content-Type metadata, and jump to the step below labeled handler.
If there is a type
attribute present on the object
element, and that
attribute's value is not a type that the user agent supports,
but it is a type that a plugin supports,
then let the resource type be the type
specified in that type
attribute, and jump to the step below labeled
handler.
Run the approprate set of steps from the following list:
Let binary be false.
If the type specified in the
resource's Content-Type metadata is
"text/plain
", and the result of applying the
rules
for distingushing if a resource is text or binary
to the resource is that the resource is not
text/plain
, then set binary to true.
If the type specified in the
resource's Content-Type metadata is
"application/octet-stream
", then set binary to true.
If binary is false, then let the resource type be the type specified in the resource's Content-Type metadata, and jump to the step below labeled handler.
If there is a type
attribute present on
the object
element, and its value is not
application/octet-stream
, then run the
following steps:
If the attribute's value is a type that a plugin supports, or
the attribute's value is a type that starts with "image/
" that is not also an XML MIME type,
then let the resource type be the type specified in that type
attribute.
Jump to the step below labeled handler.
If there is a type
attribute present on
the object
element, then let the tentative type be the type specified in that
type
attribute.
Otherwise, let tentative type be the sniffed type of the resource.
If tentative type is not
application/octet-stream
, then let resource type be tentative
type and jump to the step below labeled
handler.
If the <path> component of the URL of the specified resource (after any redirects) matches a pattern that a plugin supports, then let resource type be the type that that plugin can handle.
For example, a plugin might say that it can
handle resources with <path> components that end with
the four character string ".swf
".
It is possible for this step to finish with resource type still being unknown, or for one of the substeps above to jump straight to the next step. In both cases, the next step will trigger fallback.
Handler: Handle the content as given by the first of the following cases that matches:
If plugins are being sandboxed, jump to the last step in the overall set of steps (fallback).
Otherwise, the user agent should use the plugin that supports resource type and pass the content of the resource to that plugin. If the plugin reports an error, then jump to the last step in the overall set of steps (fallback).
image/
"The object
element must be associated with a
newly created nested browsing context, if it does
not already have one.
If the URL of the given resource is not
about:blank
, the element's nested browsing
context must then be navigated to that
resource, with replacement enabled, and with the
object
element's document's browsing
context as the source browsing context.
(The data
attribute of
the object
element doesn't get updated if the
browsing context gets further navigated to other
locations.)
If the URL of the given resource is
about:blank
, then, instead, the user agent must
queue a task to fire a simple event
named load
at the
object
element.
The object
element represents the
nested browsing context.
If the name
attribute
is present, the browsing context name must be set
to the value of this attribute; otherwise, the browsing
context name must be set to the empty string.
In certain situations, e.g. if the resource
was fetched from an
application cache but it is an HTML file with a
manifest
attribute
that points to a different application cache
manifest, the navigation
of the browsing context will be restarted so as
to load the resource afresh from the network or a different
application cache. Even if the resource is then
found to have a different type, it is still used as part of a
nested browsing context: only the
navigate algorithm is restarted, not this
object
algorithm.
image/
", and support for images has not been
disabledApply the image sniffing rules to determine the type of the image.
The object
element represents the
specified image. The image is not a nested browsing
context.
If the image cannot be rendered, e.g. because it is malformed or in an unsupported format, jump to the last step in the overall set of steps (fallback).
The given resource type is not supported. Jump to the last step in the overall set of steps (fallback).
If the previous step ended with the resource type being unknown, this is the case that is triggered.
The element's contents are not part of what the
object
element represents.
Once the resource is completely loaded, queue a
task to fire a simple event named load
at the element.
The task source for this task is the DOM manipulation task source.
If the data
attribute
is absent but the type
attribute is present, plugins aren't
being sandboxed, and the user agent can find a
plugin suitable according to the value of the type
attribute, then that
plugin should be used. If
no suitable plugin can be found, or if the
plugin reports an error, jump to the next step
(fallback).
(Fallback.) The object
element
represents the element's children, ignoring any
leading param
element children. This is the element's
fallback content. If the element has an instantiated
plugin, then unload it.
When the algorithm above instantiates a
plugin, the user agent should pass to the
plugin used the names and values of all the attributes
on the element, in the order they were added to the element, with
the attributes added by the parser being ordered in source order,
followed by a parameter named "PARAM" whose value is null,
followed by all the names and values of parameters given by
param
elements that are children of the
object
element, in tree order. If the
plugin supports a scriptable interface, the
HTMLObjectElement
object representing the element
should expose that interface. The object
element
represents the plugin. The
plugin is not a nested browsing
context.
If either:
object
element's Document
's
browsing context when the Document
was
created, orobject
element's Document
was
parsed from a resource whose sniffed type as determined during navigation is
text/html-sandboxed
...then the steps above must always act as if they had failed to find a plugin, even if one would otherwise have been used.
The above algorithm is independent of CSS properties (including 'display', 'overflow', and 'visibility'). For example, it runs even if the element is hidden with a 'display:none' CSS style, and does not run again if the element's visibility changes.
Due to the algorithm above, the contents of object
elements act as fallback content, used only when
referenced resources can't be shown (e.g. because it returned a 404
error). This allows multiple object
elements to be
nested inside each other, targeting multiple user agents with
different capabilities, with the user agent picking the first one it
supports.
Whenever the name
attribute
is set, if the object
element has a nested
browsing context, its name must be changed to the new value. If the attribute
is removed, if the object
element has a browsing
context, the browsing context name must be set
to the empty string.
The usemap
attribute,
if present while the object
element represents an
image, can indicate that the object has an associated image
map. The attribute must be ignored if the
object
element doesn't represent an image.
The form
attribute is used to
explicitly associate the object
element with its
form owner.
Constraint validation: object
elements are always barred from constraint
validation.
The object
element supports dimension
attributes.
The IDL attributes data
, type
, name
, and useMap
each must
reflect the respective content attributes of the same
name.
The contentDocument
IDL attribute must return the Document
object of the
active document of the object
element's
nested browsing context, if it has one; otherwise, it
must return null.
The contentWindow
IDL attribute must return the WindowProxy
object of the
object
element's nested browsing context,
if it has one; otherwise, it must return null.
The willValidate
, validity
, and validationMessage
attributes, and the checkValidity()
and setCustomValidity()
methods, are part of the constraint validation API. The
form
IDL attribute is part of the
element's forms API.
In the following example, a Java applet is embedded in a page
using the object
element. (Generally speaking, it is
better to avoid using applets like these and instead use native
JavaScript and HTML to provide the functionality, since that way
the application will work on all Web browsers without requiring a
third-party plugin. Many devices, especially embedded devices, do
not support third-party technologies like Java.)
<figure> <object type="application/x-java-applet"> <param name="code" value="MyJavaClass"> <p>You do not have Java available, or it is disabled.</p> </object> <figcaption>My Java Clock</figcaption> </figure>
In this example, an HTML page is embedded in another using the
object
element.
<figure> <object data="clock.html"></object> <figcaption>My HTML Clock</figcaption> </figure>
The following example shows how a plugin can be used in HTML (in
this case the Flash plugin, to show a video file). Fallback is
provided for users who do not have Flash enabled, in this case
using the video
element to show the video for those
using user agents that support video
, and finally
providing a link to the video for those who have neither Flash nor
a video
-capable browser.
<p>Look at my video: <object type="application/x-shockwave-flash"> <param name=movie value="http://video.example.com/library/watch.swf"> <param name=allowfullscreen value=true> <param name=flashvars value="http://video.example.com/vids/315981"> <video controls src="http://video.example.com/vids/315981"> <a href="http://video.example.com/vids/315981">View video</a>. </video> </object> </p>
param
elementobject
element, before any flow content.name
value
interface HTMLParamElement : HTMLElement { attribute DOMString name; attribute DOMString value; };
The param
element defines parameters for plugins
invoked by object
elements. It does not represent anything on its own.
The name
attribute gives the name of the parameter.
The value
attribute gives the value of the parameter.
Both attributes must be present. They may have any value.
If both attributes are present, and if the parent element of the
param
is an object
element, then the
element defines a parameter with the given
name/value pair.
If either the name or value of a parameter defined by a
param
element that is the child of an
object
element that represents an
instantiated plugin changes, and if that
plugin is communicating with the user agent using an
API that features the ability to update the plugin when
the name or value of a parameter so changes, then
the user agent must appropriately exercise that ability to notify
the plugin of the change.
The IDL attributes name
and value
must both
reflect the respective content attributes of the same
name.
The following example shows how the param
element
can be used to pass a parameter to a plugin, in this case the O3D
plugin.
<!DOCTYPE HTML> <html lang="en"> <head> <title>O3D Utah Teapot</title> </head> <body> <p> <object type="application/vnd.o3d.auto"> <param name="o3d_features" value="FloatingPointTextures"> <img src="o3d-teapot.png" title="3D Utah Teapot illustration rendered using O3D." alt="When O3D renders the Utah Teapot, it appears as a squat teapot with a shiny metallic finish on which the surroundings are reflected, with a faint shadow caused by the lighting."> <p>To see the teapot actually rendered by O3D on your computer, please download and install the <a href="http://code.google.com/apis/o3d/docs/gettingstarted.html#install">O3D plugin</a>.</p> </object> <script src="o3d-teapot.js"></script> </p> </body> </html>