search

browserstate / history.js

History.js gracefully supports the HTML5 History/State APIs (pushState, replaceState, onPopState) in all browsers. Including continued support for data, titles, replaceState. Supports jQuery, MooTools and Prototype. For HTML5 browsers this means that you can modify the URL directly, without needing to use hashes anymore. For HTML4 browsers it will revert back to using the old onhashchange functionality.
http://browserstate.github.com/history.js/demo/
Other
10.75k stars 1.35k forks source link
hashchange html5-history html5-history-api javascript polyfill

readme

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

Slack community badge Patreon donate button Gratipay donate button Flattr donate button PayPal donate button Bitcoin donate button Wishlist browse button

News

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

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?

  1. www.mysite.com
  2. www.mysite.com/?state=1
  3. www.mysite.com/?state=2
  4. www.mysite.com/?state=3
  5. www.mysite.com/?state=4
  6. www.mysite.com/?state=3
  7. www.mysite.com/?state=1
  8. www.mysite.com
  9. 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?

  1. www.mysite.com
  2. www.mysite.com/#?state=1&_suid=1
  3. www.mysite.com/#?state=2&_suid=2
  4. www.mysite.com/#?state=3&_suid=3
  5. www.mysite.com/#?state=4
  6. www.mysite.com/#?state=3&_suid=3
  7. www.mysite.com/#?state=1&_suid=1
  8. www.mysite.com
  9. 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?

Is there a working demo?

Download & Installation

Note: If you want to only support HTML5 Browsers and not HTML4 Browsers (so no hash fallback support) then just change the /html4+html5/ part in the urls to just /html5/. See Why supporting HTML4 browsers could be either good or bad based on my app's use cases

Get Updates

Get Support

Thanks! every bit of help really does make a difference!

Browsers: Tested and Working In

HTML5 Browsers

HTML4 Browsers

Exposed API

Functions

States

Adapter

Navigation

Debug

Options

Events

Known Issues

Notes on Compatibility

License

Licensed under the New BSD License
Copyright © 2014+ Bevry Pty Ltd us@bevry.me
Copyright © 2011-2013 Benjamin Arthur Lupton b@lupton.cc

For support see the Getting Support section.