History

The History API allows your add-on to manipulate the current page URL for use in navigation. When using the history module only the page anchor is modified and not the entire window location.

Note: This is only enabled for page modules (Admin page, General page, Configure page, User profile page). It cannot be used if the page module is launched as a dialog.

Example

1
2
3
4
5
6
7
8
9
10
11
// Register a function to run when state is changed.
// You should use this to update your UI to show the state.
AP.history.popState(function(e){
    alert("The URL has changed from: " + e.oldURL + "to: " + e.newURL);
});

// Adds a new entry to the history and changes the url in the browser.
AP.history.pushState("page2");

// Changes the URL back and invokes any registered popState callbacks.
AP.history.back();

Methods

back()

Goes back one step in the joint session history. Will invoke the popState callback.

Example

1
AP.history.back(); // go back by 1 entry in the browser history.

forward()

Goes forward one step in the joint session history. Will invoke the popState callback.

Example

1
AP.history.forward(); // go forward by 1 entry in the browser history.

go (delta)

Moves the page history back or forward the specified number of steps. A zero delta will reload the current page. If the delta is out of range, does nothing. This call invoke the popState callback.

Parameters

NameTypeDescription
delta

Integer

Number of places to move in the history

Example

1
AP.history.go(-2); // go back by 2 entries in the browser history.

getState (type, callback)

Retrieves the current state of the history stack and returns the value. The returned value is the same as what was set with the pushState method.

Parameters

NameTypeDescription
type

String

Type of requested value (optional). Valid values are undefined, "hash" and "all".

callback

function

Asynchronous callback (optional) if retrieving state during page load.

Returns

String

The current url anchor

Example

1
2
3
4
5
6
7
AP.history.pushState("page5");
AP.history.getState(); // returns "page5";

// asynchronous
AP.history.getState('hash', function(hash) {
  console.log("hash: ", hash);
});

pushState (newState)

Updates the location's anchor with the specified value and pushes the given data onto the session history. Does not invoke popState callback.

Parameters

NameTypeDescription
newState[String Object]

URL or state object to add to history


replaceState (newState)

Updates the current entry in the session history. Updates the location's anchor with the specified value but does not change the session history. Does not invoke popState callback.

Parameters

NameTypeDescription
newState[String Object]

URL or state object to update current history value with