the target's HTMLDocument
object
is not an active document at that time. In such
cases, the user agent must instead delay the firing of the event until
such time as the HTMLDocument
object in question becomes an active document again.
When there are multiple delayed storage
events for the same HTMLDocument
object, user agents must
coalesce those events such that only one event fires when the document
becomes active again.
If the DOM of a page that has delayed storage
events queued up is discarded, then the delayed events are dropped as well.
User agents should limit the total amount of space allowed for a storage area based on the domain of the page setting the value.
User agents should not limit the total amount of space allowed on a per-storage-area basis, otherwise a site could just store data in any number of subdomains or ports, e.g. storing up to the limit in a1.example.com, a2.example.com, a3.example.com, etc, circumventing per-domain limits.
User agents may prompt the user when per-domain space quotas are reached, allowing the user to grant a site more space. This enables sites to store many user-created documents on the user's computer, for instance.
User agents should allow users to see how much space each domain is using.
If the storage area space limit is reached during a setItem()
call,
the user agent must raise an INVALID_ACCESS_ERR
exception.
A mostly arbitrary limit of five megabytes per domain is recommended. Implementation feedback is welcome and will be used to update this suggestion in future.
Multiple browsing contexts must be able to access the global storage areas simultaneously in a predictable manner. Scripts must not be able to detect any concurrent script execution.
This is required to guarentee that the length
attribute of a Storage
object never changes while a script is
executing, other than in a way that is predictable by the script itself.
There are various ways of implementing this requirement. One is that if a script running in one browsing context accesses a global storage area, the UA blocks scripts in other browsing contexts when they try to access the global storage area for the same origin until the first script has executed to completion. (Similarly, when a script in one browsing context accesses its session storage area, any scripts that have the same top level browsing context and the same origin would block when accessing their session storage area until the first script has executed to completion.) Another (potentially more efficient but probably more complex) implementation strategy is to use optimistic transactional script execution. This specification does not require any particular implementation strategy, so long as the requirement above is met.
A third-party advertiser (or any entity capable of getting content distributed to multiple sites) could use a unique identifier stored in its global storage area to track a user across multiple sessions, building a profile of the user's interests to allow for highly targeted advertising. In conjunction with a site that is aware of the user's real identity (for example an e-commerce site that requires authenticated credentials), this could allow oppressive groups to target individuals with greater accuracy than in a world with purely anonymous Web usage.
There are a number of techniques that can be used to mitigate the risk of user tracking:
Blocking third-party storage: user agents may restrict access to the
globalStorage
object to scripts
originating at the domain of the top-level document of the browsing context.
Expiring stored data: user agents may automatically delete stored data after a period of time.
For example, a user agent could treat third-party global storage areas as session-only storage, deleting the data once the user had closed all the browsing contexts that could access it.
This can restrict the ability of a site to track a user, as the site would then only be able to track the user across multiple sessions when he authenticates with the site itself (e.g. by making a purchase or logging in to a service).
However, this also puts the user's data at risk.
Treating persistent storage as cookies: user agents may present the persistent storage feature to the user in a way that does not distinguish it from HTTP session cookies. [RFC2965]
This might encourage users to view persistent storage with healthy suspicion.
Site-specific white-listing of access to global storage areas: user agents may allow sites to access session storage areas in an unrestricted manner, but require the user to authorise access to global storage areas.
Origin-tracking of persistent storage data: user agents may record the origins of sites that contained content from third-party origins that caused data to be stored.
If this information is then used to present the view of data currently in persistent storage, it would allow the user to make informed decisions about which parts of the persistent storage to prune. Combined with a blacklist ("delete this data and prevent this domain from ever storing data again"), the user can restrict the use of persistent storage to sites that he trusts.
Shared blacklists: user agents may allow users to share their persistent storage domain blacklists.
This would allow communities to act together to protect their privacy.
While these suggestions prevent trivial use of this API for user tracking, they do not block it altogether. Within a single domain, a site can continue to track the user during a session, and can then pass all this information to the third party along with any identifying information (names, credit card numbers, addresses) obtained by the site. If a third party cooperates with multiple sites to obtain such information, a profile can still be created.
However, user tracking is to some extent possible even with no cooperation from the user agent whatsoever, for instance by using session identifiers in URIs, a technique already commonly used for innocuous purposes but easily repurposed for user tracking (even retroactively). This information can then be shared with other sites, using using visitors' IP addresses and other user-specific data (e.g. user-agent headers and configuration settings) to combine separate sessions into coherent user profiles.
If the user interface for persistent storage presents data in the persistent storage feature separately from data in HTTP session cookies, then users are likely to delete data in one and not the other. This would allow sites to use the two features as redundant backup for each other, defeating a user's attempts to protect his privacy.
Because of the potential for DNS spoofing attacks, one cannot guarentee that a host claiming to be in a certain domain really is from that domain. To mitigate this, pages can use SSL. Pages using SSL can be sure that only pages using SSL that have certificates identifying them as being from the same domain can access their global storage areas.
Different authors sharing one host name, for example users hosting
content on geocities.com
, all share one persistent storage
object. There is no feature to restrict the access by pathname. Authors on
shared hosts are therefore recommended to avoid using the persistent
storage feature, as it would be trivial for other authors to read from and
write to the same storage area.
Even if a path-restriction feature was made available, the usual DOM scripting security model would make it trivial to bypass this protection and access the data from any path.
The two primary risks when implementing this persistent storage feature are letting hostile sites read information from other domains, and letting hostile sites write information that is then read from other domains.
Letting third-party sites read data that is not supposed to be read from their domain causes information leakage, For example, a user's shopping wishlist on one domain could be used by another domain for targeted advertising; or a user's work-in-progress confidential documents stored by a word-processing site could be examined by the site of a competing company.
Letting third-party sites write data to the storage areas of other domains can result in information spoofing, which is equally dangerous. For example, a hostile site could add items to a user's wishlist; or a hostile site could set a user's session identifier to a known ID that the hostile site can then use to track the user's actions on the victim site.
Thus, strictly following the model described in this specification is important for user security.
...
Each origin has an associated set of databases. Each database has a name and a current version. There is no way to enumerate or delete the databases available for a domain from this API.
Each database has one version at a time, a database can't exist in multiple versions at once. Versions are intended to allow authors to manage schema changes incrementally and non-destructively, and without running the risk of old code (e.g. in another browser window) trying to write to a database with incorrect assumptions.
The openDatabase()
method returns a
Database
object. The method takes
four arguments: a database name, a database version, a display name, and
an estimated size, in bytes, of the data that will be stored in the
database.
If the database version provided is not the empty string, and the
database already exists but has a different version, then the method must
raise an INVALID_STATE_ERR
exception.
Otherwise, if the database provided is the empty string, or if the
database doesn't yet exist, or if the database exists and the version
provided to the openDatabase()
method is the same as the
current version associated with the database, then the method must return
a Database
object representing the
database associated with the origin of the active document of the browsing
context of the Window
object on
which the method was called that has the name that was given. If no such
database exists, it must be created first.
All strings including the empty string are valid database names. Database names are case-sensitive.
Implementations can support this even in environments that only support a subset of all strings as database names by mapping database names (e.g. using a hashing algorithm) to the supported set of names.
User agents are expected to use the display name and the estimated database size to optimise the user experience. For example, a user agent could use the estimated size to suggest an initial quota to the user. This allows a site that is aware that it will try to use hundreds of megabytes to declare this upfront, instead of the user agent prompting the user for permission to increase the quota every five megabytes.
interface Database { void transaction(in SQLTransactionCallback callback); void transaction(in SQLTransactionCallback callback, in SQLTransactionErrorCallback errorCallback); void transaction(in SQLTransactionCallback callback, in SQLTransactionErrorCallback errorCallback, in VoidCallback successCallback); readonly attribute DOMString version; void changeVersion(in DOMString oldVersion, in DOMString newVersion, in SQLTransactionCallback callback, in SQLTransactionErrorCallback errorCallback, in VoidCallback successCallback); }; interface SQLTransactionCallback { void handleEvent(in SQLTransaction transaction); }; interface SQLTransactionErrorCallback { boolean handleEvent(in SQLError error); };
The transaction()
method
takes one or two arguments. When called, the method must immediately
return and then asynchronously run the transaction
steps with the transaction callback being the first argument,
the error callback being the second argument, if any, the
success callback being the third argument, if any, and with no
preflight operation or postflight operation.
The version that the database was opened with is the expected version of this
Database
object. It can be the empty
string, in which case there is no expected version — any version is
fine.
On getting, the version
attribute must
return the current version of the database (as opposed to the expected
version of the Database
object).
The changeVersion()
method
allows scripts to atomically verify the version number and change it at
the same time as doing a schema update. When the method is invoked, it
must immediately return, and then asynchronously run the transaction steps with the transaction
callback being the third argument, the error callback being the
fourth argument, the success callback being the fifth argument, the
preflight operation being the following:
Check that the value of the first argument to the changeVersion()
method exactly matches
the database's actual version. If it does not, then the preflight
operation fails.
...and the postflight operation being the following:
changeVersion()
method.
Database
object's
expected version to the value of the second argument to the changeVersion()
method.
The transaction()
and changeVersion()
methods invoke callbacks
with SQLTransaction
objects.
typedef sequence<Object> ObjectArray; interface SQLTransaction { void executeSql(in DOMString sqlStatement); void executeSql(in DOMString sqlStatement, in ObjectArray arguments); void executeSql(in DOMString sqlStatement, in ObjectArray arguments, in SQLStatementCallback callback); void executeSql(in DOMString sqlStatement, in ObjectArray arguments, in SQLStatementCallback callback, in SQLStatementErrorCallback errorCallback); }; interface SQLStatementCallback { void handleEvent(in SQLTransaction transaction, in SQLResultSet resultSet); }; interface SQLStatementErrorCallback { boolean handleEvent(in SQLTransaction transaction, in SQLError error);Or should these arguments be the other way around? Either way we're inconsistent with _something_. What should we be consistent with? };
When the executeSql(sqlStatement, arguments, callback, errorCallback)
method is invoked, the user agent must run the following algorithm. (This
algorithm is relatively simple and doesn't actually execute any SQL
— the bulk of the work is actually done as part of the transaction steps.)
If the method was not invoked during the execution of a SQLTransactionCallback
,
SQLStatementCallback
,
or SQLStatementErrorCallback
then raise an INVALID_STATE_ERR
exception. (Calls from
inside a SQLTransactionErrorCallback
thus raise an exception. The SQLTransactionErrorCallback
handler is only called once a transaction has failed, and no SQL
statements can be added to a failed transaction.)
Parse the first argument to the method (sqlStatement) as an SQL statement, with the exception
that ?
characters can be used in place of literals
in the statement. [SQL]
Replace each ?
placeholder with the value of the
argument in the arguments array with the same
position. (So the first ?
placeholder gets
replaced by the first value in the arguments array,
and generally the nth ?
placeholder gets replaced by the nth value in the
arguments array.)
If the second argument is ommitted or null, then treat the arguments array as empty.
The result is the statement.
If the syntax of sqlStatement is not valid (except
for the use of ?
characters in the place of
literals), or the statement uses features that are not supported (e.g.
due to security reasons), or the number of items in the arguments array is not equal to the number of ?
placeholders in the statement, or the statement cannot
be parsed for some other reason, then mark the statement as
bogus.
If the Database
object that the
SQLTransaction
object was
created from has an expected version that is
neither the empty string nor the actual version of the database, then
mark the statement as bogus. (Error code 2.)
Queue up the statement in the transaction, along with the third argument (if any) as the statement's result set callback and the fourth argument (if any) as the error callback.
The user agent must act as if the database was hosted in an otherwise completely empty environment with no resources. For example, attempts to read from or write to the filesystem will fail.
User agents should limit the total amount of space allowed for each origin, but may prompt the user and extend the limit if a database is reaching its quota. User agents should allow users to see how much space each database is using.
A mostly arbitrary limit of five megabytes per origin is recommended. Implementation feedback is welcome and will be used to update this suggestion in future.
SQL inherently supports multiple concurrent connections. Authors should make appropriate use of the transaction features to handle the case of multiple scripts interacting with the same database simultaneously (as could happen if the same page was opened in two different browsing contexts).
User agents must consider statements that use the BEGIN
, COMMIT
, and ROLLBACK
SQL features as being unsupported (and thus will
mark them as bogus), so as to not let these statements interfere with the
explicit transactions managed by the database API itself.
A future version of this specification will probably define the exact SQL subset required in more detail.
The executeSql()
method
invokes its callback with a SQLResultSet
object as an argument.
interface SQLResultSet { readonly attribute int insertId; readonly attribute int rowsAffected; readonly attribute SQLResultSetRowList rows; };
The insertId
attribute must
return the row ID of the row that the SQLResultSet
object's SQL statement
inserted into the database, if the statement inserted a row. If the
statement inserted multiple rows, the ID of the last row must be the one
returned. If the statement did not insert a row, then the attribute must
instead raise an INVALID_ACCESS_ERR
exception.
The rowsAffected
attribute must return the number of rows that were affected by the SQL
statement. If the statement did not affected any rows, then the attribute
must return zero. For "SELECT" statements, this returns zero (querying the
database doesn't affect any rows).
The rows
attribute must return a SQLResultSetRowList
representing
the rows returned, in the order returned by the database. If no rows were
returned, then the object will be empty.
interface SQLResultSetRowList {
readonly attribute unsigned long length;
DOMObject item(in unsigned long index);
};
SQLResultSetRowList
objects have a length
attribute
that must return the number of rows it represents (the number of rows
returned by the database).
The item(index)
attribute must return the row with the
given index index. If there is no such row, then the
method must raise an INDEX_SIZE_ERR
exception.
Each row must be represented by a native ordered dictionary data type.
In the ECMAScript binding, this must be Object
. Each row object must have one property
(or dictionary entry) per column, with those properties enumerating in the
order that these columns were returned by the database. Each property must
have the name of the column and the value of the cell, as they were
returned by the database.
Errors in the database API are reported using callbacks that have a
SQLError
object as one of their
arguments.
interface SQLError { readonly attribute unsigned int code; readonly attribute DOMString message; };
The code
DOM
attribute must return the most appropriate code from the following table:
| Code | Situation |
|---|---|
| 0 | The transaction failed for reasons unrelated to the database itself and not covered by any other error code. |
| 1 | The statement failed for database reasons not covered by any other error code. |
| 2 | The statement failed because the expected version of the database didn't match the actual database version. |
| 3 | The statement failed because the data returned from the database was too large. The SQL "LIMIT" modifier might be useful to reduce the size of the result set. |
| 4 | The statement failed because there was not enough remaining storage space, or the storage quota was reached and the user declined to give more space to the database. |
| 5 | The statement failed because the transaction's first statement was a read-only statement, and a subsequent statement in the same transaction tried to modify the database, but the transaction failed to obtain a write lock before another transaction obtained a write lock and changed a part of the database that the former transaction was dependending upon. |
| 6 | An INSERT , UPDATE , or
REPLACE statement failed due to a constraint
failure. For example, because a row was being inserted and the value
given for the primary key column duplicated the value of an existing
row.
|
We should define a more thorough list of codes. Implementation feedback is requested to determine what codes are needed.
The message
DOM attribute must
return an error message describing the error encountered. The message
should be localised to the user's language.
The transaction steps are as follows. These steps must be run asynchronously. These steps are invoked with a transaction callback, optionally an error callback, optionally a success callback, optionally a preflight operation, and optionally a postflight operation.
Open a new SQL transaction to the database, and create a SQLTransaction
object that represents
that transaction.
If an error occured in the opening of the transaction, jump to the last step.
If a preflight operation was defined for this instance of the
transaction steps, run that. If it fails, then jump to the last step.
(This is basically a hook for the changeVersion()
method.)
Invoke the transaction callback with the
aforementioned SQLTransaction
object as its only argument.
If the callback couldn't be called (e.g. it was null), or if the callback was invoked and raised an exception, jump to the last step.
While there are any statements queued up in the transaction, perform the following steps for each queued up statement in the transaction, oldest first. Each statement has a statement, a result set callback, and optionally an error callback.
If the statement is marked as bogus, jump to the "in case of error" steps below.
Execute the statement in the context of the transaction. [SQL]
If the statement failed, jump to the "in case of error" steps below.
Create a SQLResultSet
object that represents the result of the statement.
Invoke the statement's result set callback with
the SQLTransaction
object
as its first argument and the new SQLResultSet
object as its second
argument.
If the callback was invoked and raised an exception, jump to the last step in the overall steps.
Move on to the next statement, if any, or onto the next overall step otherwise.
In case of error (or more specifically, if the above substeps say to jump to the "in case of error" steps), run the following substeps:
If the statement had an associated error callback, then invoke that
error callback with the SQLTransaction
object and a newly
constructed SQLError
object that
represents the error that caused these substeps to be run as the two
arguments, respectively.
If the error callback returns false, then move on to the next statement, if any, or onto the next overall step otherwise.
Otherwise, the error callback did not return false, or there was no error callback. Jump to the last step in the overall steps.
If a postflight operation was defined for his instance of the
transaction steps, run that. If it fails, then jump to the last step.
(This is basically a hook for the changeVersion()
method.)
Commit the transaction.
If an error occured in the committing of the transaction, jump to the last step.
Invoke the success callback.
End these steps. The next step is only used when something goes wrong.
Call the error callback with a newly constructed SQLError
object that represents the last
error to have occured in this transaction. If the error callback
returned false, and the last error wasn't itself a failure when
committing the transaction, then try to commit the transaction. If that
fails, or if the callback couldn't be called (e.g. the method was called
with only one argument), or if it didn't return false, then rollback the
transaction. Any still-pending statements in the transaction are
discarded.
In contrast with the globalStorage
feature, which
intentionally allows data to be accessed across multiple domains,
protocols, and ports (albeit in a controlled fashion), this database
feature is limited to scripts running with the same origin as the database. Thus, it is expected that the
privacy implications be equivalent to those already present in allowing
scripts to communicate with their originating host.
User agents are encouraged to treat data stored in databases in the same way as cookies for the purposes of user interfaces, to reduce the risk of using this feature for cookie resurrection.
User agent implementors are strongly encouraged to audit all their
supported SQL statements for security implications. For example, LOAD DATA INFILE
is likely to pose security risks and
there is little reason to support it.
In general, it is recommended that user agents not support features that control how databases are stored on disk. For example, there is little reason to allow Web authors to control the character encoding used in the disk representation of the data, as all data in ECMAScript is implicitly UTF-16.
Authors are strongly recommended to make use of the ?
placeholder feature of the executeSql()
method, and to never construct
SQL statements on the fly.
The a
, area
, and link
elements can, in certain situations described in the definitions of those
elements, represent hyperlinks.
The href
attribute on a hyperlink element must have a value that is a URI (or IRI).
This URI is the destination resource of the hyperlink.
The href
attribute on a
and area
elements is not required; when those
elements do not have href
attributes they do not represent
hyperlinks.
The href
attribute on the link
element
is required, but whether a link
element represents a hyperlink or not depends on the value of the rel
attribute of that
element.
The target
attribute, if
present, must be a valid browsing context name. User
agents use this name when following hyperlinks.
The ping
attribute, if present, gives the URIs of the resources that are interested
in being notified if the user follows the hyperlink. The value must be a
space separated list of one or more URIs (or IRIs). The value is used by
the user agent when following hyperlinks.
For a
and area
elements that represent hyperlinks, the
relationship between the document containing the hyperlink and the
destination resource indicated by the hyperlink is given by the value of
the element's rel
attribute, which must be a set of space-separated
tokens. The allowed values 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
recognised by the UA, 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. [MQ] The default, if the media
attribute
is omitted, is all
.
The hreflang
attribute on
hyperlink elements, if present, gives the language of the linked resource.
It is purely advisory. The value must be a valid RFC 3066 language code.
[RFC3066] User agents must not consider this
attribute authoritative — upon fetching the resource, user agents
must only use 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, optionally with
parameters. [RFC2046] 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, the user agent must navigate a browsing context to the URI of the hyperlink.
The URI of the hyperlink is URI given by resolving the the href
attribute of
that hyperlink relative to the hyperlink's element. In the case of
server-side image maps, the URI of the hyperlink must further have its
hyperlink suffix appended to it.
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 hyperlink 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 chosing 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 element 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 hyperlink element is an a
or area
element
with no target
attribute, but one of the child nodes of
the head
element is a base
element with a target
attribute, then
the browsing context that is navigated must be chosen by applying the rules for chosing 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 hyperlink element itself is in.
If an a
or area
hyperlink element has a ping
attribute and
the user follows the hyperlink, the user agent must take the ping
attribute's
value, split that string on
spaces, treat each resulting token as a URI (resolving relative
URIs according to element's base URI) and then should send a request to
each of the resulting URIs. 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 behaviour, for example
in conjunction with a setting that disables the sending of HTTP Referer
headers. Based on the user's preferences, UAs may
either ignore the ping
attribute
altogether, or selectively ignore URIs in the list (e.g. ignoring any
third-party URIs).
For URIs that are HTTP URIs, the requests must be performed using the POST method (with an empty entity body in the request). User agents must ignore any entity bodies returned in the responses, but must, unless otherwise specified by the user, honour the HTTP headers — in particular, HTTP cookie headers. [RFC2965]
To save bandwidth, implementors might wish to consider
omitting optional headers such as Accept
from these requests.
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 URIs.
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 improve
the user experience.
The following table summarises 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.
Unless otherwise specified, a keyword must not be specified more than
once per rel
attribute.
| Link type | Effect on... | Brief description | |
|---|---|---|---|
link
| a and area
| ||
alternate |
Hyperlink | Hyperlink | Gives alternate representations of the current document. |
archives
| Hyperlink | Hyperlink | Provides a link to a collection of records, documents, or other materials of historical interest. |
author
| Hyperlink | Hyperlink | Gives a link to the current document's author. |
bookmark |
not allowed | Hyperlink | Gives the permalink for the nearest ancestor section. |
contact |
Hyperlink | Hyperlink | Gives a link to contact information for the current document. |
external |
not allowed | Hyperlink | Indicates that the referenced document is not part of the same site as the current document. |
feed
| Hyperlink | Hyperlink | Gives the address of a syndication feed for the current document. |
first
| Hyperlink | Hyperlink | Indicates that the current document is a part of a series, and that the first document in the series is the referenced document. |
help
| Hyperlink | Hyperlink | Provides a link to context-sensitive help. |
icon |
External Resource | not allowed | Imports an icon to represent the current document. |
index |
Hyperlink | Hyperlink | Gives a link to the document that provides a table of contents or index listing the current document. |
last
| Hyperlink | Hyperlink | Indicates that the current document is a part of a series, and that the last document in the series is the referenced document. |
license |
Hyperlink | Hyperlink | Indicates that 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 | Hyperlink | Indicates that the current document's original author or publisher does not endorse the referenced document. |
noreferrer
| not allowed | Hyperlink | Requires that the user agent not send an HTTP Referer header if the user follows the hyperlink.
|
pingback
| External Resource | not allowed | Gives the address of the pingback server that handles pingbacks to the current document. |
prefetch
| External Resource | not allowed | Specifies that the target resource should be pre-emptively 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. |
sidebar |
Hyperlink | Hyperlink | Specifies that the referenced document, if retrieved, is intended to be shown in the browser's sidebar (if it has one). |
tag |
Hyperlink | Hyperlink | Gives a tag (identified by the given address) that applies to the current document. |
up
| Hyperlink | Hyperlink | Provides a link to a document giving the context for 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. For link
elements, if the rel
attribute does not also
contain the keyword stylesheet
, it creates a hyperlink; but if it
does also contains the keyword stylesheet
, the alternate
keyword instead modifies the
meaning of the stylesheet
keyword in the way described for
that keyword, and the rest of this subsection doesn't apply.
The alternate
keyword indicates that the referenced document is 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>
If the alternate
keyword is used with the type
attribute set
to the value application/rss+xml
or the value application/atom+xml
, then the user agent must treat the
link as it would if it had the feed
keyword specified as well.
The alternate
link 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.
archives
"The archives
keyword may be used with link
, a
, and area
elements. For link
elements, it creates a
hyperlink.
The archives
keyword indicates that the referenced document describes a collection of
records, documents, or other materials of historical interest.
A blog's index page could link to an index of the blog's
past posts with rel="archives"
.
Synonyms: For historical reasons, user agents must also
treat the keyword "archive
" like the archives
keyword.
author
"The author
keyword
may be used with link
, a
, and area
elements. For link
elements, it creates a
hyperlink.
For a
and area
elements, the author
keyword indicates that the referenced
document provides further information about the author of the section that
the element defining the hyperlink applies
to.
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:
URI 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.
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> ...
contact
"The contact
keyword may be used with link
, a
, and area
elements. For link
elements, it creates a
hyperlink.
For a
and area
elements, the contact
keyword indicates that the referenced
document provides further contact information for the section that the
element defining the hyperlink applies to.
User agents must treat any hyperlink in an address
element as having the contact
link type
specified.
For link
elements, the contact
keyword indicates
that the referenced document provides further contact information for the
page as a whole.
external
"The external
keyword may be used with a
and area
elements.
The external
keyword indicates that the link is leading to a document that is not part
of the site that the current document forms a part of.
feed
"The feed
keyword may be
used with link
, a
, and area
elements. For link
elements, it creates a
hyperlink.
The feed
keyword
indicates that the referenced document is a syndication feed. If the alternate
link type is
also specified, then the feed is specifically the feed for the current
document; otherwise, the feed is just a syndication feed, not necessarily
associated with a particular Web page.
The first link
, a
, or area
element
in the document (in tree order) that creates a hyperlink with the link
type feed
must be treated
as the default syndication feed for the purposes of feed autodiscovery.
The feed
keyword is implied by the alternate
link type in certain cases (q.v.).
The following two link
elements are
equivalent: both give the syndication feed for the current page:
<link rel="alternate" type="application/atom+xml" href="data.xml">
<link rel="feed alternate" 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="feed">Recently Visited Planets</a></li> <li><a href="known-bad-planets.xml" rel="feed">Known Bad Planets</a></li> <li><a href="unexplored-planets.xml" rel="feed">Unexplored Planets</a></li> </ul>
help
"The help
keyword may be
used with link
, a
, and area
elements. For link
elements, it 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.
icon
"The icon
keyword may be
used with link
elements, for which it
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 media
attribute.
license
"The license
keyword may be used with link
, a
, and area
elements. For link
elements, it creates a
hyperlink.
The license
keyword indicates that the referenced document provides the copyright
license terms under which the current document is provided.
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.
The nofollow
keyword indicates that the link is not endorsed by the original author or
publisher of the page.
noreferrer
"The noreferrer
keyword may be used with a
and area
elements.
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
HTTP header (or equivalent for
other protocols) in the request.
pingback
"The pingback
keyword may be used with link
elements,
for which it creates an external resource link.
For the semantics of the pingback
keyword, see the Pingback 1.0
specification. [PINGBACK]
prefetch
"The prefetch
keyword may be used with link
elements,
for which it 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.
search
"The search
keyword
may be used with link
, a
, and area
elements. For link
elements, it 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, for which it 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.
sidebar
"The sidebar
keyword may be used with link
, a
, and area
elements. For link
elements, it creates a
hyperlink.
The sidebar
keyword indicates that the referenced document, if retrieved, is intended
to be shown in a secondary browsing context (if
possible), instead of in the current browsing
context.
A hyperlink element with with
the sidebar
keyword
specified is a sidebar
hyperlink.
tag
"The tag
keyword may be
used with link
, a
, and area
elements. For link
elements, it creates a
hyperlink.
The tag
keyword indicates
that the tag that the referenced document represents applies to
the current document.
Some documents form part of a hierarchical structure of documents.
A hierarchical structure of documents is one where each document can have various subdocuments. The document of which a document is a subdocument is said to be the document's parent. A document with no parent forms the top of the hierarchy.
A document may be part of multiple hierarchies.
index
"The index
keyword may
be used with link
, a
, and area
elements. For link
elements, it creates a
hyperlink.
The index
keyword
indicates that the document is part of a hierarchical structure, and that
the link is leading to the document that is the top of the hierarchy. It
conveys more information when used with the up
keyword (q.v.).
Synonyms: For historical reasons, user agents must also
treat the keywords "top
", "contents
", and "toc
" like the index
keyword.
up
"The up
keyword may be used
with link
, a
, and area
elements. For link
elements, it creates a
hyperlink.
The up
keyword indicates
that the document is part of a hierarchical structure, and that the link
is leading to the document that is the parent of the current document.
The up
keyword may be
repeated within a rel
attribute to indicate the hierarchical
distance from the current document to the referenced document. Each
occurance of the keyword represents one further level. If the index
keyword is also present,
then the number of up
keywords
is the depth of the current page relative to the top of the hierarchy.
If the page is part of multiple hierarchies, then they should be
described in different paragraphs. User agents must scope any interpretation
of the up
and index
keywords together
indicating the depth of the hierarchy to the paragraph in which the link finds itself, if any, or
to the document otherwise.
When two links have both the up
and index
keywords specified together in the same
scope and contradict each other by having a different number of up
keywords, the link with the
greater number of up
keywords
must be taken as giving the depth of the document.
This can be used to mark up a navigation style sometimes known as breadcrumbs. In the following example, the current page can be reached via two paths.
<nav> <p> <a href="/" rel="index up up up">Main</a> > <a href="/products/" rel="up up">Products</a> > <a href="/products/dishwashers/" rel="up">Dishwashers</a> > <a>Second hand</a> </p> <p> <a href="/" rel="index up up">Main</a> > <a href="/second-hand/" rel="up">Second hand</a> > <a>Dishwashers</a> </p> </nav>
The relList
DOM attribute (e.g. on the a
element) does not currently represent multiple
up
keywords (the interface
hides duplicates).
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.
first
"The first
keyword may
be used with link
, a
, and area
elements. For link
elements, it creates a
hyperlink.
The first
keyword
indicates that the document is part of a sequence, and that the link is
leading to the document that is the first logical document in the
sequence.
Synonyms: For historical reasons, user agents must also
treat the keywords "begin
" and "start
" like the first
keyword.
last
"The last
keyword may be
used with link
, a
, and area
elements. For link
elements, it creates a
hyperlink.
The last
keyword
indicates that the document is part of a sequence, and that the link is
leading to the document that is the last logical document in the sequence.
Synonyms: For historical reasons, user agents must also
treat the keyword "end
" like the last
keyword.
next
"The next
keyword may be
used with link
, a
, and area
elements. For link
elements, it 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. For link
elements, it 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.
Other than the types defined above, only types defined as extensions in
the WHATWG Wiki
RelExtensions page may be used with the rel
attribute on link
, a
, and area
elements. [WHATWGWIKI]
Anyone is free to edit the WHATWG Wiki RelExtensions 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).
link
One of the following:
link
elements.
link
element; it creates a hyperlink link.
link
element; it creates a external resource link.
a
and area
One of the following:
a
and area
elements.
a
and
area
elements.
A short 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 must not use the values defined to be synonyms, they are only intended to allow user agents to support legacy content.
One of the following:
link
" and "Effect on... a
and area
"
information should be set to "not allowed".
If a keyword is added with the "proposal" 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 "proposal" status and found to be harmful, then it should be changed to "rejected" status, and its "Effect on..." information should be changed accordingly.
Conformance checkers must use the information given on the WHATWG Wiki RelExtensions page to establish if a value not explicitly defined in this specification is allowed or not. 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 "proposal" status.
This specification does not define how new values will get approved. It is expected that the Wiki will have a community that addresses this.
An interface that has a complement of URI decomposition attributes will have seven attributes with the following definitions:
attribute DOMString protocol; attribute DOMString host; attribute DOMString hostname; attribute DOMString port; attribute DOMString pathname; attribute DOMString search; attribute DOMString hash;
The attributes defined to be URI decomposition attributes must act as described for the attributes with the same corresponding names in this section.
In addition, an interface with a complement of URI decomposition attributes will define an input, which is a URI that the attributes act on, and a common setter action, which is a set of steps invoked when any of the attributes' setters are invoked.
The seven URI decomposition attributes have similar requirements.
On getting, if the input fulfills the condition given in the "getter condition" column corresponding to the attribute in the table below, the user agent must return the part of the input URI given in the "component" column, with any prefixes specified in the "prefix" column appropriately added to the start of the string and any suffixes specified in the "suffix" column appropriately added to the end of the string. Otherwise, the attribute must return the empty string.
On setting, the new value must first be mutated as described by the "setter preprocessor" column, then mutated by %-escaping any characters in the new value that are not valid in the relevant component as given by the "component" column. Then, if the resulting new value fulfills the condition given in the "setter condition" column, the user agent must make a new string output by replacing the component of the URI given by the "component" column in the input URI with the new value; otherwise, the user agent must let output be equal to the input. Finally, the user agent must invoke the common setter action with the value of output.
The rules for parsing and constructing URIs are described in RFC 3986 and RFC 3987. [RFC3986] [RFC3987]
| Attribute | Component | Getter Condition | Prefix | Suffix | Setter Preprocessor | Setter Condition |
|---|---|---|---|---|---|---|
protocol
| <scheme> | — | — | U+003A COLON (": ")
| Remove all trailing U+003A COLON (": ")
characters
| The new value is not the empty string |
host
| <hostport> | input is hierarchical and uses a server-based naming authority | — | — | — | — |
hostname
| <host>/<ihost> | input is hierarchical and uses a server-based naming authority | — | — | Remove all leading U+002F SOLIDUS ("/ ")
characters
| — |
port
| <port> | input is hierarchical and uses a server-based naming authority | — | — | Remove any characters in the new value that are not in the range U+0030 DIGIT ZERO .. U+0039 DIGIT NINE | The new value is not the empty string |
pathname
| <abs_path> | input is hierarchical | — | — | If it has no leading U+002F SOLIDUS ("/ ")
character, prepend a U+002F SOLIDUS ("/ ")
character to the new value
| — |
search
| <query> | input is hierarchical | U+003F QUESTION MARK ("? ")
| — | Remove one leading U+003F QUESTION MARK ("? ")
character, if any
| — |
hash
| <fragment> | Fragment identifier is longer than zero characters | U+0023 NUMBER SIGN ("# ")
| — | Remove one leading U+0023 NUMBER SIGN ("# ")
character, if any
| — |
The <hostport> component is defined as being the <host>/<ihost> component, followed by a colon and the <port> component, but with the colon and <port> component omitted if the given port matches the default port for the protocol given by the <scheme> component.
This section describes various features that allow authors to enable users to edit documents and parts of documents interactively.
This section is non-normative.
Would be nice to explain how these features work together.
contenteditable
attributeThe contenteditable
attribute is
a common attribute. User agents must support this attribute on all HTML elements.
The contenteditable
attribute is an enumerated attribute whose keywords are the empty
string, true
, and false
. The
empty string and the true
keyword map to the
true state. The false
keyword maps to the
false state, which is also the invalid value default.
There is no missing value default.
If an HTML element
has a contenteditable
attribute set to the
true state, or if its nearest ancestor HTML element with the contenteditable
attribute set has its
attribute set to the true state, or if it has no ancestors with the contenteditable
attribute set but the
Document
has designMode
enabled, then the UA must treat
the element as editable (as described below).
Otherwise, either the HTML element has a contenteditable
attribute set to the
false state, or its nearest ancestor HTML element with the contenteditable
attribute set is not
editable, or it has no ancestor with the
contenteditable
attribute set and the
Document
itself has designMode
disabled, and the element is thus
not editable.
The contentEditable
DOM
attribute, on getting, must return the string "inherit
" if the content attribute isn't set, "true
" if the attribute is set and has the true state, and
"false
" otherwise. On setting, if the new value is
case-insensitively equal to the string "inherit
" then the content attribute must be removed, if
the new value is case-insensitively equal to the
string "true
then the content attribute must be set
to the string "true
, if the new value is
case-insensitively equal to the string "false
then the content attribute must be set to the string
"false
, and otherwise the attribute setter must
raise a SYNTAX_ERR
exception.
If an element is editable and its parent element is not, or if an element is editable and it has no parent element, then the element is an editing host. Editable elements can be nested. User agents must make editing hosts focusable (which typicially means they enter the tab order). An editing host can contain non-editable sections, these are handled as described below. An editing host can contain non-editable sections that contain further editing hosts.
When an editing host has focus, it must have a caret position that specifies where the current editing position is. It may also have a selection.
How the caret and selection are represented depends entirely on the UA.
There are several actions that the user agent should allow the user to perform while the user is interacting with an editing host. How exactly each action is triggered is not defined for every action, but when it is not defined, suggested key bindings are provided to guide implementors.
User agents must allow users to move the caret to any position within
an editing host, even into nested editable elements. This could be
triggered as the default action of keydown
events with various key identifiers
and as the default action of mousedown
events.
User agents must allow users to change the
selection within an editing host, even into nested editable
elements. This could be triggered as the default action of keydown
events with various key identifiers
and as the default action of mousedown
events.
This action must be triggered as the default action of a textInput
event, and may be triggered by
other commands as well. It must cause the user agent to insert the
specified text (given by the event object's data
attribute in the case of the textInput
event) at the caret.
If the caret is positioned somewhere where phrasing content is not allowed (e.g. inside an
empty ol
element), then the user agent
must not insert the text directly at the caret position. In such cases
the behaviour is UA-dependent, but user agents must not, in response to
a request to insert text, generate a DOM that is less conformant than
the DOM prior to the request.
User agents should allow users to insert new paragraphs into elements that contains only content other than paragraphs.
UAs should offer a way for the user to request that the current
paragraph be broken at the caret, e.g. as the default action of a keydown
event whose identifier is the "Enter"
key and that has no modifiers set.
The exact behaviour is UA-dependent, but user agents must not, in response to a request to break a paragraph, generate a DOM that is less conformant than the DOM prior to the request.
UAs should offer a way for the user to request an explicit line break
at the caret position without breaking the paragraph, e.g. as the
default action of a keydown
event whose
identifier is the "Enter" key and that has a shift modifier set. Line
separators are typically found within a poem verse or an address. To
insert a line break, the user agent must insert a br
element.
If the caret is positioned somewhere where phrasing content is not allowed (e.g. in an empty
ol
element), then the user agent must not
insert the br
element directly at the
caret position. In such cases the behaviour is UA-dependent, but user
agents must not, in response to a request to insert a line separator,
generate a DOM that is less conformant than the DOM prior to the
request.
UAs should offer a way for the user to delete text and elements, e.g.
as the default action of keydown
events
whose identifiers are "U+0008" or "U+007F".
Five edge cases in particular need to be considered carefully when implementing this feature: backspacing at the start of an element, backspacing when the caret is immediately after an element, forward-deleting at the end of an element, forward-deleting when the caret is immediately before an element, and deleting a selection whose start and end points do not share a common parent node.
In any case, the exact behaviour is UA-dependent, but user agents must not, in response to a request to delete text or an element, generate a DOM that is less conformant than the DOM prior to the request.
UAs should offer a way for the user to mark text as having stress emphasis and as being important, and may offer the user the ability to mark text and paragraphs with other semantics.
UAs should similarly offer a way for the user to insert empty semantic
elements (such as, again, em
, strong
, and others) to subsequently fill by
entering text manually.
UAs should also offer a way to remove those semantics from marked up text, and to remove empty semantic element that have been inserted.
The exact behaviour is UA-dependent, but user agents must not, in response to a request to wrap semantics around some text or to insert or remove a semantic element, generate a DOM that is less conformant than the DOM prior to the request.
UAs should offer a way for the user to move images and other non-editable parts around the content within an editing host. This may be done using the drag and drop mechanism. User agents must not, in response to a request to move non-editable elements nested inside editing hosts, generate a DOM that is less conformant than the DOM prior to the request.
When an editable form control is edited, the
changes must be reflected in both its current value and its
default value. For input
elements this means updating the
defaultValue
DOM attribute as
well as the value
DOM attribute; for
select
elements it means updating the option
elements' defaultSelected
DOM attribute as well as the selected
DOM attribute; for
textarea
elements this means updating the defaultValue
DOM attribute as
well as the value
DOM attribute.
(Updating the default*
DOM attributes causes
content attributes to be updated as well.)
User agents may perform several commands per user request; for example if the user selects a block of text and hits Enter, the UA might interpret that as a request to delete the content of the selection followed by a request to break the paragraph at that position.
Documents have a designMode
, which can be
either enabled or disabled.
The designMode
DOM attribute on the
Document
object takes takes two values, "on
" and "off
". When it is set, the
new value must be case-insensitively
compared to these two values. If it matches the "on
"
value, then designMode
must be enabled, and if it
matches the "off
" value, then designMode
must be disabled. Other values must be ignored.
When designMode
is enabled, the DOM attribute
must return the value "on
", and when it is disabled,
it must return the value "off
".
The last state set must persist until the document is destroyed or the
state is changed. Initially, documents must have their designMode
disabled.
Enabling designMode
causes scripts in general to be
disabled and the document to become editable.
When the Document
has designMode
enabled, event listeners registered on the document or any elements owned
by the document must do nothing.
This section defines an event-based drag-and-drop mechanism.
This specification does not define exactly what a drag-and-drop operation actually is.
On a visual medium with a pointing device, a drag operation could be the
default action of a mousedown
event
that is followed by a series of mousemove
events, and the drop could be
triggered by the mouse being released.
On media without a pointing device, the user would probably have to explicitly indicate his intention to perform a drag-and-drop operation, stating what he wishes to drag and what he wishes to drop, respectively.
However it is implemented, drag-and-drop operations must have a starting point (e.g. where the mouse was clicked, or the start of the selection or element that was selected for the drag), may have any number of intermediate steps (elements that the mouse moves over during a drag, or elements that the user picks as possible drop points as he cycles through possibilities), and must either have an end point (the element above which the mouse button was released, or the element that was finally selected), or be canceled. The end point must be the last element selected as a possible drop point before the drop occurs (so if the operation is not canceled, there must be at least one element in the middle step).
DragEvent
and DataTransfer
interfacesThe drag-and-drop processing model involves several events. They all use
the DragEvent
interface.
interface DragEvent : UIEvent { readonly attribute DataTransfer dataTransfer; void initDragEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in AbstractView viewArg, in long detailArg, in DataTransfer dataTransferArg); void initDragEventNS(in DOMString namespaceURIArg, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in AbstractView viewArg, in long detailArg, in DataTransfer dataTransferArg); };
We should have modifier key information in here too (shift/ctrl, etc), like with mouse events and like with the context menu event.
The initDragEvent()
and
initDragEventNS()
methods must initialise the event in a manner analogous to the
similarly-named methods in the DOM3 Events interfaces. [DOM3EVENTS]
The dataTransfer
attribute
of the DragEvent
interface
represents the context information for the event.
When a DragEvent
object is
created, a new DataTransfer
object must be created and assigned to the dataTransfer
context information field of
the event object.
interface DataTransfer { attribute DOMString dropEffect; attribute DOMString effectAllowed; void clearData(in DOMString format); void setData(in DOMString format, in DOMString data); DOMString getData(in DOMString format); void setDragImage(in Element image, in long x, in long y); void addElement(in Element element); };
DataTransfer
objects can
conceptually contain various kinds of data.
When a DragEvent
event object is
initialised, the DataTransfer
object created for the event's dataTransfer
member must be initialised as
follows:
DataTransfer
object must
initially contain no data, no elements, and have no associated image.
DataTransfer
object's
effectAllowed
attribute must be set to
"uninitialized
".
dropEffect
attribute must be set to "none
".
The dropEffect
attribute
controls the drag-and-drop feedback that the user is given during a
drag-and-drop operation.
The attribute must ignore any attempts to set it to a value other than
none
, copy
, link
, and move
. On getting, the
attribute must return the last of those four values that it was set to.
The effectAllowed
attribute is used in the drag-and-drop processing model to initialise the
dropEffect
attribute during the dragenter
and dragover
events.
The attribute must ignore any attempts to set it to a value other than
none
, copy
, copyLink
, copyMove
, link
, linkMove
, move
, all
, and uninitialized
. On getting, the attribute must return the
last of those values that it was set to.
DataTransfer
objects can hold
pieces of data, each associated with a unique format. Formats are
generally given by MIME types, with some values special-cased for legacy
reasons.
The clearData(format)
method must clear the DataTransfer
object of any data
associated with the given format. If format is the value "Text
", then it
must be treated as "text/plain
". If the format is "URL
", then it must be
treated as "text/uri-list
".
The setData(format, data)
method must
add data to the data stored in the DataTransfer
object, labelled as being of
the type format. This must replace any previous data
that had been set for that format. If format is the
value "Text
", then it must be treated as "text/plain
". If the format is "URL
", then it must be treated as "text/uri-list
".
The getData(format)
method must return the data that is
associated with the type format, if any, and must
return the empty string otherwise. If format is the
value "Text
", then it must be treated as "text/plain
". If the format is "URL
", then the data associated with the "text/uri-list
" format must be parsed as appropriate for
text/uri-list
data, and the first URI from the list
must be returned. If there is no data with that format, or if there is but
it has no URIs, then the method must return the empty string. [RFC2483]
The setDragImage(element, x, y)
method sets which element to use to generate the drag feedback. The element argument can be any Element
; if it is
an img
element, then the user agent should
use the element's image (at its intrinsic size) to generate the feedback,
otherwise the user agent should base the feedback on the given element
(but the exact mechanism for doing so is not specified).
The addElement(element)
method is an alternative way of
specifying how the user agent is to render
the drag feedback. It adds an element to the DataTransfer
object.
The following events are involved in the drag-and-drop model. Whenever
the processing model described below causes one of these events to be
fired, the event fired must use the DragEvent
interface defined above, must have
the bubbling and cancelable behaviours given in the table below, and must
have the context information set up as described after the table, with the
view
attribute set to the view with
which the user interacted to trigger the drag-and-drop event, and the
detail
attribute set to zero.
| Event Name | Target | Bubbles? | Cancelable? | dataTransfer
| effectAllowed
| dropEffect
| Default Action |
|---|---|---|---|---|---|---|---|
dragstart
| Source node | ✓ Bubbles | ✓ Cancelable | Contains source node unless a selection is being dragged, in which case it is empty | uninitialized
| none
| Initiate the drag-and-drop operation |
drag
| Source node | ✓ Bubbles | ✓ Cancelable | Empty | Same as last event | none
| Continue the drag-and-drop operation |
dragenter
| Immediate user selection or the body element | ✓ Bubbles | ✓ Cancelable | Empty | Same as last event | Based on
effectAllowed value
| Reject immediate user selection as potential target element |
dragleave
| Previous target element | ✓ Bubbles | — | Empty | Same as last event | none
| None |
dragover
| Current target element | ✓ Bubbles | ✓ Cancelable | Empty | Same as last event | Based on
effectAllowed value
| Reset the current drag operation to "none" |
drop
| Current target element | ✓ Bubbles | ✓ Cancelable | getData() returns data set in dragstart event
| Same as last event | Current drag operation | Varies |
dragend
| Source node | ✓ Bubbles | — | Empty | Same as last event | Current drag operation | Varies |
The dataTransfer
object's contents are empty
except for dragstart
events and drop
events, for which the
contents are set as described in the processing model, below.
The effectAllowed
attribute must be set to
"uninitialized
" for dragstart
events, and to whatever value the
field had after the last drag-and-drop event was fired for all other
events (only counting events fired by the user agent for the purposes of
the drag-and-drop model described below).
The dropEffect
attribute must be set to "none
" for dragstart
, drag
, and dragleave
events (except when stated
otherwise in the algorithms given in the sections below), to the value
corresponding to the current drag operation for
drop
and dragend
events, and to a
value based on the effectAllowed
attribute's value and to
the drag-and-drop source, as given by the following table, for the
remaining events (dragenter
and dragover
):
effectAllowed
| dropEffect
|
|---|---|
none
| none
|
copy , copyLink , copyMove , all
| copy
|
link , linkMove
| link
|
move
| move
|
uninitialized when what is being dragged is a
selection from a text field
| move
|
uninitialized when what is being dragged is a
selection
| copy
|
uninitialized when what is being dragged is an
a element with an href
attribute
| link
|
| Any other case | copy
|
When the user attempts to begin a drag operation, the user agent must
first determine what is being dragged. If the drag operation was invoked
on a selection, then it is the selection that is being dragged. Otherwise,
it is the first element, going up the ancestor chain, starting at the node
that the user tried to drag, that has the DOM attribute draggable
set to
true. If there is no such element, then nothing is being dragged, the
drag-and-drop operation is never started, and the user agent must not
continue with this algorithm.
img
elements and a
elements with an href
attribute have their draggable
attribute
set to true by default.
If the user agent determines that something can be dragged, a dragstart
event must
then be fired.
If it is a selection that is being dragged, then this event must be fired on the node that the user started the drag on (typically the text node that the user originally clicked). If the user did not specify a particular node, for example if the user just told the user agent to begin a drag of "the selection", then the event must be fired on the deepest node that is a common ancestor of all parts of the selection.
We should look into how browsers do other types (e.g. Firefox apparently also adds text/html for internal drag and drop of a selection).
If it is not a selection that is being dragged, then the event must be fired on the element that is being dragged.
The node on which the event is fired is the source node. Multiple events are fired on this node during the course of the drag-and-drop operation.
If it is a selection that is being dragged, the dataTransfer
member of the event must be
created with no nodes. Otherwise, it must be created containing just the
source node. Script can use the addElement()
method to add further elements
to the list of what is being dragged.
If it is a selection that is being dragged, the dataTransfer
member of the event must have
the text of the selection added to it as the data associated with the
text/plain
format. Otherwise, if it is an img
element being dragged, then the value of the
element's src
DOM
attribute must be added, associated with the text/uri-list
format. Otherwise, if it is an a
element being dragged, then the value of the
element's href
DOM
attribute must be added, associated with the text/uri-list
format. Otherwise, no data is added to the
object by the user agent.
If the event is canceled, then the drag-and-drop operation must not occur; the user agent must not continue with this algorithm.
If it is not canceled, then the drag-and-drop operation must be initiated.
Since events with no event handlers registered are, almost by definition, never canceled, drag-and-drop is always available to the user if the author does not specifically prevent it.
The drag-and-drop feedback must be generated from the first of the following sources that is available:
setDragImage()
method of the dataTransfer
object of the dragstart
event, if
the method was called. In visual media, if this is used, the x and y arguments that were passed to
that method should be used as hints for where to put the cursor relative
to the resulting image. The values are expressed as distances in CSS
pixels from the left side and from the top side of the image
respectively. [CSS21]dataTransfer
object, both before the
event was fired, and during the handling of the event using the addElement()
method, if any such elements
were indeed added.
The user agent must take a note of the data that was placed in the dataTransfer
object. This data will be
made available again when the drop
event is fired.
From this point until the end of the drag-and-drop operation, device input events (e.g. mouse and keyboard events) must be suppressed. In addition, the user agent must track all DOM changes made during the drag-and-drop operation, and add them to its undo history as one atomic operation once the drag-and-drop operation has ended.
During the drag operation, the element directly indicated by the user as the drop target is called the immediate user selection. (Only elements can be selected by the user; other nodes must not be made available as drop targets.) However, the immediate user selection is not necessarily the current target element, which is the element currently selected for the drop part of the drag-and-drop operation. The immediate user selection changes as the user selects different elements (either by pointing at them with a pointing device, or by selecting them in some other way). The current target element changes when the immediate user selection changes, based on the results of event handlers in the document, as described below.
Both the current target element and the immediate user selection can be null, which means no target element is selected. They can also both be elements in other (DOM-based) documents, or other (non-Web) programs altogether. (For example, a user could drag text to a word-processor.) The current target element is initially null.
In addition, there is also a current drag operation, which can take on the values "none", "copy", "link", and "move". Initially it has the value "none". It is updated by the user agent as described in the steps below.
User agents must, every 350ms (±200ms), perform the following steps in sequence. (If the user agent is still performing the previous iteration of the sequence when the next iteration becomes due, the user agent must not execute the overdue iteration, effectively "skipping missed frames" of the drag-and-drop operation.)
First, the user agent must fire a drag
event at the source
node. If this event is canceled, the user agent must set the current drag operation to none (no drag operation).
Next, if the drag
event was not canceled and the user has not ended the drag-and-drop
operation, the user agent must check the state of the drag-and-drop
operation, as follows:
First, if the user is indicating a different immediate user selection than during the last iteration (or if this is the first iteration), and if this immediate user selection is not the same as the current target element, then the current target element must be updated, as follows:
If the new immediate user selection is null, or is in a non-DOM document or application, then set the current target element to the same value.
Otherwise, the user agent must fire a dragenter
event at the immediate user selection.
If the event is canceled, then the current target element must be set to the immediate user selection.
Otherwise, if the current target element
is not the body element, the user agent
must fire a dragenter
event at the body element, and the current target element must be set to the body element, regardless of whether that
event was canceled or not. (If the body
element is null, then the current target
element would be set to null too in this case, it wouldn't be
set to the Document
object.)
If the previous step caused the current target
element to change, and if the previous target element was not null
or a part of a non-DOM document, the user agent must fire a dragleave
event
at the previous target element.
If the current target element is a DOM
element, the user agent must fire a dragover
event at this current target element.
If the dragover
event is canceled, the current drag operation must be reset to "none".
Otherwise, the current drag operation must
be set based on the values the effectAllowed
and dropEffect
attributes of the dataTransfer
object had after the
event was handled, as per the following table:
effectAllowed
| dropEffect
| Drag operation |
|---|---|---|
uninitialized , copy ,
copyLink , copyMove , or
all
| copy
| "copy" |
uninitialized , link ,
copyLink , linkMove , or
all
| link
| "link" |
uninitialized , move ,
copyMove , linkMove , or
all
| move
| "move" |
| Any other case | "none" |
Then, regardless of whether the dragover
event was canceled or not, the
drag feedback (e.g. the mouse cursor) must be updated to match the current drag operation, as follows:
| Drag operation | Feedback |
|---|---|
| "copy" | Data will be copied if dropped here. |
| "link" | Data will be linked if dropped here. |
| "move" | Data will be moved if dropped here. |
| "none" | No operation allowed, dropping here will cancel the drag-and-drop operation. |
Otherwise, if the current target element is not a DOM element, the user agent must use platform-specific mechanisms to determine what drag operation is being performed (none, copy, link, or move). This sets the current drag operation.
Otherwise, if the user ended the drag-and-drop operation (e.g. by
releasing the mouse button in a mouse-driven drag-and-drop interface),
or if the drag
event
was canceled, then this will be the last iteration. The user agent must
execute the following steps, then stop looping.
If the current drag operation is none (no
drag operation), or, if the user ended the drag-and-drop operation by
canceling it (e.g. by hitting the Escape key), or if the current target element is null, then the drag
operation failed. If the current target
element is a DOM element, the user agent must fire a dragleave
event
at it; otherwise, if it is not null, it must use platform-specific
conventions for drag cancellation.
Otherwise, the drag operation was as success. If the current target element is a DOM element, the user
agent must fire a drop
event at it; otherwise, it must use
platform-specific conventions for indicating a drop.
When the target is a DOM element, the dropEffect
attribute of the event's
dataTransfer
object must be given the
value representing the current drag operation
(copy
, link
, or move
), and the object must be set up so that the getData()
method will return the data that was added during the dragstart
event.
If the event is canceled, the current drag
operation must be set to the value of the dropEffect
attribute of the event's
dataTransfer
object as it stood after
the event was handled.
Otherwise, the event is not canceled, and the user agent must perform the event's default action, which depends on the exact target as follows:
textarea
, or an input
element
with type="text"
)
text/plain
format, if any, into the text field in a
manner consistent with platform-specific conventions (e.g. inserting
it at the current mouse cursor position, or inserting it at the end
of the field).
Finally, the user agent must fire a dragend
event at the source node, with the dropEffect
attribute of the event's
dataTransfer
object being set to the
value corresponding to the current drag
operation.
The current drag operation can
change during the processing of the drop
event, if one was fired.
The event is not cancelable. After the event has been handled, the user agent must act as follows:
textarea
, or an input
element
with type="text"
), and a drop
event was fired in
the previous step, and the current drag
operation is "move", and the source of the drag-and-drop
operation is a selection in the DOM
textarea
, or an input
element
with type="text"
), and a drop
event was fired in
the previous step, and the current drag
operation is "move", and the source of the drag-and-drop
operation is a selection in a text field
The model described above is independent of which Document
object the nodes involved are from; the events must be fired as described
above and the rest of the processing model must be followed as described
above, irrespective of how many documents are involved in the operation.
If the drag is initiated in another application, the source node is not a DOM node, and the user agent must
use platform-specific conventions instead when the requirements above
involve the source node. User agents in this situation must act as if the
dragged data had been added to the DataTransfer
object when the drag
started, even though no dragstart
event was actually fired; user
agents must similarly use platform-specific conventions when deciding on
what drag feedback to use.
If a drag is started in a document but ends in another application, then the user agent must instead replace the parts of the processing model relating to handling the target according to platform-specific conventions.
In any case, scripts running in the context of the document must not be able to distinguish the case of a drag-and-drop operation being started or ended in another application from the case of a drag-and-drop operation being started or ended in another document from another domain.
draggable
attributeAll elements may have the draggable
content attribute set. The draggable
attribute
is an enumerated attribute. It has three states.
The first state is true and it has the keyword true
. The second state is false and it has the
keyword false
. The third state is auto; it
has no keywords but it is the missing value default.
The draggable
DOM attribute, whose value depends on the content attribute's in the way
described below, controls whether or not the element is draggable.
Generally, only text selections are draggable, but elements whose draggable
DOM
attribute is true become draggable as well.
If an element's draggable
content attribute has the state
true, the draggable
DOM attribute must return true.
Otherwise, if the element's draggable
content attribute has the state
false, the draggable
DOM attribute must return false.
Otherwise, the element's draggable
content attribute has the state
auto. If the element is an img
element, or, if the element is an a
element
with an href
content attribute, the draggable
DOM attribute must return true.
Otherwise, the draggable
DOM must return false.
If the draggable
DOM attribute is set to the value
false, the draggable
content attribute must be set to
the literal value false
. If the draggable
DOM
attribute is set to the value true, the draggable
content attribute must be set to
the literal value true
.
Copy-and-paste is a form of drag-and-drop: the "copy" part is equivalent to dragging content to another application (the "clipboard"), and the "paste" part is equivalent to dragging content from another application.
Select-and-paste (a model used by mouse operations in the X Window System) is equivalent to a drag-and-drop operation where the source is the selection.
When the user invokes a copy operation, the user agent must act as if the user had invoked a drag on the current selection. If the drag-and-drop operation initiates, then the user agent must act as if the user had indicated (as the immediate user selection) a hypothetical application representing the clipbroad. Then, the user agent must act as if the user had ended the drag-and-drop operation without canceling it. If the drag-and-drop operation didn't get canceled, the user agent should then follow the relevant platform-specific conventions for copy operations (e.g. updating the clipboard).
When the user invokes a cut operation, the user agent must act as if the user had invoked a copy operation (see the previous section), followed, if the copy was completed successfully, by a selection delete operation.
When the user invokes a clipboard paste operation, the user agent must
act as if the user had invoked a drag on a hypothetical application
representing the clipboard, setting the data associated with the drag as
the text from the keyboard (either as text/plain
or
text/uri-list
). If the contents of the clipboard cannot be
represented as text or URIs, then the paste operation must not have any
effect.
Then, the user agent must act as if the user had indicated (as the immediate user selection) the element with the keyboard focus, and then ended the drag-and-drop operation without canceling it.
When the user invokes a selection paste operation, the user agent must act as if the user had invoked a drag on the current selection, then indicated (as the immediate user selection) the element with the keyboard focus, and then ended the drag-and-drop operation without canceling it.
If the contents of the selection cannot be represented as text or URIs, then the paste operation must not have any effect.
User agents must not make the data added to the DataTransfer
object during the dragstart
event
available to scripts until the drop
event, because otherwise, if a user were to
drag sensitive information from one document to a second document,
crossing a hostile third document in the process, the hostile document
could intercept the data.
For the same reason, user agents must only consider a drop to be
successful if the user specifically ended the drag operation — if
any scripts end the drag operation, it must be considered unsuccessful
(canceled) and the drop
event must not be fired.
User agents should take care to not start drag-and-drop operations in response to script actions. For example, in a mouse-and-window environment, if a script moves a window while the user has his mouse button depressed, the UA would not consider that to start a drag. This is important because otherwise UAs could cause data to be dragged from sensitive sources and dropped into hostile documents without the user's consent.
There has got to be a better way of doing this, surely.
The user agent must associate an undo
transaction history with each HTMLDocument
object.
The undo transaction history is a list of entries. The entries are of two type: DOM changes and undo objects.
Each DOM changes entry in the undo transaction history consists of batches of one or more of the following:
Element
node.
Node
.HTMLDocument
object
(parentNode
, childNodes
).
Undo object entries consist of objects representing state that scripts running in the document are managing. For example, a Web mail application could use an undo object to keep track of the fact that a user has moved an e-mail to a particular folder, so that the user can undo the action and have the e-mail return to its former location.
Broadly speaking, DOM changes entries are handled by the UA in response to user edits of form controls and editing hosts on the page, and undo object entries are handled by script in response to higher-level user actions (such as interactions with server-side state, or in the implementation of a drawing tool).
 Seriously. It's a terrible API. Really bad. I hate it. Here are the requirements:
To manage undo object entries in the undo transaction history, the UndoManager
interface can be used:
interface UndoManager { unsigned long add(in DOMObject data, in DOMStrong title); void remove(in unsigned long index); void clearUndo(); void clearRedo(); DOMObject item(in unsigned long index); readonly attribute unsigned long length; readonly attribute unsigned long position; };
The undoManager
attribute of the
Window
interface must return the object
implementing the UndoManager
interface for that Window
object's
associated HTMLDocument
object.
In the ECMAScript DOM binding, objects implementing this interface must
also support being dereferenced using the square bracket notation, such
that dereferencing with an integer index is equivalent to invoking the
item()
method
with that index (e.g. undoManager[1]
returns the
same as undoManager.item(1)
).
UndoManager
objects represent
their document's undo transaction history.
Only undo object entries are visible with this
API, but this does not mean that DOM changes
entries are absent from the undo transaction
history.
The length
attribute must
return the number of undo object entries in the
undo transaction history.
The item(n)
method must return the nth undo object entry in the undo transaction history.
The undo transaction history has a current position. This is the position between two entries in the undo transaction history's list where the previous entry represents what needs to happen if the user invokes the "undo" command (the "undo" side, lower numbers), and the next entry represents what needs to happen if the user invokes the "redo" command (the "redo" side, higher numbers).
The position
attribute must
return the index of the undo object entry
nearest to the undo position, on the "redo" side.
If there are no undo object entries on the
"redo" side, then the attribute must return the same as the length
attribute. If there are no undo object entries
on the "undo" side of the undo position, the position
attribute returns zero.
Since the undo transaction
history contains both undo object entries
and DOM changes entries, but the position
attribute only returns indices relative to undo
object entries, it is possible for several "undo" or "redo" actions to
be performed without the value of the position
attribute changing.
The add(data, title)
method's
behaviour depends on the current state. Normally, it must insert the data object passed as an argument into the undo transaction history immediately before
the undo position, optionally remembering the
given title to use in the UI. If the method is called
during an undo operation,
however, the object must instead be added immediately after the
undo position.
If the method is called and there is neither an undo operation in progress nor a redo operation in progress then
any entries in the undo transaction
history after the undo position must be
removed (as if clearRedo()
had been called).
We could fire events when someone adds something to the undo history -- one event per undo object entry before the position (or after, during redo addition), allowing the script to decide if that entry should remain or not. Or something. Would make it potentially easier to expire server-held state when the server limitations come into play.
The remove(index)
method must remove the undo object entry with the specified index. If the index is less than zero or greater than or
equal to length
then the method must raise an
INDEX_SIZE_ERR
exception. DOM
changes entries are unaffected by this method.
The clearUndo()
method must
remove all entries in the undo transaction
history before the undo position, be they DOM changes entries or undo
object entries.
The clearRedo()
method must
remove all entries in the undo transaction
history after the undo position, be they DOM changes entries or undo
object entries.
Another idea is to have a way for scripts to say "startBatchingDOMChangesForUndo()" and after that the changes to the DOM go in as if the user had done them.
When the user invokes an undo operation, or when the execCommand()
method is called with the
undo
command, the
user agent must perform an undo operation.
If the undo position is at the start of the undo transaction history, then the user agent must do nothing.
If the entry immediately before the undo position is a DOM changes entry, then the user agent must remove that DOM changes entry, reverse the DOM changes that were listed in that entry, and, if the changes were reversed with no problems, add a new DOM changes entry (consisting of the opposite of those DOM changes) to the undo transaction history on the other side of the undo position.
If the DOM changes cannot be undone (e.g. because the DOM state is no longer consistent with the changes represented in the entry), then the user agent must simply remove the DOM changes entry, without doing anything else.
If the entry immediately before the undo
position is an undo object entry, then the
user agent must first remove that undo object
entry from the undo transaction history,
and then must fire an undo
event on the Document
object,
using the undo object entry's associated undo
object as the event's data.
Any calls to add()
while the event is being handled will be
used to populate the redo history, and will then be used if the user
invokes the "redo" command to undo his undo.
When the user invokes a redo operation, or when the execCommand()
method is called with the
redo
command, the
user agent must perform a redo operation.
This is mostly the opposite of an undo operation, but the full definition is included here for completeness.
If the undo position is at the end of the undo transaction history, then the user agent must do nothing.
If the entry immediately after the undo position is a DOM changes entry, then the user agent must remove that DOM changes entry, reverse the DOM changes that were listed in that entry, and, if the changes were reversed with no problems, add a new DOM changes entry (consisting of the opposite of those DOM changes) to the undo transaction history on the other side of the undo position.
If the DOM changes cannot be redone (e.g. because the DOM state is no longer consistent with the changes represented in the entry), then the user agent must simply remove the DOM changes entry, without doing anything else.
If the entry immediately after the undo position
is an undo object entry, then the user agent
must first remove that undo object entry from
the undo transaction history, and then
must fire a redo
event
on the Document
object, using the undo
object entry's associated undo object as the event's data.
UndoManagerEvent
interface and the
undo
and redo
eventsinterface UndoManagerEvent : Event {
readonly attribute DOMObject data;
void initUndoManagerEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMObject dataArg);
void initUndoManagerEventNS(in DOMString namespaceURIArg, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMObject dataArg);
};
The initUndoManagerEvent()
and initUndoManagerEventNS()
methods must initialise the event in a manner analogous to the
similarly-named methods in the DOM3 Events interfaces. [DOM3EVENTS]
The data
attribute
represents the undo object for the event.
The undo
and redo
events do not bubble,
cannot be canceled, and have no default action. When the user agent fires
one of these events it must use the UndoManagerEvent
interface, with the
data
field containing the relevant undo object.
How user agents present the above conceptual model to the user is not defined. The undo interface could be a filtered view of the undo transaction history, it could manipulate the undo transaction history in ways not described above, and so forth. For example, it is possible to design a UA that appears to have separate undo transaction histories for each form control; similarly, it is possible to design systems where the user has access to more undo information than is present in the offical (as described above) undo transaction history (such as providing a tree-based approach to document state). Such UI models should be based upon the single undo transaction history described in this section, however, such that to a script there is no detectable difference.
The execCommand(commandId, doShowUI, value)
method on the HTMLDocument
interface allows scripts to
perform actions on the current selection or at the current caret position.
Generally, these commands would be used to implement editor UI, for
example having a "delete" button on a toolbar.
There are three variants to this method, with one, two, and three arguments respectively. The doShowUI and value parameters, even if specified, are ignored unless otherwise stated.
In this specification, in fact, the doShowUI parameter is always ignored, regardless of its value. It is included for historical reasons only.
When any of these methods are invoked, user agents must act as described in the list below.
For actions marked "editing hosts only", if the selection is not entirely within an editing host, of if there is no selection and the caret is not inside an editing host, then the user agent must do nothing.
undo
redo
selectAll
unselect
The user agent must change the selection so that nothing is selected.
We need some sort of way in which the user can make a selection without risk of script clobbering it.
superscript
sup
element (or unwrapped, or, if
there is no selection, have that semantic inserted or removed — the
exact behaviour is UA-defined).
subscript
sub
element (or,
again, unwrapped, or have that semantic inserted or removed, as defined
by the UA).
formatBlock
Editing hosts only. This command changes the semantics of the blocks containing the selection.
If there is no selection, then, where in the description below refers to the selection, the user agent must act as if the selection was an empty range at the caret position.
If the value parameter is not specified or has a value other than one of the following literal strings:
<address>
<aside>
<h1>
<h2>
<h3>
<h4>
<h5>
<h6>
<nav>
<p>
<pre>
...then the user agent must do nothing.
Otherwise, the user agent must, for every position in the selection,
take the furthest prose content ancestor element
of that position that contains only phrasing
content, and, if that element is a descendant of the editing host,
rename it (as if the Element.renameNode()
method
had been used) according to the value, by stripping
the leading <
character and the trailing
>
character and using the rest as the new tag name,
using the HTML namespace.
delete
forwardDelete
insertLineBreak
insertParagraph
insertText
vendorID-customCommandID
vendorID-customCommandID
so as to prevent clashes between
extensions from different vendors and future additions to this
specification.
Every browsing context has a selection. The selection can be empty, and the selection can have more than one range (a disjointed selection). The user should be able to change the selection. User agents are not required to let the user select more than one range, and may collapse multiple ranges in the selection to a single range when the user interacts with the selection. (But, of course, the user agent may let the user create selections with multiple ranges.)
This one selection must be shared by all the content of the browsing context (though not by nested browsing contexts), including any editing hosts in the document. (Editing hosts that are not inside a document cannot have a selection.)
If the selection is empty (collapsed, so that it has only one segment and that segment's start and end points are the same) then the selection's position should equal the caret position. When the selection is not empty, this specification does not define the caret position; user agents should follow platform conventions in deciding whether the caret is at the start of the selection, the end of the selection, or somewhere else.
On some platforms (such as those using Wordstar editing conventions), the caret position is totally independent of the start and end of the selection, even when the selection is empty. On such platforms, user agents may ignore the requirement that the cursor position be linked to the position of the selection altogether.
Mostly for historical reasons, in addition to the browsing context's selection, each textarea
and
input
element has an independent selection. These are the
text field
selections.
The datagrid
and
select
elements also have selections, indicating which items
have been picked by the user. These are not discussed in this section.
This specification does not specify how selections are
presented to the user. The Selectors specification, in conjunction with
CSS, can be used to style text selections using the ::selection
pseudo-element. [SELECTORS] [CSS21]
The getSelection()
method on the
Window
interface must return the
Selection
object representing the selection of that Window
object's browsing
context.
For historical reasons, the getSelection()
method
on the HTMLDocument
interface
must return the same Selection
object.
interface Selection { readonly attribute Node anchorNode; readonly attribute long anchorOffset; readonly attribute Node focusNode; readonly attribute long focusOffset; readonly attribute boolean isCollapsed; void collapse(in Node parentNode, in long offset); void collapseToStart(); void collapseToEnd(); void selectAllChildren(in Node parentNode); void deleteFromDocument(); readonly attribute long rangeCount; Range getRangeAt(in long index); void addRange(in Range range); void removeRange(in Range range); void removeAllRanges(); DOMString toString(); };
The Selection
interface is
represents a list of Range
objects. The first item in the
list has index 0, and the last item has index count-1,
where count is the number of ranges in the list. [DOM2RANGE]
All of the members of the Selection
interface are defined in terms of
operations on the Range
objects represented by this object.
These operations can raise exceptions, as defined for the
Range
interface; this can therefore result in the members of
the Selection
interface raising
exceptions as well, in addition to any explicitly called out below.
The anchorNode
attribute
must return the value returned by the startContainer
attribute of the last Range
object in the list, or null if
the list is empty.
The anchorOffset
attribute
must return the value returned by the startOffset
attribute of the last Range
object in the list, or 0 if the
list is empty.
The focusNode
attribute must
return the value returned by the endContainer
attribute of the last Range
object in the list, or null if
the list is empty.
The focusOffset
attribute
must return the value returned by the endOffset
attribute of the last Range
object in the list, or 0 if the
list is empty.
The isCollapsed
attribute
must return true if there are zero ranges, or if there is exactly one
range and its collapsed
attribute is itself true.
Otherwise it must return false.
The collapse(parentNode, offset)
method
must raise a WRONG_DOCUMENT_ERR
DOM exception if parentNode's ownerDocument
is not the
HTMLDocument
object with which
the Selection
object is associated.
Otherwise it is, and the method must remove all the ranges in the Selection
list, then create a new
Range
object, add it to the list, and invoke its setStart()
and setEnd()
methods with
the parentNode and offset values
as their arguments.
The collapseToStart()
method must raise an INVALID_STATE_ERR
DOM exception if there
are no ranges in the list. Otherwise, it must invoke the collapse()
method with the startContainer
and startOffset
values of the first Range
object
in the list as the arguments.
The collapseToEnd()
method must raise an INVALID_STATE_ERR
DOM exception if there
are no ranges in the list. Otherwise, it must invoke the collapse()
method with the endContainer
and endOffset
values of the last Range
object in
the list as the arguments.
The selectAllChildren(parentNode)
method must invoke the collapse()
method with the parentNode value as the first argument
and 0 as the second argument, and must then invoke the selectNodeContents()
method on the first (and only) range
in the list with the parentNode value as the argument.
The deleteFromDocument()
method must invoke the deleteContents()
method on
each range in the list, if any, from first to last.
The rangeCount
attribute
must return the number of ranges in the list.
The getRangeAt(index)
method must return the indexth range in the list. If index is
less than zero or greater or equal to the value returned by the rangeCount
attribute, then the method must raise an INDEX_SIZE_ERR
DOM
exception.
The addRange(range)
method must add the given range Range object to the list of selections, at the end
(so the newly added range is the new last range). Duplicates are not
prevented; a range may be added more than once in which case it appears in
the list more than once, which (for example) will cause toString()
to
return the range's text twice.
The removeRange(range)
method must remove the first occurrence
of range in the list of ranges, if it appears at all.
The removeAllRanges()
method must remove all the ranges from the list of ranges, such that the
rangeCount
attribute returns 0 after the
removeAllRanges()
method is invoked
(and until a new range is added to the list, either through this interface
or via user interaction).
The toString()
method must
return a concatenation of the results of invoking the toString()
method of the Range
object on each
of the ranges of the selection, in the order they appear in the list
(first to last).
In language bindings where this is supported, objects implementing the
Selection
interface must stringify
to the value returned by the object's toString()
method.
In the following document fragment, the emphasised parts indicate the selection.
<p>The cute girl likes the <cite>Oxford English Dictionary</cite>.</p>
If a script invoked window.getSelection().toString()
, the return value would
be "the Oxford English
".
The Selection
interface has no relation to the DataGridSelection
interface.
When we define HTMLTextAreaElement and HTMLInputElement we will have to add the IDL given below to both of their IDLs.
The input
and textarea
elements define four
members in their DOM interfaces for handling their text selection:
void select(); attribute unsigned long selectionStart; attribute unsigned long selectionEnd; void setSelectionRange(in unsigned long start, in unsigned long end);
These methods and attributes expose and control the selection of
input
and textarea
text fields.
The select()
method must
cause the contents of the text field to be fully selected.
The selectionStart
attribute must, on getting, return the offset (in logical order) to the
character that immediately follows the start of the selection. If there is
no selection, then it must return the offset (in logical order) to the
character that immediately follows the text entry cursor.
On setting, it must act as if the setSelectionRange()
method had been
called, with the new value as the first argument, and the current value of
the selectionEnd
attribute as the second
argument, unless the current value of the selectionEnd
is less than the new value,
in which case the second argument must also be the new value.
The selectionEnd
attribute must, on getting, return the offset (in logical order) to the
character that immediately follows the end of the selection. If there is
no selection, then it must return the offset (in logical order) to the
character that immediately follows the text entry cursor.
On setting, it must act as if the setSelectionRange()
method had been
called, with the current value of the selectionStart
attribute as the first
argument, and new value as the second argument.
The setSelectionRange(start, end)
method must
set the selection of the text field to the sequence of characters starting
with the character at the startth position (in logical
order) and ending with the character at the (end-1)th position. Arguments greater than the length
of the value in the text field must be treated as pointing at the end of
the text field. If end is less than or equal to start then the start of the selection and the end of the
selection must both be placed immediately before the character with offset
end. In UAs where there is no concept of an empty
selection, this must set the cursor to be just before the character with
offset end.
To obtain the currently selected text, the following JavaScript suffices:
var selectionText = control.value.substring(control.selectionStart, control.selectionEnd);
...where control is the input
or
textarea
element.
Characters with no visible rendering, such as U+200D ZERO WIDTH JOINER, still count as characters. Thus, for instance, the selection can include just an invisible character, and the text insertion cursor can be placed to one side or another of such a character.
When these methods and attributes are used with input
elements that are not displaying simple text fields, they must raise an
INVALID_STATE_ERR
exception.
Messages in cross-document messaging and,
by default, in server-sent DOM events, use the
message
event.
The following interface is defined for this event:
interface MessageEvent : Event { readonly attribute DOMString data; readonly attribute DOMString domain; readonly attribute DOMString uri; readonly attribute Window source; void initMessageEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString dataArg, in DOMString domainArg, in DOMString uriArg, in Window sourceArg); void initMessageEventNS(in DOMString namespaceURI, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString dataArg, in DOMString domainArg, in DOMString uriArg, in Window sourceArg); };
The initMessageEvent()
and initMessageEventNS()
methods must initialise the event in a manner analogous to the
similarly-named methods in the DOM3 Events interfaces. [DOM3EVENTS]
The data
attribute represents the message being sent.
The domain
attribute
represents, in cross-document messaging, the
domain of the document from which the message came.
The uri
attribute represents, in cross-document
messaging, the address of the document from which the message came.
The source
attribute
represents, in cross-document messaging, the
Window
from which the message came.
This section describes a mechanism for allowing servers to dispatch DOM
events into documents that expect it. The event-source
element provides a simple
interface to this mechanism.
RemoteEventTarget
interfaceAny object that implements the EventTarget
interface must
also implement the RemoteEventTarget
interface.
interface RemoteEventTarget { void addEventSource(in DOMString src); void removeEventSource(in DOMString src); };
When the addEventSource(src)
method is invoked, the user agent must
add the URI specified in src to the list of event sources
for that object. The same URI can be registered multiple times.
When the removeEventSource(src)
method is invoked, the user agent must
remove the URI specified in src from the list of event sources
for that object. If the same URI has been registered multiple times,
removing it must only remove one instance of that URI for each invocation
of the removeEventSource()
method.
Relative URIs must be resolved relative to ....
Each object implementing the EventTarget
and RemoteEventTarget
interfaces has a
list of event
sources that are registered for that object.
When a new URI is added to this list, the user agent should, as soon as all currently executing scripts (if any) have finished executing, and if the specified URI isn't removed from the list before they do so, fetch the resource identified by that URI.
When an event source is removed from the list of event sources for an object, if that resource is still being fetched, then the relevant connection must be closed.
Since connections established to remote servers for such resources are expected to be long-lived, UAs should ensure that appropriate buffering is used. In particular, while line buffering may be safe if lines are defined to end with a single U+000A LINE FEED character, block buffering or line buffering with different expected line endings can cause delays in event dispatch.
In general, the semantics of the transport protocol specified by the URIs for the event sources must be followed, including HTTP caching rules.
For HTTP connections, the Accept
header may be
included; if included, it must only contain formats of event framing that
are supported by the user agent (one of which must be
application/x-dom-event-stream
, as described below).
Other formats of event framing may also be supported in addition to
application/x-dom-event-stream
, but this specification does
not define how they are to be parsed or processed.
Such formats could include systems like SMS-push; for example
servers could use Accept
headers and HTTP redirects
to an SMS-push mechanism as a kind of protocol negotiation to reduce
network load in GSM environments.
User agents should use the Cache-Control: no-cache
header
in requests to bypass any caches for requests of event sources.
For connections to domains other than the document's domain, the semantics of the Access-Control HTTP header must be followed. [ACCESSCONTROL]
HTTP 200 OK responses with a Content-Type
header specifying the type application/x-dom-event-stream
that are either from the document's domain or
explicitly allowed by the Access-Control HTTP headers must be processed
line by line as described
below.
For the purposes of such successfully opened event streams only, user agents should ignore HTTP cache headers, and instead assume that the resource indicates that it does not wish to be cached.
If such a resource completes loading (i.e. the entire HTTP response body is received or the connection itself closes), the user agent should request the event source resource again after a delay of approximately five seconds.
HTTP 200 OK responses that have a Content-Type other than
application/x-dom-event-stream
(or some other supported
type), and HTTP responses whose Access-Control headers indicate that the
resource are not to be used, must be ignored and must prevent the user
agent from refetching the resource for that event source.
HTTP 201 Created, 202 Accepted, 203 Non-Authoritative Information, and 206 Partial Content responses must be treated like HTTP 200 OK responses for the purposes of reopening event source resources. They are, however, likely to indicate an error has occurred somewhere and may cause the user agent to emit a warning.
HTTP 204 No Content, and 205 Reset Content responses must be treated as if they were 200 OK responses with the right MIME type but no content, and should therefore cause the user agent to refetch the resource after a short delay.
HTTP 300 Multiple Choices responses should be handled automatically if possible (treating the responses as if they were 302 Found responses pointing to the appropriate resource), and otherwise must be treated as HTTP 404 responses.
HTTP 301 Moved Permanently responses must cause the user agent to reconnect using the new server specified URI instead of the previously specified URI for all subsequent requests for this event source. (It doesn't affect other event sources with the same URI unless they also receive 301 responses, and it doesn't affect future sessions, e.g. if the page is reloaded.)
HTTP 302 Found, 303 See Other, and 307 Temporary Redirect responses must cause the user agent to connect to the new server-specified URI, but if the user agent needs to again request the resource at a later point, it must return to the previously specified URI for this event source.
HTTP 304 Not Modified responses should be handled like HTTP 200 OK responses, with the content coming from the user agent cache. A new request should then be made after a short delay of approximately five seconds.
HTTP 305 Use Proxy, HTTP 401 Unauthorized, and 407 Proxy Authentication Required should be treated transparently as for any other subresource.
Any other HTTP response code not listed here should cause the user agent to stop trying to process this event source.
DNS errors must be considered fatal, and cause the user agent to not open any connection for that event source.
For non-HTTP protocols, UAs should act in equivalent ways.
This event stream format's MIME type is
application/x-dom-event-stream
.
The event stream format is (in pseudo-BNF):
<stream> ::= <bom>? <event>* <event> ::= [ <comment> | <command> | <field> ]* <newline> <comment> ::= ';' <any-char>* <newline> <command> ::= ':' <any-char>* <newline> <field> ::= <name> [ ':' <space>? <any-char>* ]? <newline> <name> ::= <name-start-char> <name-char>* # characters: <bom> ::= a single U+FEFF BYTE ORDER MARK character <space> ::= a single U+0020 SPACE character (' ') <newline> ::= a U+000D CARRIAGE RETURN character followed by a U+000A LINE FEED character | a single U+000D CARRIAGE RETURN character | a single U+000A LINE FEED character | the end of the file <name-start-char> ::= a single Unicode character other than ':', ';', U+000D CARRIAGE RETURN and U+000A LINE FEED <name-char> ::= a single Unicode character other than ':', U+000D CARRIAGE RETURN and U+000A LINE FEED <any-char> ::= a single Unicode character other than U+000D CARRIAGE RETURN and U+000A LINE FEED
Event streams in this format must always be encoded as UTF-8. Lines must be separated by either a U+000D CARRIAGE RETURN U+000A LINE FEED (CRLF) character pair, a single U+000A LINE FEED (LF) character, or a single U+000D CARRIAGE RETURN (CR) character. User agents must treat those three variants as equivalent line terminators.
Bytes or sequences of bytes that are not valid UTF-8 sequences must be interpreted as the U+FFFD REPLACEMENT CHARACTER.
One leading U+FEFF BYTE ORDER MARK character must be ignored if any are present.
The stream must then be parsed by reading everything line by line, in blocks separated by blank lines. Comment lines (those starting with the character ';') and command lines (those starting with the character ':') must be ignored.
Command lines are reserved for future extensions.
For each non-blank, non-comment, non-command line, the field name must first be taken. This is everything on the line up to but not including the first colon (':') or the line terminator, whichever comes first. Then, if there was a colon, the data for that line must be taken. This is everything after the colon, ignoring a single space after the colon if there is one, up to the end of the line. If there was no colon the data is the empty string.
Examples:
Field name: Field data
This is a blank field
1. These two lines: have the same data 2. These two lines:have the same data
1. But these two lines: do not 2. But these two lines: do not
If a field name occurs multiple times in a block, the value for that field in that black must consist of the data parts for each of those lines, concatenated with U+000A LINE FEED characters between them (regardless of what the line terminators used in the stream actually are).
For example, the following block:
Test: Line 1 Foo: Bar Test: Line 2
...is treated as having two fields, one called Test
with
the value "Line 1\nLine 2
" (where \n
represents
a newline), and one called Foo
with the value
" Bar
" (note the leading space character).
A block thus consists of all the name-value pairs for its fields. Command lines have no effect on blocks and are not considered part of a block.
Since any random stream of characters matches the above format, there is no need to define any error handling.
Once the fields have been parsed, they are interpreted as follows (these are case-sensitive exact comparisons):
Event
field
This field gives the name of the event. For example, load
, DOMActivate
, updateTicker
. If there is no field with this name, the
name message
must be used.
Namespace
field
This field gives the DOM3 namespace for the event. (For normal DOM events this would be null.) If it isn't specified the event namespace is null.
Class
field
This field gives is the interface used for the event, for instance
Event
, UIEvent
, MutationEvent
,
KeyboardEvent
, etc. For compatibility with DOM3 Events, the
values UIEvents
, MouseEvents
, MutationEvents
, and
HTMLEvents
are valid values and must be treated
respectively as meaning the interfaces UIEvent
,
MouseEvent
, MutationEvent
, and
Event
. (This value can therefore be used as the argument to
createEvent()
.)
If the value is not specified but the Namespace
is null and the Event
field exactly matches one of
the events specified by DOM3 Events in section
1.4.2 "Complete list of event types", then the interface used must
default to the interface relevant for that event type. [DOM3EVENTS]
For example:
Event: click
...would cause Class
to be treated as
MouseEvent
.
If the Namespace
is null and the Event
field is message
(including if it was not specified
explicitly), then the MessageEvent
interface must be used.
Otherwise, the Event
interface must be used.
It is quite possible to give the wrong class for an event. This is equivalent to creating an event in the DOM using the DOM Event APIs, but using the wrong interface for it.
Bubbles
field
This field specifies whether the event is to bubble. If it is
specified and has the value No
, the event must not
bubble. If it is specified and has any other value (including no
or NO
) then the event must
bubble.
If it is not specified but the Namespace
field
is null and the Event
field exactly matches one of
the events specified by DOM3 Events in section
1.4.2 "Complete list of event types", then the event must bubble if
the DOM3 Events spec specifies that that event bubbles, and musn't
bubble if it specifies it does not. [DOM3EVENTS]
For example:
Event: load
...would cause Bubbles
to be treated as No
.
Otherwise, the event must bubble.
Cancelable
field
This field specifies whether the event can have its default action
prevented. If it is specified and has the value No
, the event must not be cancelable. If it is specified
and has any other value (including no
or NO
) then the event must be cancelable.
If it is not specified, but the Namespace
field
is null and the Event
field exactly matches one of
the events specified by DOM3 Events in section
1.4.2 "Complete list of event types", then the event must be
cancelable if the DOM3 Events specification specifies that it is, and
must not be cancelable otherwise. [DOM3EVENTS]
For example:
Event: load
...would cause Cancelable
to be treated as
No
.
Otherwise, the event must be cancelable.
Target
field
This field gives the node that the event is to be dispatched on.
If the object for which the event source is being processed is not a
Node, but the Target
field is nonetheless
specified, then the event must be dropped.
Otherwise, if field is specified and its value starts with a #
character, then the remainder of the value represents
an ID, and the event must be dispatched on the same node as would be
obtained by the getElementById()
method on the
ownerDocument
of the node whose event source is
being processed.
For example,
Target: #test
...would target the element with ID test
.
Otherwise, if the field is specified and its value is the literal
string "Document
", then the event must be
dispatched at the ownerDocument
of the node whose
event source is being processed.
Otherwise, the field (whether specified or not) is ignored and the event must be dispatched at the object itself.
Other fields depend on the interface specified (or possibly implied) by
the Class
field. If the specified interface has an
attribute that exactly matches the name of the field, and the value of the
field can be converted (using the type conversions defined in ECMAScript)
to the type of the attribute, then it must be used. Any attributes (other
than the Event
interface attributes) that do not have
matching fields are initialised to zero, null, false, or the empty string.
For example: