This section is non-normative.
This specification introduces two related mechanisms, similar to HTTP session cookies [RFC2965] , for storing structured data on the client side.
The first is designed for scenarios where the user is carrying out a single transaction, but could be carrying out multiple transactions in different windows at the same time.
Cookies don't really handle this case well. For example, a user could be buying plane tickets in two different windows, using the same site. If the site used cookies to keep track of which ticket the user was buying, then as the user clicked from page to page in both windows, the ticket currently being purchased would "leak" from one window to the other, potentially causing the user to buy two tickets for the same flight without really noticing.
To address this, this specification introduces the sessionStorage
DOM attribute. Sites
can add data to the session storage, and it will be accessible to
any page from that origin the same site opened in that window.
For example, a page could have a checkbox that the user ticks to indicate that he wants insurance:
<label> <input type="checkbox" onchange="sessionStorage.insurance = checked"> I want insurance on this trip. </label>
A later page could then check, from script, whether the user had checked the checkbox or not:
if (sessionStorage.insurance) { ... }
If the user had multiple windows opened on the site, each one would have its own individual copy of the session storage object.
The second storage mechanism is designed for storage that spans
multiple windows, and lasts beyond the current session. In
particular, Web applications may wish to store megabytes of user
data, such as entire user-authored documents or a user's mailbox,
on the clientside client side for performance reasons.
Again, cookies do not handle this case well, because they are transmitted with every request.
The
DOM attribute is used to
access a page's globalStorage localStorageglobal local storage area.
The site at example.com can display a count of how many times the user has loaded its page by putting the following at the bottom of its page:
<p> You have viewed this page <span id="count">an untold number of</span> time(s). </p> <script>if (!globalStorage.pageLoadCount) globalStorage.pageLoadCount = 0; globalStorage.pageLoadCount = parseInt(globalStorage.pageLoadCount, 10) + 1; document.getElementById('count').textContent = globalStorage.pageLoadCount;if (!localStorage.pageLoadCount) localStorage.pageLoadCount = 0; localStorage.pageLoadCount = parseInt(localStorage.pageLoadCount, 10) + 1; document.getElementById('count').textContent = localStorage.pageLoadCount; </script>
Each origin site has its own separate storage area.
Storage areas (both session storage and global local storage)
store strings. To store structured data in a storage area, you must
first convert it to a string.
Storage
interface interface Storage { readonly attribute unsigned long length; [IndexGetter] DOMString key(in unsigned long index); [NameGetter] DOMString getItem(in DOMString key); [NameSetter] void setItem(in DOMString key, in DOMString data); [XXX] void removeItem(in DOMString key); void clear(); };
Each Storage
object
provides access to a list of key/value pairs, which are sometimes
called items. Keys and values are strings. Any string (including
the empty string) is a valid key.
To store more structured data, authors may consider using the SQL interfaces instead.
Each Storage
object is
associated with a list of key/value pairs when it is created, as
defined in the sections on the sessionStorage
and
attributes. Multiple
separate objects implementing the globalStorage
localStorageStorage
interface can all be associated with
the same list of key/value pairs simultaneously.
The length
attribute must
return the number of key/value pairs currently present in the list
associated with the object.
The key(
n )
method must return the name of
the n th key in the list. The order of keys is
user-agent defined, but must be consistent within an object between
changes to the number of keys. (Thus, adding or removing a key may change the order of
the keys, but merely changing the value of an existing key must
not.) If n is less than zero or greater than or
equal to the number of key/value pairs in the object, then this
method must raise an INDEX_SIZE_ERR
exception.
The getItem(
key )
method must return the
current value associated with the given key .
If the given key does not exist in the list
associated with the object then this method must return null.
The setItem(
key , value )
method must first check if a key/value pair with the given
key already exists in the list associated with
the object.
If it does not, then a new key/value pair must be added to the list, with the given key and value .
If the given key does exist in the list, then it must have its value updated to the value given in the value argument.
When If it
couldn't set the new value, the setItem() method is invoked,
events are fired on other must raise
an HTMLDocument INVALID_ACCESS_ERRobjects that can access exception. (Setting could fail if, e.g., the
newly stored data, as defined in
user has disabled storage for the
sections on domain, or if the sessionStorage and globalStorage attributes.
quota has been exceeded.)
The removeItem( key
)
method must cause the key/value pair with the given
key to be removed from the list associated with
the object, if it exists. If no item with that key exists, the
method must do nothing.
The setItem()
and removeItem()
methods must be atomic with
respect to failure. That is, changes to the data storage area must
either be successful, or the data storage area must not be changed
at all.
In the ECMAScript DOM binding, enumerating
a Storage The clear()
object method
must enumerate through the currently stored
keys in atomically cause the list
the object is associated with. (It must not enumerate the values or
with the actual
members object to be emptied of
all key/value pairs.
When the interface). In the ECMAScript DOM binding,
, Storage setItem() objects must
support dereferencing such that getting a property that is not a
member of the object (i.e. is neither a member of the
,and Storage removeItem()clear()
interface nor of Object ) must invoke
the methods are invoked, events are
fired on other getItem()
HTMLDocumentmethod with objects that can
access the property's name
newly stored or removed data, as
defined in the argument, and setting such a property must invoke
sections on the setItem() sessionStoragemethod with the property's name as the first
argument and the given value as the
second argument. localStorage
attributes.
sessionStorage
attributeThe sessionStorage
attribute
represents the set of storage areas specific to the current
top-level browsing context .
Each top-level browsing context has a unique set of session storage areas, one for each origin .
User agents should not expire data from a browsing context's session storage areas, but may do so when the user requests that such data be deleted, or when the UA detects that it has limited storage space, or for security reasons. User agents should always avoid deleting data while a script that could access that data is running. When a top-level browsing context is destroyed (and therefore permanently inaccessible to the user) the data stored in its session storage areas can be discarded with it, as the API described in this specification provides no way for that data to ever be subsequently retrieved.
The lifetime of a browsing context can be unrelated to the lifetime of the actual user agent process itself, as the user agent may support resuming sessions after a restart.
When a new HTMLDocument
is created, the user agent must check to see if the document's
top-level browsing context has allocated a
session storage area for that document's origin . If it has not, a new storage area for that
document's origin must be created.
The Storage
object for the
document's associated Window
object's sessionStorage
attribute must then be
associated with that origin 's session
storage area for that top-level browsing
context .
When a new top-level browsing context is created by cloning an existing browsing context , the new browsing context must start with the same session storage areas as the original, but the two sets must from that point on be considered separate, not affecting each other in any way.
When a new top-level browsing context
is created by a script in an existing browsing
context , or by the user following a link in an existing
browsing context, or in some other way related to a specific
HTMLDocument
, then the
session storage area of the origin of that
HTMLDocument
must be
copied into the new browsing context when it is created. From that
point on, however, the two session storage areas must be considered
separate, not affecting each other in any way.
When the setItem()
,
removeItem()
,and clear()
method
is methods are called on a
Storage
object x that is associated with a session storage area, then in
every HTMLDocument
object
whose Window
object's
sessionStorage
attribute's
Storage
object is associated
with the same storage area, other than x , a
storage
event must be fired, as described below .
globalStorage
localStorage
attributeThe
object
provides a globalStorage
localStorageStorage
object for
an origin .
User agents must have a set of global local storage
areas, one for each origin .
User agents should only expire data
from the global local storage areas only for security reasons or when requested to do
so by the user. User agents should always avoid deleting data while
a script that could access that data is running. Data stored in
global local storage areas should be considered
potentially user-critical. It is expected that Web applications
will use the global local storage areas for storing user-written
documents.
When the
attribute is accessed, the
user agent must check to see if it has allocated globalStorage localStorageglobal local storage
area for the origin of the browsing context within which the script is
running. If it has not, a new storage area for that origin must be created.
The user agent must then create a Storage
object associated with that origin's
global local storage area, and return it.
When the setItem()
,
removeItem()
,and clear()
method
is methods are called on a
Storage
object x that is associated with a global local storage
area, then in every HTMLDocument
object whose Window
object's
attribute's globalStorage
localStorageStorage
object is associated with the same
storage area, other than x , a storage
event must
be fired, as described
below .
storage
eventThe storage
event is fired in an
HTMLDocument
when a
storage area changes, as described in the previous two sections (
for session storage , for global
local storage ).
When this happens, the user agent must fire a simple dispatch
an event called with the name storage
,
with no namespace, which does not bubble but
is cancelable, and which uses the onStorageEvent
,at the body
element . However, it is possible (indeed,
for session storage areas, likely) that the target's
of each active
HTMLDocument
object
affected.
If the event is not being fired due to
an active document invocation of the setItem()
or
at that time.
In such cases,removeItem()
methods, the user
agent event must instead delay have its
key
attribute set
to the firing name of the event until such
time as the key in question, its
HTMLDocument oldValueobject attribute set to the
old value of the key in question
becomes an active document again. question, or null if the key is newly added, and
its newValue
attribute
set to the new value of the key in question, or null if the key was
removed.
When there are multiple delayed
Otherwise, if the event is being fired due to
an invocation of the storage clear()events for method, the same
event must have its
,
HTMLDocument
keyoldValue
,and newValue
object, user
agents must coalesce those events such that only one event fires
when the document becomes active again. attributes set to null.
If In
addition, the DOM event must have its uri
attribute set
to the address of a the page that has
delayed whose storage Storageevents
queued up object was affected, and
its source
attribute set to the Window
object of the browsing context that
that document is discarded , then
in, if the delayed events two
documents are dropped as well. 4.10.6.
Miscellaneous implementation requirements for storage areas
in the same unit of related browsing
contexts ,or null
otherwise.
interface StorageEvent : Event {
readonly attribute DOMString key;
readonly attribute DOMString oldValue;
readonly attribute DOMString newValue;
readonly attribute DOMString uri;
readonly attribute Window source;
void initStorageEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString keyArg, in DOMString oldValueArg, in DOMString newValueArg, in DOMString uriArg, in Window sourceArg);
void initStorageEventNS(in DOMString namespaceURI, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString keyArg, in DOMString oldValueArg, in DOMString newValueArg, in DOMString uriArg, in Window sourceArg);
};
User agents should limit The initStorageEvent()
and initStorageEventNS()
methods must initialise the total amount of space allowed for event in a storage area
based on manner analogous to the
domain of similarly-named methods in the page setting DOM3 Events
interfaces. [DOM3EVENTS]
The key
attribute
represents the value. key being changed.
User agents should not limit
The oldValue
attribute represents the total amount old value
of space allowed on a per-storage-area basis,
otherwise a site could just store data in any number
the key being changed.
The newValue
attribute represents the new value 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.
key being changed.
User agents may prompt The uri
attribute
represents the user when per-domain
space quotas are reached, allowing address of the user to grant
a site more space. This enables sites to store many user-created
documents on document that
changed the user's computer, for
instance. User agents should allow users to see how much space each
domain is using. key.
If The
source
attribute represents the storage area space limit is reached during a
setItem() Windowcall, that changed 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. key.
Multiple browsing contexts must be able to access the
global local storage areas simultaneously in a
predictable manner. Scripts must not be able to detect any
concurrent script execution.
This is required to guarentee
guarantee 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 local storage area, the UA blocks scripts in other
browsing contexts when they try to access the global local 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. 4.10.7. Security and privacy
4.10.7.1. User tracking 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. 4.10.7.2.
Cookie resurrection 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.
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. 4.10.7.5. Implementation risks
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 This section is
important for user security. 4.11.
Client-side database storage 4.11.1. Introduction non-normative.
...
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.
The openDatabase()
method must use and create databases from the
origin
of the active document of
the Window
object on
which the method was invoked.
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.
The user agent may also raise a security exception in case the request violates a policy decision (e.g. if the user agent is configured to not allow the page to open databases).
Otherwise, if the database version
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
optimize 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 error);void 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 (in DOMString sqlStatement); void arguments); void callback); void errorCallback);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 n
th ?
placeholder gets replaced by the
n th value in the arguments
array.)
If the second argument is ommitted
omitted or null, then treat the
arguments array as empty.
The result is the statement .
Implementation feedback is requested on what to do with arguments that are of types that are not supported by the underlying SQL backend. For example, SQLite doesn't support booleans, so what should the UA do if passed a boolean? The Gears team suggests failing, not silently converting types.
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 file system
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. empty (its
length
will be zero).
interface SQLResultSetRowList {readonly attribute unsigned long ; (in unsigned long index);readonly attribute unsigned long length; [IndexGetter] 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 |
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 localized 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 occurred 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, optionally 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 If the statement's
statement has a result set callback callback, invoke
it 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 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.)
Commit the transaction.
If an error occured occurred 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 occurred 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 Rollback the
transaction. Any still-pending statements in the transaction are
discarded.
User agents should limit the total amount of space allowed for storage areas and databases.
User agents should guard against sites storing data in the storage areas or databases of subdomains, e.g. storing up to the limit in a1.example.com, a2.example.com, a3.example.com, etc, circumventing the main example.com storage limit.
User agents may prompt the user when 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.
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.
A third-party advertiser (or any entity
capable of getting content distributed to multiple sites) could use
a unique identifier stored in its local storage area or in its
client-side database to track a user across multiple sessions,
building a profile of the user's interests to allow for highly
targeted advertising. In contrast
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
localStoragefeature, which intentionally allows and database objects to scripts originating at the
domain of the top-level document of the browsing context
,for instance denying access to the API for
pages from other domains running in iframe
s.
Expiring stored data: user agents may automatically delete stored data after a period of time.
For example, a user agent could treat third-party local 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 accessed able to track the user across multiple domains, protocols, and ports (albeit sessions when he authenticates with the site itself
(e.g. by making a purchase or logging in to a controlled
fashion), service).
However, this also puts the user's data at risk.
Treating persistent storage as cookies:
user agents should present the persistent storage and
database feature is limited features to scripts
running the user in a way that does not
distinguish them from HTTP session cookies. [RFC2965]
This might encourage users to view persistent storage with healthy suspicion.
Site-specific white-listing of access to
local storage areas and databases: user agents may allow sites to
access session storage areas in an unrestricted manner, but
require the same user to authorize access to local storage areas and
databases.
origin
Origin as -tracking of persistent
storage data: user agents may record the database. Thus, it is expected origins of sites that the
privacy implications contained content
from third-party origins that caused data to be equivalent stored.
If this information is then used to
those already present the view of data currently in allowing scripts persistent
storage, it would allow the user to communicate make informed
decisions about which parts of the persistent storage to prune.
Combined with their originating
host. 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.
User Shared
blacklists: user agents are
encouraged may allow users to
treat share their
persistent storage domain blacklists.
This would allow communities to act together to protect their privacy.
While these suggestions prevent trivial use of these APIs 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 stored in
databases the
persistent storage features separately from data in
HTTP session cookies, then users are likely
to delete data in one and not the same
way other. This would allow sites to
use the two features as cookies
redundant backup for the purposes each other,
defeating a user's attempts to protect his privacy.
Because of user interfaces, the
potential for DNS spoofing attacks, one cannot guarantee that a
host claiming to reduce
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 risk
same domain can access their local storage
areas and databases.
Different authors sharing one host name,
for example users hosting content on geocities.com
,all
share one persistent storage object and one set of
using this databases. There is no feature to restrict the access by pathname. Authors on shared
hosts are therefore recommended to avoid using the persistent
storage features, as it would be trivial for cookie resurrection. other
authors to read from and write to the same storage area or
database.
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 these persistent storage features 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 origin model described in this specification is important for user security.
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
or keyword . 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 recognized 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. 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
only language information associated
with the resource to determine its language, not metadata included
in the link to the resource.
The type
attribute, if
present, gives the MIME type of the linked resource. It is purely
advisory. The value must be a valid MIME type, 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
choosing a browsing context given a
browsing context name , using the value of the target
attribute as the browsing context name. If these rules result in
the creation of a new browsing context ,
it must be navigated with replacement
enabled .
Otherwise, if the hyperlink 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 choosing a
browsing context given a browsing context name , using the
value of the target
attribute of the first such
base
element as the browsing
context name. If these rules result in the creation of a new
browsing context , it must be navigated
with replacement enabled .
Otherwise, the browsing context that must be navigated is the same browsing context as the one which the hyperlink element itself is in.
The navigation must be done with the
browsing
context that contains the
Document
object with which the hyperlink's element in question is
associated as the source browsing context .
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)
URI )
and then should send a request (as described
below) 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, behavior,
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). All relevant cookie and HTTP authentication headers must be included in the request. Which other headers are required depends on the URIs involved.
Document
object containing the hyperlink being audited and the
ping URI have the same originPing-From
HTTP header with, as its value, the location
of the document containing the hyperlink, and a Ping-To
HTTP header with, as its value, the address of the
target of the hyperlink. The request must not include a
Referer
HTTP header.Referer
HTTP header [sic] with, as its value, the
location of the document containing the hyperlink, a
Ping-From
HTTP header with the same value, and a
Ping-To
HTTP header with, as its value, the address
of the target of the hyperlink.Ping-To
HTTP header with, as its value, the address
of the target of the hyperlink. The request must neither include
a Referer
HTTP header nor include a Ping-From
HTTP header.To save bandwidth,
implementors might also wish to consider omitting optional headers
such as Accept
from these requests.
User agents must ignore any entity bodies returned in the
responses, but must, unless otherwise specified by the user,
honour honor the HTTP headers — (including, in
particular, redirects and HTTP cookie
headers. 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
summarizes the link types that are
defined by this specification. This table is non-normative; the
actual definitions for the link types are given in the next few
sections.
In this section, the term referenced document refers to the resource identified by the element representing the link, and the term current document refers to the resource within which the element representing the link finds itself.
To determine which link types apply to a link
, a
, or
area
element, the element's
rel
attribute must be split on spaces . The resulting
tokens are the link types that apply to that element.
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.
|
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 |
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 contain 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> ...
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 type
, media
, and sizes
attributes. If there are multiple equally appropriate
icons, user agents must use the last one declared in tree order
.If the user agent tries to use an icon but
that icon is determined, upon closer examination, to in fact be
inappropriate (e.g. because it uses an unsupported format), then
the user agent must try the next-most-appropriate icon as
determined by the attributes.
There is no default type for resources
given by the icon
keyword.
The sizes
attribute
gives the sizes of icons for visual media.
If specified, the attribute must have a
value that is an unordered set of unique space-separated tokens
.The values must all be either
any
or a value
that consists of two valid
non-negative integers that do not
have a leading U+0030 DIGIT ZERO (0) character and that are
separated by a single U+0078 LATIN SMALL LETTER X
character.
The keywords represent icon sizes.
To parse and process the attribute's value, the user agent must first split the attribute's value on spaces ,and must then parse each resulting keyword to determine what it represents.
The any
attribute. keyword represents that the resource contains a scalable
icon, e.g. as provided by an SVG image.
Other keywords must be further parsed as follows to determine what they represent:
If the keyword doesn't contain exactly one U+0078 LATIN SMALL LETTER X character, then this keyword doesn't represent anything. Abort these steps for that keyword.
Let width string be the
string before the " x
".
Let height string be the
string after the " x
".
If either width string or height string start with a U+0030 DIGIT ZERO (0) character or contain any characters other than characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9), then this keyword doesn't represent anything. Abort these steps for that keyword.
Apply the rules for parsing non-negative integers to width string to obtain width .
Apply the rules for parsing non-negative integers to height string to obtain height .
The keyword represents that the resource contains a bitmap icon with a width of width device pixels and a height of height device pixels.
The keywords specified on the
sizes
attribute
must not represent icon sizes that are not actually available in
the linked resource.
If the attribute is not specified, then the user agent must assume that the given icon is appropriate, but less appropriate than an icon of a known and appropriate size.
The following snippet shows the top part of an application with several icons.
<!DOCTYPE HTML> <html> <head> <title>lsForums — Inbox</title> <link rel=icon href=favicon.png sizes="16x16"> <link rel=icon href=windows.ico sizes="32x32 48x48"> <link rel=icon href=mac.icns sizes="128x128 512x512 8192x8192 32768x32768"> <link rel=icon href=iphone.png sizes="59x60"> <link rel=icon href=gnome.svg sizes="any"> <link rel=stylesheet href=lsforums.css> <script src=lsforums.js></script> <meta name=application-name content="lsForums"> </head> <body> ...
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. page, or that the link
to the referenced document was included primarily because of a
commercial relationship between people affiliated with the two
pages.
noreferrer
"The noreferrer
keyword may be used with
a
and area
elements.
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.
There is no default type for resources
given by the prefetch
keyword.
search
"The search
keyword may be used with
link
, a
, and area
elements. 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.
The default type for resources given by
the stylesheet
keyword is text/css
.
Quirk: If the document has been set to quirks mode and the Content-Type
metadata of the external resource
is not a supported style sheet type, the user agent must instead
assume it to be text/css
.
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 occurrence 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.
Only one link is created for the set of one
or more up
keywords and,
if present, the index
keyword.
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. bread crumbs. 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 .
When replacing a component in the URI, if the component is part of an optional group in the URI syntax consisting of a character followed by the component, the component (including its prefix character) must be included even if the new value is the empty string.
The previous paragraph
applies in particular to the " :
" before a <port> component,
the " ?
" before a <query> component, and the
" #
" before a <fragment>
component.
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 |
— |
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.