search element with form functionality — Last Updated 1 December 2021History interfaceLocation interfaceA browsing session is …. See whatwg/html issue #4782 and whatwg/html issue #5350 for defining
browsing session. It is roughly analogous to a top-level browsing
context except that it cannot be replaced due to a
`Cross-Origin-Opener-Policy` header or navigation.
A top-level browsing context has an associated browsing session which is a browsing session.
The browsing session of an environment settings object environment is the result of running these steps:
Assert: environment has a responsible document.
Return environment's responsible document's browsing context's top-level browsing context's browsing session.
The sequence of Documents in a browsing context is its session
history. Each browsing context, including child browsing contexts, has a distinct session history. A browsing
context's session history consists of a flat list of session history entries.
Each Document object in a browsing context's session
history is associated with a unique History object which must all model the
same underlying session history.
The history getter steps
are to return this's associated
Document's History instance.
A session history entry is a struct with the following items:
URL, a URL
document, a Document or null
Each entry, when first created, has a Document for its document. However, when a Document is not active, it's possible for it to be discarded to free resources. The URL and other
data in the session history entry is then used to bring a new Document
into being to take the place of the original, in the case where the user agent finds itself
having to navigate to the entry.
serialized state, which is serialized state or null, initially null
policy container, a policy container or null
scroll restoration mode, a scroll
restoration mode, initially "auto"
scroll position data, which is scroll position data for the document's restorable scrollable regions
browsing context name, a browsing context name or null, initially null
persisted user state, which is implementation-defined, initially null
For example, some user agents might want to persist the values of form controls.
User agents that persist the value of form controls are encouraged to also
persist their directionality (the value of the element's dir
attribute). This prevents values from being displayed incorrectly after a history traversal when
the user had originally entered the values with an explicit, non-default directionality.
Serialized state is a serialization (via StructuredSerializeForStorage) of an object representing a user interface state. We sometimes informally refer to "state objects", which are the objects representing user interface state supplied by the author, or alternately the objects created by deserializing (via StructuredDeserialize) serialized state.
Pages can add serialized state to the session history. These are then deserialized and returned to the script when the user (or script) goes back in the history, thus enabling authors to use the "navigation" metaphor even in one-page applications.
Serialized state is intended to be used for two main purposes: first, storing a
preparsed description of the state in the URL so that in the simple case an author
doesn't have to do the parsing (though one would still need the parsing for handling URLs passed around by users, so it's only a minor optimization). Second, so
that the author can store state that one wouldn't store in the URL because it only applies to the
current Document instance and it would have to be reconstructed if a new
Document were opened.
An example of the latter would be something like keeping track of the precise coordinate from
which a popup div was made to animate, so that if the user goes back, it can be made
to animate to the same location. Or alternatively, it could be used to keep a pointer into a
cache of data that would be fetched from the server based on the information in the
URL, so that when going back and forward, the information doesn't have to be fetched
again.
A scroll restoration mode indicates whether the user agent should restore the persisted scroll position (if any) when traversing to an entry. A scroll restoration mode is one of the following:
auto"manual"Several contiguous entries in a session history can share the same document. This can occur when the initial entry is reached via normal
navigation, and the following entry is added via history.pushState(). Or it can occur via navigation to a fragment.
All entries that share the same document (and that are therefore merely different states of one particular document) are contiguous by definition.
User agents may discard the documents of entries with non-null documents, as long as the following conditions are met:
They must not discard the document of the current entry.
They must not discard any Document objects which are referenced from
script.
Apart from these restrictions, this standard does not specify when user agents should discard an entry's document, versus keeping it cached.
Discarding a Document will
set the corresponding document item of any session history entries to null. Subsequent navigations to
those entries will result in the creation of a new Document object, and set the document item to it.
At any point, one of the entries in the session history is the current entry. This is the entry representing the active document of the browsing context. Which entry is the current entry is changed by the algorithms defined in this specification, e.g., during session history traversal.
The current entry is usually the initial entry created upon navigation. However, it can also be one of the contiguous entries that share the same document, as described above.
Each Document in a browsing context can also have a latest
entry. This is the entry for that Document to which the browsing
context's session history was most recently traversed. When a
Document is created, it initially has no latest entry.
History interfaceSupport in all current engines.
Support in all current engines.
enum ScrollRestoration { " auto " , " manual " };
[Exposed =Window ]
interface History {
readonly attribute unsigned long length ;
attribute ScrollRestoration scrollRestoration ;
readonly attribute any state ;
undefined go (optional long delta = 0);
undefined back ();
undefined forward ();
undefined pushState (any data , DOMString unused , optional USVString ? url = null );
undefined replaceState (any data , DOMString unused , optional USVString ? url = null );
};window.history.lengthSupport in all current engines.
Returns the number of entries in the joint session history.
window.history.scrollRestoration [ = value ]Support in all current engines.
Returns the scroll restoration mode of the current entry in the session history.
Can be set, to change the scroll restoration mode of the current entry in the session history.
window.history.stateSupport in all current engines.
Returns the current serialized state, deserialized into an object.
window.history.go([ delta ])Support in all current engines.
Goes back or forward the specified number of steps in the joint session history.
A zero delta will reload the current page.
If the delta is out of range, does nothing.
window.history.back()Support in all current engines.
Goes back one step in the joint session history.
If there is no previous page, does nothing.
window.history.forward()Support in all current engines.
Goes forward one step in the joint session history.
If there is no next page, does nothing.
window.history.pushState(data, "")Support in all current engines.
Push a new entry into session history with the given data associated. The current entry's URL will be copied over and used for the new entry's URL.
(The second parameter exists for historical reasons, and cannot be omitted; passing the empty string is traditional.)
window.history.pushState(data, "", url)Push a new entry into session history with the given data associated, and with its URL set to url.
If the current Document cannot have
its URL rewritten to url, a "SecurityError"
DOMException will be thrown.
(The second parameter exists for historical reasons, and cannot be omitted; passing the empty string is traditional.)
window.history.replaceState(data, "")Support in all current engines.
Updates the data stored in the current session history entry to data.
(The second parameter exists for historical reasons, and cannot be omitted; passing the empty string is traditional.)
window.history.replaceState(data, "", url)Updates the data stored in the current session history entry to data, and its URL to url.
If the current Document cannot have
its URL rewritten to url, a "SecurityError"
DOMException will be thrown.
(The second parameter exists for historical reasons, and cannot be omitted; passing the empty string is traditional.)
The joint session history of a top-level browsing context is the union
of all the session histories of all browsing contexts of all the fully active
Document objects that share that top-level browsing context, with all
the entries that are current entries in their respective session histories removed except for the current entry of
the joint session history.
The current entry of the joint session history is the entry that most recently became a current entry in its session history.
Entries in the joint session history are ordered chronologically by the time they were added to their respective session histories. Each entry has an index; the earliest entry has index 0, and the subsequent entries are numbered with consecutively increasing integers (1, 2, 3, etc.).
Since each Document in a browsing context might have a
different event loop, the actual state of the joint session history can
be somewhat nebulous. For example, two sibling iframe elements could both traverse from one unique origin to another at the same time,
so their precise order might not be well-defined; similarly, since they might only find out about
each other later, they might disagree about the length of the joint session
history.
Each History object has state,
initially null.
The length getter
steps are:
If this's associated Document is not fully active,
then throw a "SecurityError" DOMException.
Return the number of entries in the top-level browsing context's joint session history.
The actual entries are not accessible from script.
The scrollRestoration getter steps are:
If this's associated Document is not fully active,
then throw a "SecurityError" DOMException.
Return this's session history's current entry's scroll restoration mode.
The scrollRestoration setter steps
are:
If this's associated Document is not fully active,
then throw a "SecurityError" DOMException.
Set this's session history's current entry's scroll restoration mode to the given value.
The state getter
steps are:
If this's associated Document is not fully active,
then throw a "SecurityError" DOMException.
The go(delta)
method steps are:
If document is not fully active, then throw a
"SecurityError" DOMException.
If delta is 0, then act as if the location.reload() method was called, and return.
Traverse the history by a delta with delta and document's browsing context.
The back() method steps
are:
If document is not fully active, then throw a
"SecurityError" DOMException.
Traverse the history by a delta with −1 and document's browsing context.
The forward() method
steps are:
If document is not fully active, then throw a
"SecurityError" DOMException.
Traverse the history by a delta with +1 and document's browsing context.
Each top-level browsing context has a session history traversal queue, initially empty, to which tasks can be added.
Each top-level browsing context, when created, must begin running the following algorithm, known as the session history event loop for that top-level browsing context, in parallel:
Wait until this top-level browsing context's session history traversal queue is not empty.
Pull the first task from this top-level browsing context's session history traversal queue, and execute it.
Return to the first step of this algorithm.
The session history event loop helps coordinate cross-browsing-context transitions
of the joint session history: since each browsing context might, at any
particular time, have a different event loop (this can happen if the user navigates
from example.com to shop.example), transitions would
otherwise have to involve cross-event-loop synchronization.
To traverse the history by a delta given delta and browsing context source browsing context, the user agent must append a task to this top-level browsing context's session history traversal queue, the task consisting of running the following steps:
If the index of the current entry of the joint session history plus delta is less than zero or greater than or equal to the number of items in the joint session history, then return.
Let specified entry be the entry in the joint session history whose index is the sum of delta and the index of the current entry of the joint session history.
Let specified browsing context be the browsing context of the specified entry.
If source browsing context is not allowed to navigate specified browsing context, then return.
If the specified browsing context's active document's unload counter is greater than 0, then return.
Queue a global task on the history traversal task source given specified browsing context's active window to perform the following steps:
If there is an ongoing attempt to navigate specified browsing context
that has not yet matured (i.e. it has not passed the
point of making its Document the active document), then cancel that
attempt to navigate the browsing context.
If the specified browsing context's active document is not
the same Document as the Document of the specified
entry, then run these substeps:
If the result of calling prompt to unload with the active
document of the specified browsing context is "refuse", then abort these steps.
Unload the active document of the specified browsing context.
Traverse the history of the specified browsing context to the specified entry with explicitHistoryNavigation set to true.
When the user navigates through a browsing context, e.g. using a browser's back and forward buttons, the user agent must traverse the history by a delta with a delta equivalent to the action specified by the user and the browsing context being operated on.
The URL and history update steps, given a Document document,
a URL newURL, an optional serialized state-or-null serializedData (default null), and an optional
boolean isPush (default false), are:
Let browsingContext be document's browsing context.
If isPush is true, then:
Remove all the entries in browsingContext's session history after the current entry. If the current entry is the last entry in the session history, then no entries are removed.
This doesn't necessarily have to affect the user agent's user interface.
Remove any tasks queued by the history
traversal task source that are associated with any Document objects in the
top-level browsing context's document family.
Save persisted state to the current entry.
Add a session history entry entry to browsingContext's session history, after the current entry, with
newURL as the URL;
document as the document;
serializedData as the serialized state;
the scroll restoration mode of the current entry in the session history as the scroll restoration mode.
Update the current entry to be this newly added entry.
Otherwise:
Let entry be browsingContext's session history's current entry.
Set entry's URL to newURL.
If serializedData is not null, then set entry's serialized state to serializedData.
Update entry so that it represents a GET request, if it currently represents a non-GET request (e.g. it was the result of a POST submission).
What does this mean? This is not a part of the definition of session history entry.
Set document's URL to newURL.
Since this is neither a navigation of the
browsing context nor a history traversal,
it does not cause a hashchange event to be fired.
If serializedData is not null, then:
Let state be StructuredDeserialize(serializedData, document's relevant Realm). If this throws an exception, catch it, ignore the exception, and set state to null.
Set the current entry's document's latest entry to the current entry.
The pushState(data,
unused, url) method steps are to run the shared history
push/replace state steps given this, data, url, and
true.
The replaceState(data, unused,
url) method steps are to run the shared history push/replace state
steps given this, data, url, and false.
The shared history push/replace state steps, given a History
history, a value data, a scalar value string-or-null
url, and a boolean isPush, are:
Let document be history's associated Document.
If document is not fully active, then throw a
"SecurityError" DOMException.
Optionally, return. (For example, the user agent might disallow calls to these methods that are invoked on a timer, or from event listeners that are not triggered in response to a clear user action, or that are invoked in rapid succession.)
Let serializedData be StructuredSerializeForStorage(data). Rethrow any exceptions.
Let newURL be the session history's current entry's URL.
If url is not null, then:
Parse url, relative to the relevant settings object of history.
If that fails, then throw a "SecurityError"
DOMException.
Set newURL to the resulting URL record.
If document cannot have its URL
rewritten to newURL, then throw a "SecurityError"
DOMException.
Run the URL and history update steps given document and newURL, with serializedData set to serializedData and isPush set to isPush.
User agents may limit the number of state objects added to the session history per page. If a
page hits the implementation-defined limit, user agents must remove the entry
immediately after the first entry for that Document object in the session history
after having added the new entry. (Thus the state history acts as a FIFO buffer for eviction, but
as a LIFO buffer for navigation.)
A Document document can have its URL rewritten to a
URL targetURL if the following algorithm returns true:
Let documentURL be document's URL.
If targetURL and documentURL differ in their scheme, username, password, host, or port components, then return false.
If targetURL's scheme is an
HTTP(S) scheme, then return true. (Differences in path, query, and fragment are allowed for http: and https: URLs.)
If targetURL's scheme is "file", and targetURL and documentURL differ in their
path component, then return false. (Differences in query and fragment
are allowed for file: URLs.)
If targetURL and documentURL differ in their path component or query components, then return false. (Only differences in fragment are allowed for other types of URLs.)
Return true.
| document's URL | targetURL | can have its URL rewritten |
|---|---|---|
https://example.com/home
| https://example.com/home#about
| ✅ |
https://example.com/home
| https://example.com/home?page=shop
| ✅ |
https://example.com/home
| https://example.com/shop
| ✅ |
https://example.com/home
| https://user:pass@example.com/home
| ❌ |
https://example.com/home
| http://example.com/home
| ❌ |
file:///path/to/x
| file:///path/to/x#hash
| ✅ |
file:///path/to/x
| file:///path/to/x?search
| ✅ |
file:///path/to/x
| file:///path/to/y
| ❌ |
about:blank
| about:blank#hash
| ✅ |
about:blank
| about:blank?search
| ❌ |
about:blank
| about:srcdoc
| ❌ |
data:text/html,foo
| data:text/html,foo#hash
| ✅ |
data:text/html,foo
| data:text/html,foo?search
| ❌ |
data:text/html,foo
| data:text/html,bar
| ❌ |
data:text/html,foo
| data:bar
| ❌ |
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43
| blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43#hash
| ✅ |
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43
| blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43?search
| ❌ |
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43
| blob:https://example.com/anything
| ❌ |
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43
| blob:path
| ❌ |
Note how only the URL of the Document
matters, and not its origin. They can mismatch in
cases like about:blank Documents with inherited origins, in sandboxed
iframes, or when the document.domain
setter has been used.
Consider a game where the user can navigate along a line, such that the user is always at some coordinate, and such that the user can bookmark the page corresponding to a particular coordinate, to return to it later.
A static page implementing the x=5 position in such a game could look like the following:
<!DOCTYPE HTML>
<!-- this is https://example.com/line?x=5 -->
< html lang = "en" >
< title > Line Game - 5</ title >
< p > You are at coordinate 5 on the line.</ p >
< p >
< a href = "?x=6" > Advance to 6</ a > or
< a href = "?x=4" > retreat to 4</ a > ?
</ p > The problem with such a system is that each time the user clicks, the whole page has to be reloaded. Here instead is another way of doing it, using script:
<!DOCTYPE HTML>
<!-- this starts off as https://example.com/line?x=5 -->
< html lang = "en" >
< title > Line Game - 5</ title >
< p > You are at coordinate < span id = "coord" > 5</ span > on the line.</ p >
< p >
< a href = "?x=6" onclick = "go(1); return false;" > Advance to 6</ a > or
< a href = "?x=4" onclick = "go(-1); return false;" > retreat to 4</ a > ?
</ p >
< script >
var currentPage = 5 ; // prefilled by server
function go( d) {
setupPage( currentPage + d);
history. pushState( currentPage, "" , '?x=' + currentPage);
}
onpopstate = function ( event) {
setupPage( event. state);
}
function setupPage( page) {
currentPage = page;
document. title = 'Line Game - ' + currentPage;
document. getElementById( 'coord' ). textContent = currentPage;
document. links[ 0 ]. href = '?x=' + ( currentPage+ 1 );
document. links[ 0 ]. textContent = 'Advance to ' + ( currentPage+ 1 );
document. links[ 1 ]. href = '?x=' + ( currentPage- 1 );
document. links[ 1 ]. textContent = 'retreat to ' + ( currentPage- 1 );
}
</ script > In systems without script, this still works like the previous example. However, users that do have script support can now navigate much faster, since there is no network access for the same experience. Furthermore, contrary to the experience the user would have with just a naïve script-based approach, bookmarking and navigating the session history still work.
In the example above, the data argument to the pushState() method is the same information as would be sent
to the server, but in a more convenient form, so that the script doesn't have to parse the URL
each time the user navigates.
Most applications want to use the same scroll restoration mode value for all of
their history entries. To achieve this they can set the scrollRestoration attribute as soon as possible
(e.g., in the first script element in the document's head element) to
ensure that any entry added to the history session gets the desired scroll restoration mode.
< head >
< script >
if ( 'scrollRestoration' in history)
history. scrollRestoration = 'manual' ;
</ script >
</ head >
This section is non-normative.
The History interface is not meant to place restrictions on how implementations
represent the session history to the user.
For example, session history could be implemented in a tree-like manner, with each page having
multiple "forward" pages. This specification doesn't define how the linear list of pages in the
history object are derived from the actual session history as
seen from the user's perspective.
Similarly, a page containing two iframes has a history object distinct from the iframes' history objects, despite the fact that typical web browsers present the
user with just one "Back" button, with a session history that interleaves the navigation of the
two inner frames and the outer page.
Security: It is suggested that to avoid letting a page "hijack" the history
navigation facilities of a UA by abusing pushState(),
the UA provide the user with a way to jump back to the previous page (rather than just going back
to the previous state). For example, the back button could have a drop down showing just the pages
in the session history, and not showing any of the states. Similarly, an aural browser could have
two "back" commands, one that goes back to the previous state, and one that jumps straight back to
the previous page.
For both pushState() and replaceState(), user agents are encouraged to prevent
abuse of these APIs via too-frequent calls or over-large state objects. As detailed above, the
algorithm explicitly allows user agents to ignore any such calls when appropriate.
Location interfaceSupport in all current engines.
Support in all current engines.
Support in all current engines.
Each Window object is associated with a unique instance of a Location
object, allocated when the Window object is created.
The Location exotic object is defined through a mishmash of IDL,
invocation of JavaScript internal methods post-creation, and overridden JavaScript internal
methods. Coupled with its scary security policy, please take extra care while implementing
this excrescence.
To create a Location object, run these steps:
Let location be a new Location platform
object.
Let valueOf be location's relevant Realm.[[Intrinsics]].[[%Object.prototype.valueOf%]].
Perform ! location.[[DefineOwnProperty]]("valueOf", {
[[Value]]: valueOf,
[[Writable]]: false,
[[Enumerable]]: false,
[[Configurable]]: false }).
Perform ! location.[[DefineOwnProperty]](@@toPrimitive, { [[Value]]: undefined, [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }).
Set the value of the [[DefaultProperties]] internal slot of location to location.[[OwnPropertyKeys]]().
Return location.
The addition of valueOf and @@toPrimitive own
data properties, as well as the fact that all of Location's IDL attributes are marked
[LegacyUnforgeable], is required by legacy code that consulted
the Location interface, or stringified it, to determine the document URL, and then used it in a security-sensitive way.
In particular, the valueOf, @@toPrimitive, and [LegacyUnforgeable] stringifier mitigations ensure that code such as
foo[location] = bar or location + "" cannot be
misdirected.
document.location [ = value ]window.location [ = value ]Returns a Location object with the current page's location.
Can be set, to navigate to another page.
The Document object's location getter steps are to return
this's relevant global object's Location object, if
this is fully active, and null otherwise.
The Window object's location getter steps are to return this's
Location object.
Location objects provide a representation of the URL of the active document of their
Document's browsing context, and allow the
current entry of the browsing context's session history to be changed,
by adding or replacing entries in the history object.
[Exposed =Window ]
interface Location { // but see also additional creation steps and overridden internal methods
[LegacyUnforgeable ] stringifier attribute USVString href ;
[LegacyUnforgeable ] readonly attribute USVString origin ;
[LegacyUnforgeable ] attribute USVString protocol ;
[LegacyUnforgeable ] attribute USVString host ;
[LegacyUnforgeable ] attribute USVString hostname ;
[LegacyUnforgeable ] attribute USVString port ;
[LegacyUnforgeable ] attribute USVString pathname ;
[LegacyUnforgeable ] attribute USVString search ;
[LegacyUnforgeable ] attribute USVString hash ;
[LegacyUnforgeable ] undefined assign (USVString url );
[LegacyUnforgeable ] undefined replace (USVString url );
[LegacyUnforgeable ] undefined reload ();
[LegacyUnforgeable , SameObject ] readonly attribute DOMStringList ancestorOrigins ;
};location.toString()location.hrefSupport in all current engines.
Support in all current engines.
Returns the Location object's URL.
Can be set, to navigate to the given URL.
location.originSupport in all current engines.
Returns the Location object's URL's origin.
location.protocolSupport in all current engines.
Returns the Location object's URL's scheme.
Can be set, to navigate to the same URL with a changed scheme.
location.hostSupport in all current engines.
Returns the Location object's URL's host and port (if different from the default
port for the scheme).
Can be set, to navigate to the same URL with a changed host and port.
location.hostnameSupport in all current engines.
Returns the Location object's URL's host.
Can be set, to navigate to the same URL with a changed host.
location.portSupport in all current engines.
Returns the Location object's URL's port.
Can be set, to navigate to the same URL with a changed port.
location.pathnameSupport in all current engines.
Returns the Location object's URL's path.
Can be set, to navigate to the same URL with a changed path.
location.searchSupport in all current engines.
Returns the Location object's URL's query (includes leading "?" if non-empty).
Can be set, to navigate to the same URL with a changed query (ignores leading "?").
location.hashSupport in all current engines.
Returns the Location object's URL's fragment (includes leading "#" if non-empty).
Can be set, to navigate to the same URL with a changed fragment (ignores leading "#").
location.assign(url)Support in all current engines.
Navigates to the given URL.
location.replace(url)Support in all current engines.
Removes the current page from the session history and navigates to the given URL.
location.reload()Support in all current engines.
Reloads the current page.
location.ancestorOriginsReturns a DOMStringList object listing the origins of the ancestor browsing contexts, from the parent browsing
context to the top-level browsing context.
A Location object has an associated relevant Document,
which is this Location object's relevant global object's browsing context's active document, if this
Location object's relevant global object's browsing context is non-null, and null otherwise.
A Location object has an associated url,
which is this Location object's relevant Document's URL, if this Location object's relevant
Document is non-null, and about:blank otherwise.
A Location object has an associated ancestor origins list. When a
Location object is created, its ancestor origins list must be set to a
DOMStringList object whose associated list is the list of strings that
the following steps would produce:
Let output be a new list of strings.
Let current be the browsing context
of the Document with which this Location object is associated.
Loop: If current has no parent browsing context, jump to the step labeled end.
Let current be current's parent browsing context.
Append the serialization of current's active document's origin to output.
Return to the step labeled loop.
End: Return output.
To Location-object navigate, given a URL url
and an optional history handling behavior historyHandling (default "default"):
Let browsingContext be this Location object's relevant
global object's browsing context.
Let sourceBrowsingContext be the incumbent global object's browsing context.
If browsingContext is still on its initial about:blank
Document, then set historyHandling to "replace".
If this Location object's relevant Document is not
yet completely loaded, and the incumbent
global object does not have transient activation, then set
historyHandling to "replace".
Navigate browsingContext to url, with exceptionsEnabled set to true, historyHandling set to historyHandling, and the source browsing context set to sourceBrowsingContext.
The href getter
steps are:
If this's relevant Document is non-null and its
origin is not same origin-domain with
the entry settings object's origin, then throw a
"SecurityError" DOMException.
Return this's url, serialized.
The href setter steps are:
If this's relevant Document is null, then
return.
Parse the given value relative to the entry
settings object. If that failed, throw a TypeError exception.
Location-object navigate given the resulting URL
record.
The href setter intentionally has no
security check.
The origin
getter steps are:
If this's relevant Document is non-null and its
origin is not same origin-domain with
the entry settings object's origin, then throw a
"SecurityError" DOMException.
Return the serialization of this's url's origin.
The protocol
getter steps are:
If this's relevant Document is non-null and its
origin is not same origin-domain with
the entry settings object's origin, then throw a
"SecurityError" DOMException.
The protocol setter steps are:
If this's relevant Document is null, then
return.
If this's relevant Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" DOMException.
Let possibleFailure be the result of basic URL
parsing the given value, followed by ":", with copyURL
as url and scheme start state as
state override.
Because the URL parser ignores multiple consecutive colons, providing a value
of "https:" (or even "https::::") is the same as
providing a value of "https".
If possibleFailure is failure, then throw a
"SyntaxError" DOMException.
If copyURL's scheme is not an HTTP(S) scheme, then terminate these steps.
Location-object navigate to copyURL.
The host getter
steps are:
If this's relevant Document is non-null and its
origin is not same origin-domain with
the entry settings object's origin, then throw a
"SecurityError" DOMException.
If url's host is null, return the empty string.
If url's port is null, return url's host, serialized.
Return url's host, serialized, followed by ":" and url's port, serialized.
The host setter steps are:
If this's relevant Document is null, then
return.
If this's relevant Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" DOMException.
If copyURL has an opaque path, then return.
Basic URL parse the given value, with copyURL as url and host state as state override.
Location-object navigate to copyURL.
The hostname
getter steps are:
If this's relevant Document is non-null and its
origin is not same origin-domain with
the entry settings object's origin, then throw a
"SecurityError" DOMException.
Return this's url's host, serialized.
The hostname setter steps are:
If this's relevant Document is null, then
return.
If this's relevant Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" DOMException.
If copyURL has an opaque path, then return.
Basic URL parse the given value, with copyURL as url and hostname state as state override.
Location-object navigate to copyURL.
The port getter
steps are:
If this's relevant Document is non-null and its
origin is not same origin-domain with
the entry settings object's origin, then throw a
"SecurityError" DOMException.
Return this's url's port, serialized.
The port setter steps are:
If this's relevant Document is null, then
return.
If this's relevant Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" DOMException.
If copyURL cannot have a username/password/port, then return.
If the given value is the empty string, then set copyURL's port to null.
Otherwise, basic URL parse the given value, with copyURL as url and port state as state override.
Location-object navigate to copyURL.
The pathname
getter steps are:
If this's relevant Document is non-null and its
origin is not same origin-domain with
the entry settings object's origin, then throw a
"SecurityError" DOMException.
Return the result of URL path serializing this
Location object's url.
The pathname setter steps are:
If this's relevant Document is null, then
return.
If this's relevant Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" DOMException.
If copyURL has an opaque path, then return.
Set copyURL's path to the empty list.
Basic URL parse the given value, with copyURL as url and path start state as state override.
Location-object navigate to copyURL.
The search
getter steps are:
If this's relevant Document is non-null and its
origin is not same origin-domain with
the entry settings object's origin, then throw a
"SecurityError" DOMException.
If this's url's query is either null or the empty string, return the empty string.
The search setter steps are:
If this's relevant Document is null, then
return.
If this's relevant Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" DOMException.
If the given value is the empty string, set copyURL's query to null.
Otherwise, run these substeps:
Let input be the given value with a single leading "?" removed, if any.
Set copyURL's query to the empty string.
Basic URL parse input, with null, the
relevant Document's document's character encoding,
copyURL as url, and query
state as state
override.
Location-object navigate to copyURL.
The hash getter
steps are:
If this's relevant Document is non-null and its
origin is not same origin-domain with
the entry settings object's origin, then throw a
"SecurityError" DOMException.
If this's url's fragment is either null or the empty string, return the empty string.
The hash setter steps are:
If this's relevant Document is null, then
return.
If this's relevant Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" DOMException.
Let input be the given value with a single leading "#"
removed, if any.
Set copyURL's fragment to the empty string.
Basic URL parse input, with copyURL as url and fragment state as state override.
Location-object navigate to copyURL.
Unlike the equivalent API for the a and area elements,
the hash setter does not special case the empty string, to
remain compatible with deployed scripts.
The assign(url) method steps are:
If this's relevant Document is null, then
return.
If this's relevant Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" DOMException.
Parse url relative to the entry
settings object. If that failed, throw a "SyntaxError"
DOMException.
Location-object navigate given the resulting URL
record.
The replace(url) method steps are:
If this's relevant Document is null, then
return.
Parse url relative to the entry
settings object. If that failed, throw a "SyntaxError"
DOMException.
Location-object navigate given the resulting URL
record and "replace".
The replace() method intentionally has
no security check.
The reload() method
steps are to run the appropriate steps from the following list:
Document is nullReturn.
Document's origin is not same origin-domain with the
entry settings object's originThrow a "SecurityError" DOMException.
resize event in response to the user resizing the
browsing contextRepaint the browsing context and return.
iframe srcdoc documentReprocess the iframe
attributes of the browsing context's container.
Navigate the browsing context to
this's relevant Document's URL, with exceptionsEnabled set to
true, historyHandling set to "reload", and the source browsing context set to the
browsing context being navigated.
When a user requests that the active document of a browsing context
be reloaded through a user interface element, the user agent should navigate the browsing context to the same resource as that
Document, with historyHandling set to "reload". In the case of non-idempotent methods (e.g., HTTP POST), the
user agent should prompt the user to confirm the operation first, since otherwise transactions
(e.g., purchases or database modifications) could be repeated. User agents may allow the user to
explicitly override any caches when reloading.
The ancestorOrigins getter steps are:
If this's relevant Document is null, then return
an empty list.
If this's relevant Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" DOMException.
Otherwise, return this's ancestor origins list.
The details of how the ancestorOrigins attribute works are still
controversial and might change. See issue
#1918 for more information.
As explained earlier, the Location exotic object
requires additional logic beyond IDL for security purposes. The Location object must
use the ordinary internal methods except where it is explicitly specified otherwise below.
Also, every Location object has a [[DefaultProperties]] internal slot
representing its own properties at time of its creation.
If ! IsPlatformObjectSameOrigin(this) is true, then return ! OrdinaryGetPrototypeOf(this).
Return null.
Return ! SetImmutablePrototype(this, V).
Return true.
Return false.
If ! IsPlatformObjectSameOrigin(this) is true, then:
Let desc be ! OrdinaryGetOwnProperty(this, P).
If the value of the [[DefaultProperties]] internal slot of this contains P, then set desc.[[Configurable]] to true.
Return desc.
Let property be ! CrossOriginGetOwnPropertyHelper(this, P).
If property is not undefined, then return property.
Return ? CrossOriginPropertyFallback(P).
If ! IsPlatformObjectSameOrigin(this) is true, then:
If the value of the [[DefaultProperties]] internal slot of this contains P, then return false.
Return ? OrdinaryDefineOwnProperty(this, P, Desc).
Throw a "SecurityError" DOMException.
If ! IsPlatformObjectSameOrigin(this) is true, then return ? OrdinaryGet(this, P, Receiver).
Return ? CrossOriginGet(this, P, Receiver).
If ! IsPlatformObjectSameOrigin(this) is true, then return ? OrdinarySet(this, P, V, Receiver).
Return ? CrossOriginSet(this, P, V, Receiver).
If ! IsPlatformObjectSameOrigin(this) is true, then return ? OrdinaryDelete(this, P).
Throw a "SecurityError" DOMException.
If ! IsPlatformObjectSameOrigin(this) is true, then return ! OrdinaryOwnPropertyKeys(this).
Return ! CrossOriginOwnPropertyKeys(this).