ko.routing: history & manual routing

All routers have an history property containing an history object that may be used to set manually the router current url and to navigate among past urls. The history object of the main router is connected with the browser history, while the history object of all local routers simulates the back-forward url navigation, and provides some observables that may be connected to some UI to implement a local navigation bar.

The following methods are common to all history objects:

  • set(url, replace, title). Sets url as the current url. If replace is true, the back and forward urls are unaffected, otherwise, as usual, the previous url is pushed in the back stack and the forward stack is cleared. After that the router is invoked on the hash part of the url. If the router has the fakeUrls option set the router is invoked on the whole url. If we pass just the hash part of the url, a complete url is formed by prepending the server part of the current url.
    The title argument is processed only by local router history objects, that handle a virtual document title.
  • back([x]). Moves, x places back in the url history. If x is omitted its default is  1.
  • forward([x]). Moves, x places forward in the url history. If x is omitted its default is 1.
  • go(x). if x<0 it moves x places back in the url history, otherwise if x>0 it moves x places forward in the url history.

The following methods are specific for the main router history object:

  • refresh(). Repeat routing on the current url. Useful to start routing on the initial page url as soon as the Html page is loaded. There is no equivalent method for local routers histories, since for local routers histories the set method triggers routing also when the url doesn't change.

The following methods are specific for the local router history objects.

  • clear(url, title). Clears the whole urls history and sets new url and title.

The following observables are specific  for the local router history objects:

  • url. Contains the current url.
  • title. Contains the current title.
  • canBack. True if the back stack is not empty.
  • canForward. True if the forward stack is not empty.

The above observables may be used to implement an UI for the history navigation.