html5 - How do I use window.history in JavaScript? -

i found lot of questions on stack overflow, specific parts. did find this question answers provide nice references, don't explain how works, , examples hardly anything. want know more how works together, , want use vanilla javascript.

(also, many of answers on other questions years old.)

getting started

first of all, can remove window part. history works fine. before how works together, need know can use.

important events

window.onload

this event fires whenever webpage loaded. there 2 cases fire event:

1. when webpage navigated webpage. note wrote webpage, not website. moving between pages on same site trigger event.
2. just after webpage refreshed.

window.onpopstate

this event fires when navigate between history states you have set. browser automatically sets history states (to null) during normal browsing, navigating to/from these states not trigger event.

window.onunload

this event fires whenever webpage unloaded. there 2 cases fire event:

1. when navigate webpage webpage.
2. just before webpage refreshed.

important objects

the history interface contains 5 functions (described below), 2 read-only objects (described here), , works bit linked list. 2 objects contained in each 'link' of history object are:

• length - number of history states current browser window. starts @ 1.
• state - javascript object can contain practically anything. null default.

you can access them calling history.length , history.state respectively, though history.state can used current history state.

important functions

history.go(distance)

this function same thing pressing or forward button in browser, added functionality of being able specify how far want go. example, history.go(3) has same effect pushing forward button 3 times, without loading pages between start , end locations. negative value likewise move backwards through history. history.go(0), history.go(), , history.go(nan) have same effect refreshing page (this not trigger popstate event). if cannot move forward/backward far specified, function nothing.

history.back()

this function has same functionality button in browser. equivalent history.go(-1). if cannot go back, function nothing.

history.forward()

this function has same functionality forward button in browser. equivalent history.go(1). if cannot go forward, function nothing.

history.replacestate(state, title[, location])

this function replaces current history state. takes 3 arguments, though last 1 optional. arguments are:

• state - important argument. object give argument saved history.state later retrieval. deep copy, if later modify original object not change saved state. set null, if aren't going use it, there's not point in using history @ all.
• title - html standard suggests string passed argument used browser in user interface, no browser it.
• location - argument allows change url relative current page. cannot used change url of website, can used change url of page on your website. advise against however, page not reloaded though url of page. using back/forward show changed url, not change page, , trigger popstate rather load or unload. refreshing page after changing url load page specified url rather page on. functionality used provide link page in current state, recommend changing query string rather full url. if argument not used, url not change.

history.pushstate(state, title[, location])

this function works same history.replacestate, except puts new state after current state instead of replacing current state. history states have been accessed forward discarded, , new state becomes current state.

assembling pieces

the history interface useful allowing users navigate through dynamically generated content within browser without having reload entire page, need mindful of possible things users could affect history state.

1. first time navigating page
   • should users greeted menu/list, specific dynamically generated content, or maybe random dynamically generated content?
   • will page display correctly without history, or javascript?
2. using back/forward return page
   • should users see same thing saw first time, or should see result of visit reflected in content? (a "welcome back" message might nice touch some, unwanted distraction others.)
3. refreshing page
   • should new page, return start page, or reload same page? (your users won't expect last 1 if url hasn't changed.)
4. using back/forward refreshed page
   • should new content relative refreshed page, or reload saved state?
5. navigating away page
   • do need save before leaving?
6. returning page via deep link
   • do have code in place recognize , handle deep link?

note there no way delete saved state (other specific case pushstate() mentioned above). can replace new content.

putting together

since starting bit wordy, lets finish off code.

// function called when page first loaded, when page refreshed, // , when returning page page using back/forward. // navigating different page history.pushstate , going // not trigger event page not reloaded. window.onload = function() {   // remember browser automatically sets state null on   // first visit, if check , find null, know   // user hasn't been here yet.   if (history.state == null) {     // stuff on first load.   } else {     // stuff on refresh or on returning page page     // using back/forward. may want make window.onpopstate function     // below named function, , call function here.   }    // can of course have code execute in 3 cases. go here.    // may wish set history state @ time. go in   // if..else statement above if want replace state in   // circumstances. 1 reason setting state right away if user   // navigates page via deep link.   var state = ...; // there might not set @ point since page                    // loaded, if page gets random content, or time-                    // dependent content, may want save here can                    // retrieved again later.   var title = ...; // since isn't used browser yet, can put                    // want here, though recommend setting                    // null or document.title when browsers start doing                    // it.   var url = ...;   // don't want change url yet since page                    // has been loaded, in case shouldn't use                    // variable. 1 reason might want change url if                    // user navigated page query string in url. after                    // reading query string, can remove setting                    // variable to: location.origin + location.pathname   history.replacestate(state, title, url); // since page has been loaded,                                            // don't want push new state; should                                            // replace current state. }  // function called when navigating between states have set. // since purpose of `history` allow dynamic content changes without // reloading page (ie contacting server), code in function // should simple. things replacing text content , images. window.onpopstate = function() {   // things history.state here. }  // function called right before page refreshed, , right // before leaving page (not counting history.replacestate). // last chance set page's history state before leaving. window.onunload = function() {   // "how know if user navigating away page or refreshing it?"   // well, can't. @ least not history interface. it's possible   // http referer url , check if it's different page's url, won't   // work of time: https://en.wikipedia.org/wiki/http_referer#referer_hiding } 

notice never called history.pushstate anywhere. because history.pushstate should not called anywhere in these functions. should called function changes page in way want users able use button undo.

so in conclusion, generic setup might work this:

• check if (history.state == null) in window.onload function.
  • if true, overwrite history state new information.
  • if false, use history state restore page.
• while user navigating page, call history.pushstate when important things happen should undoable button.
• if/when user uses button , popstate event triggered, use history state set return page previous state.
  • do likewise if/when user uses forward button.
• use unload event finalize history state before user leaves page.