Memo

While there are some legitimate bugs and differences in state handling even in modern browsers, they are relatively small enough now that you can just use the native HTML5 History API. If you intend to support legacy browsers, then History.js is your bet.

This notice is here as History.js does not receive enough funding to be maintained, so it exists only in legacy condition for legacy browsers. Perhaps it still works for modern browsers, but it could really do with maintenance. Maintenance is very difficult as the library requires manual testing in HTML5 and HTML4 modes, and for each adapter, and for each browser. So that means 2^(# of adapters)^(# of browsers and their versions) tests that need to be run by a human. Tests need to be run by a human as certain failures require browser interactions, such as navigating from the test suite to a different domain and back again, or clicking the physical back buttons, or checking if the physical back buttons actually work. This takes a lot of time.

Despite History.js being one of the most popular JavaScript libraries there is, and has been used by even multi-million-user companies in its time - the reality of economy and company practices seems to be that companies prefer to fork their own internal versions and fix locally with their own devs rather than fund open-source maintainers what they would pay their own devs to make things better for everyone, including themselves, which would be cheaper - but no, that would require too many tiers of company approval that don't understand the need.

As such, if you are an open-source developer, I'd recommend just working on open-source projects that are paid for by your own consulting work or your own company (e.g. every successful open-source project). As otherwise, when they become popular, you better hope they are easily maintainable and testable, otherwise the cost of maintenance is higher than the free time of the maintainers.

So with all that said, this repo still exists for archival purposes, legacy browsers, and a hub for anarachistic issue & fork maintenance.

Cheers, Benjamin Lupton, founder of Bevry, creator of History.js

Welcome to History.js v1.8b2, June 22 2013

News

22/06/2013: Beta 2 of v1.8 is released. Fixes and uncompressed bundled files.
31/05/2013: Beta 1 of v1.8 is released. Fixes.
14/02/2013: Alpha 4 of v1.8 is released. Fixes.
05/02/2013: Alpha 3 of v1.8 is released. Tests updated.
21/01/2013: Alpha 2 of v1.8 is released. Correct statechange behaviour.
19/01/2013: Alpha 1 of v1.8 is released. Started to categorize old balupton's issues.

History

See the HISTORY.md file for a detailed list of features, changes, solved issues and bugs

Involve

Please create an issue if something doesn't work or if there is a browser specific bug. I'll try to fix it as soon as possible. Please send me your Pull requests if you have a nice solution! I'm also going to review old issues in balupton's repository and try to solve them too.

Aims

Follow the HTML5 History API as much as possible
Provide a cross-compatible experience for all HTML5 Browsers (they all implement the HTML5 History API a little bit differently causing different behaviours and sometimes bugs - History.js fixes this ensuring the experience is as expected / the same / great throughout the HTML5 browsers)
Provide a backwards-compatible experience for all HTML4 Browsers using a hash-fallback (including continued support for the HTML5 History API's data, title, pushState and replaceState) with the option to remove HTML4 support if it is not right for your application
Provide a forwards-compatible experience for HTML4 States to HTML5 States (so if a hash-fallbacked url is accessed by a HTML5 browser it is naturally transformed into its non-hashed url equivalent)
Provide support for as many javascript frameworks as possible via adapters; especially Dojo, ExtJS, jQuery, MooTools, Right.js and Zepto.

Quick Install

Via Ajaxify Script

To ajaxify your entire website with the HTML5 History API, History.js and jQuery the Ajaxify script is all you need. It's that easy.

Via Ajaxify Extension

If you don't have access to your server, or just want to try out the Ajaxify script first, you can install the History.js It! Google Chrome Extension to try out History.js via Ajaxify on select websites without actually installing History.js/Ajaxify on your server.

Via Ruby On Rails Gem

If you are using Rails, then the easiest way for you to try History.js would be to use Wiselinks gem. Wiselinks integrates into Rails application and allows you to start using History.js with three lines of code.

Direct Install

Working with History.js directly

(function(window,undefined){

	// Bind to StateChange Event
	History.Adapter.bind(window,'statechange',function(){ // Note: We are using statechange instead of popstate
		var State = History.getState(); // Note: We are using History.getState() instead of event.state
	});

	// Change our States
	History.pushState({state:1}, "State 1", "?state=1"); // logs {state:1}, "State 1", "?state=1"
	History.pushState({state:2}, "State 2", "?state=2"); // logs {state:2}, "State 2", "?state=2"
	History.replaceState({state:3}, "State 3", "?state=3"); // logs {state:3}, "State 3", "?state=3"
	History.pushState(null, null, "?state=4"); // logs {}, '', "?state=4"
	History.back(); // logs {state:3}, "State 3", "?state=3"
	History.back(); // logs {state:1}, "State 1", "?state=1"
	History.back(); // logs {}, "Home Page", "?"
	History.go(2); // logs {state:3}, "State 3", "?state=3"

})(window);

How would the above operations look in a HTML5 Browser?

www.mysite.com
www.mysite.com/?state=1
www.mysite.com/?state=2
www.mysite.com/?state=3
www.mysite.com/?state=4
www.mysite.com/?state=3
www.mysite.com/?state=1
www.mysite.com
www.mysite.com/?state=3

Note: These urls also work in HTML4 browsers and Search Engines. So no need for the hashbang (#!) fragment-identifier that google "recommends".

How would they look in a HTML4 Browser?

www.mysite.com
www.mysite.com/#?state=1&_suid=1
www.mysite.com/#?state=2&_suid=2
www.mysite.com/#?state=3&_suid=3
www.mysite.com/#?state=4
www.mysite.com/#?state=3&_suid=3
www.mysite.com/#?state=1&_suid=1
www.mysite.com
www.mysite.com/#?state=3&_suid=3

Note 1: These urls also work in HTML5 browsers - we use replaceState to transform these HTML4 states into their HTML5 equivalents so the user won't even notice :-)

Note 2: These urls will be automatically url-encoded in IE6 to prevent certain browser-specific bugs.

Note 3: Support for HTML4 browsers (this hash fallback) is optional - why supporting HTML4 browsers could be either good or bad based on my app's use cases

What's the deal with the SUIDs used in the HTML4 States?

SUIDs (State Unique Identifiers) are used when we utilise a title and/or data in our state. Adding a SUID allows us to associate particular states with data and titles while keeping the urls as simple as possible (don't worry it's all tested, working and a lot smarter than I'm making it out to be).
If you aren't utilising title or data then we don't even include a SUID (as there is no need for it) - as seen by State 4 above :-)
We also shrink the urls to make sure that the smallest url will be used. For instance we will adjust http://www.mysite.com/#http://www.mysite.com/projects/History.js to become http://www.mysite.com/#/projects/History.js automatically. (again tested, working, and smarter).

History.js

Install / Use

README