diff --git a/files/en-us/web/api/history/forward/index.md b/files/en-us/web/api/history/forward/index.md index 9177368a3eba3ea..5c0b2ed549cdfd9 100644 --- a/files/en-us/web/api/history/forward/index.md +++ b/files/en-us/web/api/history/forward/index.md @@ -11,8 +11,7 @@ The **`History.forward()`** method causes the browser to move forward one page in the session history. It has the same effect as calling {{domxref("History.go", "history.go(1)")}}. -This method is {{glossary("asynchronous")}}. Add a listener for the -{{domxref("Window/popstate_event", "popstate")}} event in order to determine when the navigation has completed. +This method is {{glossary("asynchronous")}}. Add a listener for the {{domxref("Window/popstate_event", "popstate")}} event in order to determine when the navigation has completed. ## Syntax @@ -43,7 +42,7 @@ history. ```js document.getElementById("go-forward").addEventListener("click", (e) => { - window.history.forward(); + history.forward(); }); ``` @@ -58,4 +57,5 @@ document.getElementById("go-forward").addEventListener("click", (e) => { ## See also - {{domxref("History")}} +- {{domxref("Window/popstate_event", "popstate")}} - [Working with the History API](/en-US/docs/Web/API/History_API/Working_with_the_History_API) diff --git a/files/en-us/web/api/history/index.md b/files/en-us/web/api/history/index.md index 606733db1d39439..b7bc5388db39a31 100644 --- a/files/en-us/web/api/history/index.md +++ b/files/en-us/web/api/history/index.md @@ -9,6 +9,10 @@ browser-compat: api.History The **`History`** interface allows manipulation of the browser _session history_, that is the pages visited in the tab or frame that the current page is loaded in. +There is only one instance of `history` (It is a _singleton_.) accessible via the global object {{domxref("Window.history", "history")}}. + +> **Note:** This interface is only available on the main thread ({{domxref("Window")}}). It cannot be accessed in {{domxref("Worker")}} or {{domxref("Worklet")}} contexts. + ## Instance properties _The `History` interface doesn't inherit any property._ @@ -53,4 +57,4 @@ _The `History`_ _interface doesn't inherit any methods._ ## See also -- The {{domxref("Window.history")}} property returning the history of the current session. +- {{domxref("Window.history", "history")}} global object diff --git a/files/en-us/web/api/history/pushstate/index.md b/files/en-us/web/api/history/pushstate/index.md index 8eb11d7ad2a8c35..913e1cc9d6ccb12 100644 --- a/files/en-us/web/api/history/pushstate/index.md +++ b/files/en-us/web/api/history/pushstate/index.md @@ -11,6 +11,8 @@ In an [HTML](/en-US/docs/Web/HTML) document, the **`history.pushState()`** method adds an entry to the browser's session history stack. +This method is {{glossary("asynchronous")}}. Add a listener for the {{domxref("Window/popstate_event", "popstate")}} event in order to determine when the navigation has completed. The `state` parameter will be available in it. + ## Syntax ```js-nolint @@ -89,9 +91,9 @@ history.pushState(state, "", url); ### Change a query parameter ```js -const url = new URL(window.location); +const url = new URL(location); url.searchParams.set("foo", "bar"); -window.history.pushState({}, "", url); +history.pushState({}, "", url); ``` ## Specifications diff --git a/files/en-us/web/api/history/replacestate/index.md b/files/en-us/web/api/history/replacestate/index.md index b41a32bc40c1941..0d51c89a0cfbfb5 100644 --- a/files/en-us/web/api/history/replacestate/index.md +++ b/files/en-us/web/api/history/replacestate/index.md @@ -13,18 +13,20 @@ URL passed in the method parameters. This method is particularly useful when you want to update the state object or URL of the current history entry in response to some user action. +This method is {{glossary("asynchronous")}}. Add a listener for the {{domxref("Window/popstate_event", "popstate")}} event in order to determine when the navigation has completed. The `state` parameter will be available in it. + ## Syntax ```js-nolint -replaceState(stateObj, unused) -replaceState(stateObj, unused, url) +replaceState(state, unused) +replaceState(state, unused, url) ``` ### Parameters -- `stateObj` - - : The state object is a JavaScript object which is associated with the history entry - passed to the `replaceState` method. The state object can be +- `state` + - : An object which is associated with the history entry + passed to the `replaceState()` method. The state object can be `null`. - `unused` - : This parameter exists for historical reasons, and cannot be omitted; passing the empty string is traditional, and safe against future changes to the method. diff --git a/files/en-us/web/api/history/state/index.md b/files/en-us/web/api/history/state/index.md index f692592320c3c07..c1acabf62c4bcd3 100644 --- a/files/en-us/web/api/history/state/index.md +++ b/files/en-us/web/api/history/state/index.md @@ -48,3 +48,4 @@ console.log("History.state after pushState: ", history.state); - [Working with the History API](/en-US/docs/Web/API/History_API/Working_with_the_History_API) - [`History.pushState()`](/en-US/docs/Web/API/History/pushState) - [`History.replaceState()`](/en-US/docs/Web/API/History/replaceState) +- [`PopStateEvent.state`](/en-US/docs/Web/API/PopStateEvent/state) diff --git a/files/en-us/web/api/history_api/example/index.md b/files/en-us/web/api/history_api/example/index.md index bd3c971f4558fba..c89e64d966a9a6f 100644 --- a/files/en-us/web/api/history_api/example/index.md +++ b/files/en-us/web/api/history_api/example/index.md @@ -1,10 +1,10 @@ --- -title: Ajax navigation example +title: History navigation example slug: Web/API/History_API/Example page-type: guide --- -This is an example of an AJAX website composed only of three pages (_first_page.php_, _second_page.php_ and _third_page.php_). To see how it works, please create the following files (or git clone [https://github.com/giabao/mdn-ajax-nav-example.git](https://github.com/giabao/mdn-ajax-nav-example) ): +This is an example of a website composed only of three pages (_first_page.php_, _second_page.php_ and _third_page.php_). To see how it works, please create the following files (or git clone [https://github.com/giabao/mdn-ajax-nav-example.git](https://github.com/giabao/mdn-ajax-nav-example) ): > **Note:** For fully integrating the {{HTMLElement("form")}} elements within this _mechanism_, please take a look at the paragraph [Submitting forms and uploading files](/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest#submitting_forms_and_uploading_files). @@ -422,5 +422,5 @@ For more information, please see: [Working with the History API](/en-US/docs/Web ## See also -- {{ domxref("window.history") }} +- {{domxref("window.history", "history")}} global object - {{domxref("Window/popstate_event", "popstate")}} event diff --git a/files/en-us/web/api/history_api/index.md b/files/en-us/web/api/history_api/index.md index 5cbadbed98cfa02..d3d8a2f7c08b70f 100644 --- a/files/en-us/web/api/history_api/index.md +++ b/files/en-us/web/api/history_api/index.md @@ -7,7 +7,9 @@ browser-compat: api.History {{DefaultAPISidebar("History API")}} -The DOM {{DOMxRef("Window")}} object provides access to the browser's session history (not to be confused for [WebExtensions history](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/history)) through the {{DOMxRef("Window.history","history")}} object. It exposes useful methods and properties that let you navigate back and forth through the user's history, and manipulate the contents of the history stack. +The **History API** provides access to the browser's session history (not to be confused with [WebExtensions history](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/history)) through the {{DOMxRef("Window.history","history")}} global object. It exposes useful methods and properties that let you navigate back and forth through the user's history, and manipulate the contents of the history stack. + +> **Note:** This API is only available on the main thread ({{domxref("Window")}}). It cannot be accessed in {{domxref("Worker")}} or {{domxref("Worklet")}} contexts. ## Concepts and usage @@ -18,7 +20,7 @@ Moving backward and forward through the user's history is done using the {{DOMxR To move backward through history: ```js -window.history.back(); +history.back(); ``` This acts exactly as if the user clicked on the Back button in their browser toolbar. @@ -26,7 +28,7 @@ This acts exactly as if the user clicked on the Back Similarly, you can move forward (as if the user clicked the Forward button), like this: ```js -window.history.forward(); +history.forward(); ``` ### Moving to a specific point in history @@ -36,13 +38,13 @@ You can use the {{DOMxRef("History.go","go()")}} method to load a specific page To move back one page (the equivalent of calling {{DOMxRef("History.back","back()")}}): ```js -window.history.go(-1); +history.go(-1); ``` To move forward a page, just like calling {{DOMxRef("History.forward","forward()")}}: ```js -window.history.go(1); +history.go(1); ``` Similarly, you can move forward 2 pages by passing `2`, and so forth. @@ -53,27 +55,29 @@ Another use for the `go()` method is to refresh the current page by either passi // The following statements // both have the effect of // refreshing the page -window.history.go(0); -window.history.go(); +history.go(0); +history.go(); ``` You can determine the number of pages in the history stack by looking at the value of the `length` property: ```js -let numberOfEntries = window.history.length; +const numberOfEntries = history.length; ``` ## Interfaces - {{domxref("History")}} - : Allows manipulation of the browser _session history_ (that is, the pages visited in the tab or frame that the current page is loaded in). +- {{domxref("PopStateEvent")}} + - : The interface of the {{domxref("Window.popstate_event", "popstate")}} event. ## Examples -The following example assigns a listener to the `onpopstate` property. And then illustrates some of the methods of the history object to add, replace, and move within the browser history for the current tab. +The following example assigns a listener for the {{domxref("Window.popstate_event", "popstate")}} event. It then illustrates some of the methods of the history object to add, replace, and move within the browser history for the current tab. ```js -window.onpopstate = (event) => { +window.addEventListener("popstate", (event) => { alert( `location: ${document.location}, state: ${JSON.stringify(event.state)}` ); @@ -97,11 +101,5 @@ history.go(2); // alerts "location: http://example.com/example.html?page=3, stat ## See also -### References - -- {{ domxref("window.history") }} +- {{domxref("window.history", "history")}} global object - {{domxref("Window/popstate_event", "popstate")}} event - -### Guides - -- [Working with the History API](/en-US/docs/Web/API/History_API/Working_with_the_History_API) diff --git a/files/en-us/web/api/history_api/working_with_the_history_api/index.md b/files/en-us/web/api/history_api/working_with_the_history_api/index.md index 346327468e7f499..850edd482a50f88 100644 --- a/files/en-us/web/api/history_api/working_with_the_history_api/index.md +++ b/files/en-us/web/api/history_api/working_with_the_history_api/index.md @@ -5,6 +5,7 @@ page-type: guide --- {{DefaultAPISidebar("History API")}} + The {{DOMxRef("History.pushState","pushState()")}} and {{DOMxRef("History.replaceState","replaceState()")}} methods add and modify history entries, respectively. These methods work in conjunction with the {{domxref("Window/popstate_event", "popstate")}} event. ## Adding and modifying history entries @@ -16,7 +17,7 @@ Using {{DOMxRef("History.pushState","pushState()")}} changes the referrer that g Suppose `https://mozilla.org/foo.html` executes the following JavaScript: ```js -let stateObj = { +const stateObj = { foo: "bar", }; @@ -67,7 +68,9 @@ In other documents, it creates an element with a `null` namespace URI. Suppose `https://mozilla.org/foo.html` executes the following JavaScript: ```js -let stateObj = { foo: "bar" }; +const stateObj = { + foo: "bar", +}; history.pushState(stateObj, "page 2", "bar.html"); ``` @@ -96,11 +99,11 @@ When your page loads, it might have a non-null state object. This can happen, fo You can read the state of the current history entry without waiting for a `popstate` event using the {{DOMxRef("History.state","history.state")}} property like this: ```js -let currentState = history.state; +const currentState = history.state; ``` ## See also - [History API](/en-US/docs/Web/API/History_API) -- [Ajax navigation example](/en-US/docs/Web/API/History_API/Example) -- {{ domxref("window.history") }} +- [History navigation example](/en-US/docs/Web/API/History_API/Example) +- {{domxref("window.history", "history")}} global object diff --git a/files/en-us/web/api/popstateevent/index.md b/files/en-us/web/api/popstateevent/index.md index c906e57925d9871..9d47264e874c336 100644 --- a/files/en-us/web/api/popstateevent/index.md +++ b/files/en-us/web/api/popstateevent/index.md @@ -5,7 +5,7 @@ page-type: web-api-interface browser-compat: api.PopStateEvent --- -{{APIRef("HTML DOM")}} +{{APIRef("History API")}} **`PopStateEvent`** is an interface for the [`popstate`](/en-US/docs/Web/API/Window/popstate_event) event. diff --git a/files/en-us/web/api/popstateevent/popstateevent/index.md b/files/en-us/web/api/popstateevent/popstateevent/index.md new file mode 100644 index 000000000000000..8fed684b5c4d565 --- /dev/null +++ b/files/en-us/web/api/popstateevent/popstateevent/index.md @@ -0,0 +1,46 @@ +--- +title: PopStateEvent() +slug: Web/API/PopStateEvent/PopStateEvent +page-type: web-api-constructor +browser-compat: api.PopStateEvent.PopStateEvent +--- + +{{APIRef("History API")}} + +The **`PopStateEvent()`** constructor creates a new {{domxref("PopStateEvent")}} object. + +> **Note:** A web developer doesn't typically need to call this constructor, as the browser creates these objects itself when firing {{domxref("Window/popstate_event", "popstate")}} events. + +## Syntax + +```js-nolint +new PopStateEvent(type, options) +``` + +### Parameters + +- `type` + - : A string with the name of the event. + It is case-sensitive and browsers set it to `popstate`. +- `options` {{optional_inline}} + - : An object that, _in addition to the properties defined in {{domxref("Event/Event", "Event()")}}_, has the following property: + - `state` {{optional_inline}} + - : An object representing the state. Practically it is a value provided by the call to {{domxref("history.pushState()")}} or {{domxref("history.replaceState()")}}. If not set, it defaults to `null`. + +### Return value + +A new {{domxref("PopStateEvent")}} object. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("history.pushState()")}} +- {{domxref("history.replaceState()")}} +- {{domxref("Window/popstate_event", "popstate")}} event diff --git a/files/en-us/web/api/popstateevent/state/index.md b/files/en-us/web/api/popstateevent/state/index.md new file mode 100644 index 000000000000000..924cc79d0644583 --- /dev/null +++ b/files/en-us/web/api/popstateevent/state/index.md @@ -0,0 +1,56 @@ +--- +title: PopStateEvent.state +slug: Web/API/PopStateEvent/state +page-type: web-api-instance-property +browser-compat: api.PopStateEvent.state +--- + +{{ APIRef("History API") }} + +The **`state`** read-only property of the {{domxref("PopStateEvent")}} interface represents the state stored when the event was created. + +Practically it is a value provided by the call to {{domxref("history.pushState()")}} or {{domxref("history.replaceState()")}} + +## Value + +An object, or `null`. + +## Examples + +The code below logs the value of `state` when using the +{{domxref("History.pushState","pushState()")}} method to push a value to the history. + +```js +// Log the state of +addEventListener("popstate", (event) => { + console.log("State received: ", event.state); +}); + +// Now push something on the stack +history.pushState({ name: "Example" }, "pushState example", "page1.html"); +history.pushState( + { name: "Another example" }, + "pushState example", + "page1.html" +); +``` + +This will log: + +```plain +State received: { name: "Example" } +State received: { name: "Another example" } +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("PopStateEvent()")}} constructor +- {{domxref("History.state")}} diff --git a/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md b/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md index 54dccbc8621eb9d..ac549d0eb0811aa 100644 --- a/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md +++ b/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md @@ -79,7 +79,6 @@ Browsers must serialize the properties `name` and `message`, and are expected to - [HTML Specification: Safe passing of structured data](https://html.spec.whatwg.org/multipage/infrastructure.html#safe-passing-of-structured-data) - [Transferable objects](/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) - {{domxref("structuredClone()")}} -- {{domxref("window.history")}} - {{domxref("window.postMessage()")}} - [Web Workers](/en-US/docs/Web/API/Web_Workers_API) - [IndexedDB](/en-US/docs/Web/API/IndexedDB_API) diff --git a/files/en-us/web/api/window/forward/index.md b/files/en-us/web/api/window/forward/index.md index 245d10918ea9fa2..3f2c3d4236e11df 100644 --- a/files/en-us/web/api/window/forward/index.md +++ b/files/en-us/web/api/window/forward/index.md @@ -11,7 +11,7 @@ status: Moves the window one document forward in history. This was a Firefox-specific method and was removed in Firefox 31. -> **Note:** Use the standard {{domxref("History.forward", "window.history.forward()")}} method instead. +> **Note:** Use the standard {{domxref("History.forward", "history.forward()")}} method instead. ## Syntax diff --git a/files/en-us/web/api/window/index.md b/files/en-us/web/api/window/index.md index 4bcd94832a00696..ffa174b3aec822b 100644 --- a/files/en-us/web/api/window/index.md +++ b/files/en-us/web/api/window/index.md @@ -270,11 +270,11 @@ _This interface inherits methods from the {{domxref("EventTarget")}} interface a ### Deprecated methods - {{domxref("Window.back()")}} {{Non-standard_Inline}} {{Deprecated_Inline}} - - : Moves back one in the window history. This method is deprecated; you should instead use {{domxref("History.back", "window.history.back()")}}. + - : Moves back one in the window history. This method is deprecated; you should instead use {{domxref("History.back", "history.back()")}}. - {{domxref("Window.captureEvents()")}} {{Deprecated_Inline}} - : Registers the window to capture all events of the specified type. - {{domxref("Window.forward()")}} {{Non-standard_Inline}} {{Deprecated_Inline}} - - : Moves the window one document forward in the history. This method is deprecated; you should instead use {{domxref("History.forward", "window.history.forward()")}}. + - : Moves the window one document forward in the history. This method is deprecated; you should instead use {{domxref("History.forward", "history.forward()")}}. - {{domxref("Window.releaseEvents()")}} {{Deprecated_Inline}} - : Releases the window from trapping events of a specific type. - {{domxref("Window.showModalDialog()")}} {{Non-standard_Inline}} {{Deprecated_Inline}} diff --git a/files/en-us/web/api/window/popstate_event/index.md b/files/en-us/web/api/window/popstate_event/index.md index a8b1573d0230172..371e86be1cb5025 100644 --- a/files/en-us/web/api/window/popstate_event/index.md +++ b/files/en-us/web/api/window/popstate_event/index.md @@ -5,7 +5,7 @@ page-type: web-api-event browser-compat: api.Window.popstate_event --- -{{APIRef}} +{{APIRef("History API")}} The **`popstate`** event of the {{domxref("Window")}} interface is fired when the active history entry changes while the user navigates the session history. It changes the current history entry to that of the last page the user visited or, if {{domxref("history.pushState()")}} has been used to add a history entry to the history stack, that history entry is used instead. diff --git a/files/jsondata/GroupData.json b/files/jsondata/GroupData.json index 8441576e56cfdf0..c56df5eb3088447 100644 --- a/files/jsondata/GroupData.json +++ b/files/jsondata/GroupData.json @@ -560,10 +560,10 @@ "History API": { "overview": ["History API"], "guides": ["/docs/Web/API/History_API/Working_with_the_History_API"], - "interfaces": ["History"], + "interfaces": ["History", "PopStateEvent"], "methods": [], "properties": [], - "events": [] + "events": ["Window: popstate"] }, "HTML DOM": { "overview": ["HTML DOM API"], @@ -650,7 +650,6 @@ "PageTransitionEvent", "Plugin", "PluginArray", - "PopStateEvent", "PromiseRejectionEvent", "RadioNodeList", "UserActivation", @@ -711,7 +710,6 @@ "Window: online", "Window: pagehide", "Window: pageshow", - "Window: popstate", "Window: rejectionhandled", "Window: storage", "Window: unload",