Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 250 lines (176 sloc) 13.828 kb
6f85fefc »
2011-02-11 Updated readme to reflect latest changes.
1 Welcome to History.js (v1.5.0 - Unreleased)
8d5cacfe »
2011-01-21 Initial Commit
2 ==================
3
4
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
5 This project is the successor of [jQuery History](http://balupton.com/projects/jquery-history), it aims to:
8d5cacfe »
2011-01-21 Initial Commit
6
bc79c006 »
2011-02-12 Fixed demo/test. Updated readme. Added note to .htaccess. Demo is now…
7 - Follow the [HTML5's History/State APIs](https://developer.mozilla.org/en/DOM/Manipulating_the_browser_history) as much as possible
8 - 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)
9 - 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](https://github.com/balupton/History.js/wiki/Intelligent-State-Handling)
10 - 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)
11 - Provide support for as many javascript frameworks as possible via adapters; especially [jQuery](http://jquery.com/), [MooTools](http://mootools.net/) and [Prototype](http://www.prototypejs.org/)
c76ef2c9 »
2011-01-26 Added graceful upgradation of HTML4 States to HTML5 Browsers... but i…
12
13 Licensed under the [New BSD License](http://creativecommons.org/licenses/BSD/)
14 Copyright 2011 [Benjamin Arthur Lupton](http://balupton.com)
88c3212d »
2011-01-21 Lots more working.
15
ba466c34 »
2011-01-21 Now working with prototype.
16
d2028b3f »
2011-01-21 Added Code Smaple in Documentation.
17 ## Usage
18
bc79c006 »
2011-02-12 Fixed demo/test. Updated readme. Added note to .htaccess. Demo is now…
19 ### Working with History.js:
d2028b3f »
2011-01-21 Added Code Smaple in Documentation.
20
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
21 (function(window,undefined){
d2028b3f »
2011-01-21 Added Code Smaple in Documentation.
22
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
23 var History = window.History; // Note: We are using a capital H instead of a lower h
d2028b3f »
2011-01-21 Added Code Smaple in Documentation.
24
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
25 History.Adapter.bind(window,'statechange',function(){ // Note: We are using statechange instead of popstate
26 var State = History.getState(); // Note: We are using History.getState() instead of event.state
27 History.log(State.data, State.title, State.url);
28 });
d2028b3f »
2011-01-21 Added Code Smaple in Documentation.
29
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
30 History.pushState({state:1}, "State 1", "?state=1"); // logs {state:1}, "State 1", "?state=1"
31 History.pushState({state:2}, "State 2", "?state=2"); // logs {state:2}, "State 2", "?state=2"
32 History.replaceState({state:3}, "State 3", "?state=3"); // logs {state:3}, "State 3", "?state=3"
33 History.pushState(null, null, "?state=4"); // logs {}, '', "?state=4"
34 History.back(); // logs {state:3}, "State 3", "?state=3"
35 History.back(); // logs {state:1}, "State 1", "?state=1"
36 History.back(); // logs {}, "Home Page", "?"
37 History.go(2); // logs {state:3}, "State 3", "?state=3"
d2028b3f »
2011-01-21 Added Code Smaple in Documentation.
38
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
39 })(window);
c76ef2c9 »
2011-01-26 Added graceful upgradation of HTML4 States to HTML5 Browsers... but i…
40
bc79c006 »
2011-02-12 Fixed demo/test. Updated readme. Added note to .htaccess. Demo is now…
41 ### How would the above operations look in a HTML5 Browser?
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
42
b0edf7a6 »
2011-02-10 Fixed readme formatting a bit. Attempt to add a subscribe form.
43 1. www.mysite.com
44 1. www.mysite.com?state=1
45 1. www.mysite.com?state=2
46 1. www.mysite.com?state=3
47 1. www.mysite.com?state=4
48 1. www.mysite.com?state=3
49 1. www.mysite.com?state=1
50 1. www.mysite.com
51 1. www.mysite.com?state=3
52
bc79c006 »
2011-02-12 Fixed demo/test. Updated readme. Added note to .htaccess. Demo is now…
53 > Note: These urls also work in HTML4 browsers and Search Engines. So no need for the hashbang (`#!`) fragment-identifier that google ["recommends"](https://github.com/balupton/History.js/wiki/Intelligent-State-Handling).
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
54
bc79c006 »
2011-02-12 Fixed demo/test. Updated readme. Added note to .htaccess. Demo is now…
55 ### How would they look in a HTML4 Browser?
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
56
b0edf7a6 »
2011-02-10 Fixed readme formatting a bit. Attempt to add a subscribe form.
57 1. www.mysite.com
58 1. www.mysite.com#?state=1/uid=1
59 1. www.mysite.com#?state=2/uid=2
60 1. www.mysite.com#?state=3/uid=3
61 1. www.mysite.com#?state=4
62 1. www.mysite.com#?state=3/uid=3
63 1. www.mysite.com#?state=1/uid=1
64 1. www.mysite.com
65 1. www.mysite.com#?state=3/uid=3
66
bc79c006 »
2011-02-12 Fixed demo/test. Updated readme. Added note to .htaccess. Demo is now…
67 > Note 1: These urls also work in HTML5 browsers - we use `replaceState` to transform these HTML4 states their HTML5 equivalents so the user won't even notice :-)
dc4cc15d »
2011-02-10 v1.4.0 Release
68 >
bc79c006 »
2011-02-12 Fixed demo/test. Updated readme. Added note to .htaccess. Demo is now…
69 > Note 2: These urls will be url-encoded in Firefox 3; IE6,7,8; and Safari 5. Opera does not url-encode the urls. The url-encoding is necessary for these browsers as otherwise it won't work. There is nothing we can do about this.
70 >
71 > 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](https://github.com/balupton/History.js/wiki/Intelligent-State-Handling)
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
72
bc79c006 »
2011-02-12 Fixed demo/test. Updated readme. Added note to .htaccess. Demo is now…
73 ### What's the deal with the UIDs used in the HTML4 States?
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
74
75 - UIDs are used when we utilise a `title` and/or `data` in our state. Adding a UID 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).
76 - If you aren't utilising `title` or `data` then we don't even include a UID (as there is no need for it) - as seen by State 4 above :-)
77 - 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).
78 - It works with domains, subdomains, subdirectories, whatever - doesn't matter where you put it. It's smart.
79
bc79c006 »
2011-02-12 Fixed demo/test. Updated readme. Added note to .htaccess. Demo is now…
80 ### Is there a working demo?
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
81
519ed6ea »
2011-02-09 Updated readme a bit more.
82 - Sure is, give it a download and navigate to the demo directory in your browser :-)
04697acc »
2011-02-10 v1.4.1 - Added HTML5 Supported for Safari 5 and Safari iOS 4.2.1
83 - If you are after something a bit more adventurous than a end-user demo, open up the tests directory in your browser and editor - it'll rock your world and show all the vast use cases that History.js supports. _Note: you will have to [run a `git submodule init; git submodule update` and update the `tests/.htaccess` for your path] prior to running the tests._
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
84
85
86 ## Download & Installation
f2ac286a »
2011-01-22 First version complete.
87
88 1. Download History.js and upload it to your webserver. Download links: [tar.gz](https://github.com/balupton/History.js/tarball/master) or [zip](https://github.com/balupton/History.js/zipball/master)
89
90 2. Include [JSON2](http://www.json.org/js.html) for HTML4 Browsers Only *(replace www.yourwebsite.com)*
91
92 <script type="text/javascript">
93 if ( typeof JSON === 'undefined' ) {
94 var
6f85fefc »
2011-02-11 Updated readme to reflect latest changes.
95 url = 'http://www.yourwebsite.com/history.js/scripts/compressed/json2.js',
f2ac286a »
2011-01-22 First version complete.
96 scriptEl = document.createElement('script');
97 scriptEl.type = 'text/javascript';
98 scriptEl.src = url;
99 document.body.appendChild(scriptEl);
100 }
101 </script>
102
103 3. Include the Adapter for your Framework:
104
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
105 - [jQuery](http://jquery.com/)
f2ac286a »
2011-01-22 First version complete.
106
6f85fefc »
2011-02-11 Updated readme to reflect latest changes.
107 <script type="text/javascript" src="http://www.yourwebsite.com/history.js/scripts/compressed/history.adapter.jquery.js"></script>
f2ac286a »
2011-01-22 First version complete.
108
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
109 - [Mootools](http://mootools.net/)
f2ac286a »
2011-01-22 First version complete.
110
6f85fefc »
2011-02-11 Updated readme to reflect latest changes.
111 <script type="text/javascript" src="http://www.yourwebsite.com/history.js/scripts/compressed/history.adapter.mootools.js"></script>
f2ac286a »
2011-01-22 First version complete.
112
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
113 - [Prototype](http://www.prototypejs.org/)
f2ac286a »
2011-01-22 First version complete.
114
6f85fefc »
2011-02-11 Updated readme to reflect latest changes.
115 <script type="text/javascript" src="http://www.yourwebsite.com/history.js/scripts/compressed/history.adapter.prototype.js"></script>
f2ac286a »
2011-01-22 First version complete.
116
f4e3f609 »
2011-02-09 Cleaned files. Improved documentation.
117 - _Would you like to support another framework? No problem! It's very easy to create adapters, and I'll be happy to include them or help out if you [let me know](https://github.com/balupton/history.js/issues) :-)_
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
118
6f85fefc »
2011-02-11 Updated readme to reflect latest changes.
119
bc79c006 »
2011-02-12 Fixed demo/test. Updated readme. Added note to .htaccess. Demo is now…
120 4. Include History.js
74d79b82 »
2011-02-11 Fixed readme
121
bc79c006 »
2011-02-12 Fixed demo/test. Updated readme. Added note to .htaccess. Demo is now…
122 <script type="text/javascript" src="http://www.yourwebsite.com/history.js/scripts/compressed/history.js"></script>
123 <script type="text/javascript" src="http://www.yourwebsite.com/history.js/scripts/compressed/history.html4.js"></script>
6f85fefc »
2011-02-11 Updated readme to reflect latest changes.
124
bc79c006 »
2011-02-12 Fixed demo/test. Updated readme. Added note to .htaccess. Demo is now…
125 > Note: If you want to only support HTML5 Browsers and not HTML4 Browsers (so no hash fallback support) then just remove the `history.html4.js` include in step #4 file and the JSON2 include in step #2 [- why supporting HTML4 browsers could be either good or bad based on my app's use cases](https://github.com/balupton/History.js/wiki/Intelligent-State-Handling)
f2ac286a »
2011-01-22 First version complete.
126
127
04697acc »
2011-02-10 v1.4.1 - Added HTML5 Supported for Safari 5 and Safari iOS 4.2.1
128 ## Subscribe to Updates
129
130 - For Email Updates:
02dcc4c2 »
2011-02-10 Added support section to readme.
131 - You can subscribe via the subscription form included in the demo page
04697acc »
2011-02-10 v1.4.1 - Added HTML5 Supported for Safari 5 and Safari iOS 4.2.1
132 - For Commit RSS/Atom Updates:
133 - You can subscribe via the [GitHub Commit Atom Feed](https://github.com/balupton/History.js/commits/master.atom)
44f28577 »
2011-02-10 Readme updates mostly on compatibility.
134 - For GitHub News Feed Updates:
135 - You can click the "watch" button up the top right of History.js's [GitHub Project Page](https://github.com/balupton/History.js)
04697acc »
2011-02-10 v1.4.1 - Added HTML5 Supported for Safari 5 and Safari iOS 4.2.1
136
137
02dcc4c2 »
2011-02-10 Added support section to readme.
138 ## Getting Support
139
44f28577 »
2011-02-10 Readme updates mostly on compatibility.
140 History.js is an actively developed, supported and maintained project. You can grab support via its [GitHub Issue Tracker](https://github.com/balupton/History.js/issues). Alternatively you can reach [Benjamin Lupton](http://balupton.com) (the core developer) via [twitter](http://twitter.com/balupton), skype (balupton) or email (contact@balupton.com).
02dcc4c2 »
2011-02-10 Added support section to readme.
141
142
f4e3f609 »
2011-02-09 Cleaned files. Improved documentation.
143 ## Browsers: Tested and Working In
ba466c34 »
2011-01-21 Now working with prototype.
144
f4e3f609 »
2011-02-09 Cleaned files. Improved documentation.
145 ### HTML5 Browsers
146
147 - Chrome 8,9
148 - Firefox 4
04697acc »
2011-02-10 v1.4.1 - Added HTML5 Supported for Safari 5 and Safari iOS 4.2.1
149 - Safari 5
150 - Safari iOS 4.2.1
f4e3f609 »
2011-02-09 Cleaned files. Improved documentation.
151
152 ### HTML4 Browsers
88c3212d »
2011-01-21 Lots more working.
153
aadfa613 »
2011-01-22 Tested in IE7,8. Better adapting testing. Adapter now does work being…
154 - Opera 10,11
88c3212d »
2011-01-21 Lots more working.
155 - Firefox 3
aadfa613 »
2011-01-22 Tested in IE7,8. Better adapting testing. Adapter now does work being…
156 - IE 6,7,8
f2ac286a »
2011-01-22 First version complete.
157
158
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
159 ## Exposed API
160
161 ### Functions
162
163 - `History.pushState(data,title,url)` <br/> Pushes a new state to the browser, `data` and `title` can be null
164 - `History.replaceState(data,title,url)` <br/> Replaces the existing state with a new state to the browser, `data` and `title` can be null
165 - `History.getState()` <br/> Get's the current state of the browser, returns an object with `data`, `title` and `url`
166 - `History.getHash()` <br/> Get's the current hash of the browser
f4e3f609 »
2011-02-09 Cleaned files. Improved documentation.
167 - `History.Adapter.bind(element,event,callback)` <br/> A framework independent event binder, you may either use this or your framework's native event binder.
168 - `History.Adapter.trigger(element,event)` <br/> A framework independent event trigger, you may either use this or your framework's native event trigger.
169 - `History.Adapter.onDomLoad(callback)` <br/> A framework independent onDomLoad binder, you may either use this or your framework's native onDomLoad binder.
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
170 - `History.back()` <br/> Go back once through the history (same as hitting the browser's back button)
171 - `History.forward()` <br/> Go forward once through the history (same as hitting the browser's forward button)
172 - `History.go(X)` <br/> If X is negative go back through history X times, if X is positive go forwards through history X times
173 - `History.log(...)` <br/> Logs messages to the console, the log element, and fallbacks to alert if neither of those two exist
174 - `History.debug(...)` <br/> Same as `History.log` but only runs if `History.debug.enable === true`
175
176 ### Events
177
178 - `window.onstatechange` <br/> Fired when the state of the page changes (does not include hashchanges)
179 - `window.onanchorchange` <br/> Fired when the anchor of the page changes (does not include state hashes)
180
181
7529b355 »
2011-01-24 Fixed Google Chrome issue. Now have to retest in HTML4 Browsers.
182 ## Notes on Compatibility
183
c76ef2c9 »
2011-01-26 Added graceful upgradation of HTML4 States to HTML5 Browsers... but i…
184 - State data will always contain the State's title and url at: `data.title` and `data.url`
44f28577 »
2011-02-10 Readme updates mostly on compatibility.
185 - State data and title will not persist if the page was closed then re-opened, or navigated to another website then back - this is expected/standard functionality
186 - State titles will always be applied to the `document.title` if set
187 - ReplaceState functionality is emulated in HTML4 browsers by discarding the replaced state, so when the discarded state is accessed it is skipped using the appropriate `History.back()` / `History.forward()` call
bc79c006 »
2011-02-12 Fixed demo/test. Updated readme. Added note to .htaccess. Demo is now…
188 - History.js resolves the following browser bugs:
189 - Chrome does not retrieve the correct state data when traversing back to the start page
190 - Safari 5 and Safari iOS 4.2.1 do not fire the `onpopstate` event on page load or when the hash has changed
191 - MSIE 6 and 7 sometimes do not actually apply hash-changes
192 - Non-Opera HTML4 browsers sometimes fail when the hash is not `urlencoded`
44f28577 »
2011-02-10 Readme updates mostly on compatibility.
193 - HTML4 Browsers on initial page load will have a hash inserted into the url; this is to ensure correct cross-compatibility between HTML4 browsers (as IE will refresh the page if the anchor is lost)
194 - Changing the hash of the page causes `onpopstate` to fire; this is expected/standard functionality. To ensure correct compatibility between HTML5 and HTML4 browsers the following events have been created:
195 - `window.onstatechange`: this is the same as onpopstate except does not fire for traditional anchors
196 - `window.onanchorchange`: this is the same as onhashchange except does not fire for states
7529b355 »
2011-01-24 Fixed Google Chrome issue. Now have to retest in HTML4 Browsers.
197
f2ac286a »
2011-01-22 First version complete.
198
c76ef2c9 »
2011-01-26 Added graceful upgradation of HTML4 States to HTML5 Browsers... but i…
199 ## Changelog
200
6f85fefc »
2011-02-11 Updated readme to reflect latest changes.
201 - v1.5.0 - Unreleased
202 - Moved to UglifyJS instead of Google Closure
203 - Split HTML4 functionality from HTML5 functionality
204 - Installation details have changed (the filenames are different)
205
04697acc »
2011-02-10 v1.4.1 - Added HTML5 Supported for Safari 5 and Safari iOS 4.2.1
206 - v1.4.1 - February 10 2011
207 - Added HTML History API Support for Safari 5 and Safari iOS 4.2.1
208 - Cleaned code a bit (mostly with unit tests)
209
dc4cc15d »
2011-02-10 v1.4.0 Release
210 - v1.4.0 - February 10 2011
f4e3f609 »
2011-02-09 Cleaned files. Improved documentation.
211 - Unit Testing now uses [QUnit](http://docs.jquery.com/Qunit)
212 - Corrected Safari 5 Support
213 - Now uses queues instead of timeouts
214 - This means the API works exactly as expected, no more need to wrap calls in timeouts
519ed6ea »
2011-02-09 Updated readme a bit more.
215 - Included a Subscribe Form in the Demo for Version Updates via Email
dc4cc15d »
2011-02-10 v1.4.0 Release
216 - Small updates to Documentation
f4e3f609 »
2011-02-09 Cleaned files. Improved documentation.
217
b3614b96 »
2011-02-04 Improved documentation.
218 - v1.3.1 - February 04 2011
219 - Improved Documentation
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
220
d1d85e72 »
2011-01-31 Fixed date in changelog for v1.3.0 release
221 - v1.3.0 - January 31 2011
c76ef2c9 »
2011-01-26 Added graceful upgradation of HTML4 States to HTML5 Browsers... but i…
222 - Support for cleaner HTML4 States
223
23d7a97a »
2011-01-31 Clean HTML4 States completed. Tests now have to run longer... 8 secon…
224 - v1.2.1 - January 30 2011
b564e7c8 »
2011-01-30 v1.2.1 - Re-Added History.go, updated the documentation, changed Hist…
225 - Fixed History.log always being called - [reported by dlee](https://github.com/balupton/History.js/issues/#issue/2)
226 - Re-Added `History.go(index)` support
227
23d7a97a »
2011-01-31 Clean HTML4 States completed. Tests now have to run longer... 8 secon…
228 - v1.2.0 - January 25 2011
c76ef2c9 »
2011-01-26 Added graceful upgradation of HTML4 States to HTML5 Browsers... but i…
229 - Support for HTML4 States in HTML5 Browsers (added test)
230 - Updates of Documentation
231
23d7a97a »
2011-01-31 Clean HTML4 States completed. Tests now have to run longer... 8 secon…
232 - v1.1.0 - January 24 2011
c76ef2c9 »
2011-01-26 Added graceful upgradation of HTML4 States to HTML5 Browsers... but i…
233 - Developed a series of automated test cases
234 - Fixed issue with traditional anchors
235 - Fixed issue with differing replaceState functionality in HTML4 Browsers
236 - Fixed issue with Google Chrome artefacts being carried over to the initial state
237 - Provided `onstatechange` and `onanchorchange` events
238
23d7a97a »
2011-01-31 Clean HTML4 States completed. Tests now have to run longer... 8 secon…
239 - v1.0.0 - January 22 2011
c76ef2c9 »
2011-01-26 Added graceful upgradation of HTML4 States to HTML5 Browsers... but i…
240 - Supported `History.pushState` and `History.replaceState` degradation
241 - Supported jQuery, MooTools and Prototype Frameworks
242
243
244 ## Todo for Upcoming Releases
245
583a3f7a »
2011-02-11 Performed split. Added uglify.
246 - Add data persistance to HTML4 browsers (navigate to 3rd party website, navigate back, state data should still be there)
247 - Default will use cookies (requires no configuration) - limited to a 4KB payload.
248 - Extension will use cookies and add an ajax pre-fetch to fetch full (unlimited) data (requires configuration through a server-side helper)
249 - Add an Ajax extension to succeed the [jQuery Ajaxy](http://balupton.com/projects/jquery-ajaxy) project
250 - Add a compilation test to ensure `.debug = false` and no `History.log` or `console.xxx` calls exist.
Something went wrong with that request. Please try again.