up.history
up:location:changed
DOM event
This event is emitted after the browser's address bar was updated with a new URL.
There may be several reasons why the browser location was changed:
- A fragment update changes history through navigation or rendering with
{ history: true }. - The user uses the back or forward buttons in their browser UI.
- Programmatic calls to functions like
up.history.push()orhistory.pushState(). - The user navigates to a different
#hashwithin the page.
The up:location:changed event is not emitted when the page is loaded initially.
For this observe up:framework:booted.
Handling the change
This event cannot be prevented, but you can mutate the event.willHandle property to decide whether
Unpoly should handle the change by restoring a location or revealing a fragment matching the location #hash.
Location changes in overlays
Overlays can configure whether their history state is reflected the browser's address bar.
When a layer has no visible history, no up:location:changed event will be emitted.
However, an up:layer:location:changed will be emitted even if the address bar did not change.
Also see History in overlays.
Change
The new URL after the change.
When this event is emitted, the browser location has already been updated.
The action that caused this change in history state.
The value of this property is one of the following:
| Value | Reason |
|---|---|
'hash' |
The location was changed, but only the #hash changed from the previous location. |
'push' |
A new history entry was added via up.history.push() or history.pushState(). |
'replace' |
The current history update was changed via up.history.replace() or history.replaceState(). |
'pop' |
The user navigated back to the current location. |
Handling
Whether Unpoly thinks this change has already been handled and requires no additional processing.
For example, updating history by navigating or calling history.pushState() is
considered to be already handled.
Whether Unpoly thinks it is responsible for handling this change.
By default Unpoly feels responsible for owned locations when the change has not already been handled.
Listeners can tell Unpoly to not handle a change by setting event.willHandle = false.
You can then handle the change with your own code.
Listeners can tell Unpoly to handle a change it does not own by setting event.willHandle = true.
Regardless of this Unpoly will never handle a change that already been handled.