Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 216 lines (153 sloc) 10.73 kb
dc4cc15d »
2011-02-10 v1.4.0 Release
1 Welcome to History.js (v1.4.0 - February 10 2011)
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
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
7 - Support [HTML5's History/State APIs](https://developer.mozilla.org/en/DOM/Manipulating_the_browser_history)
8 - Provide a backwards compatible experience for Browsers which do not support HTML5's History APIs
9 - Provide a backwards compatible experience for Browsers which do not support HTML4's OnHashChange
10 - Provide a forwards compatible experience for HTML4 States in HTML5 Browsers (see usage section for an example)
11 - Follow the original API's as much as possible and support attaching data and title properties to states as well as both the `pushState` and `replaceState` methods in **both** HTML4 **and** HTML5 browsers.
12 - Support 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…
13
14 Licensed under the [New BSD License](http://creativecommons.org/licenses/BSD/)
15 Copyright 2011 [Benjamin Arthur Lupton](http://balupton.com)
88c3212d »
2011-01-21 Lots more working.
16
ba466c34 »
2011-01-21 Now working with prototype.
17
d2028b3f »
2011-01-21 Added Code Smaple in Documentation.
18 ## Usage
19
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
20 Working with History.js:
d2028b3f »
2011-01-21 Added Code Smaple in Documentation.
21
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
22 (function(window,undefined){
d2028b3f »
2011-01-21 Added Code Smaple in Documentation.
23
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
24 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.
25
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
26 History.Adapter.bind(window,'statechange',function(){ // Note: We are using statechange instead of popstate
27 var State = History.getState(); // Note: We are using History.getState() instead of event.state
28 History.log(State.data, State.title, State.url);
29 });
d2028b3f »
2011-01-21 Added Code Smaple in Documentation.
30
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
31 History.pushState({state:1}, "State 1", "?state=1"); // logs {state:1}, "State 1", "?state=1"
32 History.pushState({state:2}, "State 2", "?state=2"); // logs {state:2}, "State 2", "?state=2"
33 History.replaceState({state:3}, "State 3", "?state=3"); // logs {state:3}, "State 3", "?state=3"
34 History.pushState(null, null, "?state=4"); // logs {}, '', "?state=4"
35 History.back(); // logs {state:3}, "State 3", "?state=3"
36 History.back(); // logs {state:1}, "State 1", "?state=1"
37 History.back(); // logs {}, "Home Page", "?"
38 History.go(2); // logs {state:3}, "State 3", "?state=3"
d2028b3f »
2011-01-21 Added Code Smaple in Documentation.
39
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
40 })(window);
c76ef2c9 »
2011-01-26 Added graceful upgradation of HTML4 States to HTML5 Browsers... but i…
41
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
42 So how would the above operations look in a HTML5 Browser?
43
e23917f7 »
2011-02-02 Fixed example website state listing in readme.
44 > 1. www.mysite.com
45 > 1. www.mysite.com?state=1
46 > 1. www.mysite.com?state=2
47 > 1. www.mysite.com?state=3
48 > 1. www.mysite.com?state=4
49 > 1. www.mysite.com?state=3
50 > 1. www.mysite.com?state=1
51 > 1. www.mysite.com
52 > 1. www.mysite.com?state=3
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
53 >
54 > _Note: These urls also work in HTML4 browsers and Search Engines. So no need for the `#!` fragment-identifier that google ["recommends"](http://getsatisfaction.com/balupton/topics/support_googles_recommendation_for_ajax_deeplinking)._
55
56 And how would they look in a HTML4 Browser?
57
e23917f7 »
2011-02-02 Fixed example website state listing in readme.
58 > 1. www.mysite.com
59 > 1. www.mysite.com#?state=1/uid=1
60 > 1. www.mysite.com#?state=2/uid=2
61 > 1. www.mysite.com#?state=3/uid=3
62 > 1. www.mysite.com#?state=4
63 > 1. www.mysite.com#?state=3/uid=3
64 > 1. www.mysite.com#?state=1/uid=1
65 > 1. www.mysite.com
66 > 1. www.mysite.com#?state=3/uid=3
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
67 >
dc4cc15d »
2011-02-10 v1.4.0 Release
68 > _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 :-)_
69 >
70 > _Note 2: There 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._
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
71
72 What's the deal with the UIDs used in the HTML4 States?
73
74 - 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).
75 - 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 :-)
76 - 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).
77 - It works with domains, subdomains, subdirectories, whatever - doesn't matter where you put it. It's smart.
78
79 Is there a working demo?
80
519ed6ea »
2011-02-09 Updated readme a bit more.
81 - Sure is, give it a download and navigate to the demo directory in your browser :-)
82 - 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.
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
83
84
85 ## Download & Installation
f2ac286a »
2011-01-22 First version complete.
86
87 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)
88
89 2. Include [JSON2](http://www.json.org/js.html) for HTML4 Browsers Only *(replace www.yourwebsite.com)*
90
91 <script type="text/javascript">
92 if ( typeof JSON === 'undefined' ) {
93 var
94 url = 'http://www.yourwebsite.com/history.js/scripts/compressed/json2.min.js',
95 scriptEl = document.createElement('script');
96 scriptEl.type = 'text/javascript';
97 scriptEl.src = url;
98 document.body.appendChild(scriptEl);
99 }
100 </script>
101
102 3. Include the Adapter for your Framework:
103
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
104 - [jQuery](http://jquery.com/)
f2ac286a »
2011-01-22 First version complete.
105
106 <script type="text/javascript" src="http://www.yourwebsite.com/history.js/scripts/compressed/history.adapter.jquery.min.js"></script>
107
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
108 - [Mootools](http://mootools.net/)
f2ac286a »
2011-01-22 First version complete.
109
110 <script type="text/javascript" src="http://www.yourwebsite.com/history.js/scripts/compressed/history.adapter.mootools.min.js"></script>
111
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
112 - [Prototype](http://www.prototypejs.org/)
f2ac286a »
2011-01-22 First version complete.
113
114 <script type="text/javascript" src="http://www.yourwebsite.com/history.js/scripts/compressed/history.adapter.prototype.min.js"></script>
115
f4e3f609 »
2011-02-09 Cleaned files. Improved documentation.
116 - _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…
117
f2ac286a »
2011-01-22 First version complete.
118 4. Include History.js
119
120 <script type="text/javascript" src="http://www.yourwebsite.com/history.js/scripts/compressed/history.min.js"></script>
121
122
f4e3f609 »
2011-02-09 Cleaned files. Improved documentation.
123 ## Browsers: Tested and Working In
ba466c34 »
2011-01-21 Now working with prototype.
124
f4e3f609 »
2011-02-09 Cleaned files. Improved documentation.
125 ### HTML5 Browsers
126
127 - Chrome 8,9
128 - Firefox 4
129
130 ### HTML4 Browsers
88c3212d »
2011-01-21 Lots more working.
131
aadfa613 »
2011-01-22 Tested in IE7,8. Better adapting testing. Adapter now does work being…
132 - Opera 10,11
88c3212d »
2011-01-21 Lots more working.
133 - Safari 5
134 - Firefox 3
aadfa613 »
2011-01-22 Tested in IE7,8. Better adapting testing. Adapter now does work being…
135 - IE 6,7,8
f2ac286a »
2011-01-22 First version complete.
136
137
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
138 ## Exposed API
139
140 ### Functions
141
142 - `History.pushState(data,title,url)` <br/> Pushes a new state to the browser, `data` and `title` can be null
143 - `History.replaceState(data,title,url)` <br/> Replaces the existing state with a new state to the browser, `data` and `title` can be null
144 - `History.getState()` <br/> Get's the current state of the browser, returns an object with `data`, `title` and `url`
145 - `History.getHash()` <br/> Get's the current hash of the browser
f4e3f609 »
2011-02-09 Cleaned files. Improved documentation.
146 - `History.Adapter.bind(element,event,callback)` <br/> A framework independent event binder, you may either use this or your framework's native event binder.
147 - `History.Adapter.trigger(element,event)` <br/> A framework independent event trigger, you may either use this or your framework's native event trigger.
148 - `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…
149 - `History.back()` <br/> Go back once through the history (same as hitting the browser's back button)
150 - `History.forward()` <br/> Go forward once through the history (same as hitting the browser's forward button)
151 - `History.go(X)` <br/> If X is negative go back through history X times, if X is positive go forwards through history X times
152 - `History.log(...)` <br/> Logs messages to the console, the log element, and fallbacks to alert if neither of those two exist
153 - `History.debug(...)` <br/> Same as `History.log` but only runs if `History.debug.enable === true`
154
155 ### Events
156
157 - `window.onstatechange` <br/> Fired when the state of the page changes (does not include hashchanges)
158 - `window.onanchorchange` <br/> Fired when the anchor of the page changes (does not include state hashes)
159
160
7529b355 »
2011-01-24 Fixed Google Chrome issue. Now have to retest in HTML4 Browsers.
161 ## Notes on Compatibility
162
c76ef2c9 »
2011-01-26 Added graceful upgradation of HTML4 States to HTML5 Browsers... but i…
163 - State data will always contain the State's title and url at: `data.title` and `data.url`
23d7a97a »
2011-01-31 Clean HTML4 States completed. Tests now have to run longer... 8 secon…
164 - 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.
165 - State titles will always be applied to the document.title if set.
c76ef2c9 »
2011-01-26 Added graceful upgradation of HTML4 States to HTML5 Browsers... but i…
166 - 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.
7529b355 »
2011-01-24 Fixed Google Chrome issue. Now have to retest in HTML4 Browsers.
167 - History.js fixes a bug in Google Chrome where traversing back through the history to the home page does not return the correct state data.
168 - Setting a hash (even in HTML5 browsers) causes `onpopstate` to fire - this is expected/standard functionality.
3cde3348 »
2011-01-25 Updated documentation for v1.1
169 - As such, to ensure correct compatability between HTML5 and HTML4 browsers, we now have two new events:
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
170 - `window.onstatechange`: this is the same as onpopstate except does not fire for traditional anchors
171 - `window.onanchorchange`: this is the same as onhashchange except does not fire for states
3cde3348 »
2011-01-25 Updated documentation for v1.1
172 - To fetch the anchor/hash, you may use `History.getHash()`.
7529b355 »
2011-01-24 Fixed Google Chrome issue. Now have to retest in HTML4 Browsers.
173
f2ac286a »
2011-01-22 First version complete.
174
c76ef2c9 »
2011-01-26 Added graceful upgradation of HTML4 States to HTML5 Browsers... but i…
175 ## Changelog
176
dc4cc15d »
2011-02-10 v1.4.0 Release
177 - v1.4.0 - February 10 2011
f4e3f609 »
2011-02-09 Cleaned files. Improved documentation.
178 - Unit Testing now uses [QUnit](http://docs.jquery.com/Qunit)
179 - Corrected Safari 5 Support
180 - Now uses queues instead of timeouts
181 - 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.
182 - Included a Subscribe Form in the Demo for Version Updates via Email
dc4cc15d »
2011-02-10 v1.4.0 Release
183 - Small updates to Documentation
f4e3f609 »
2011-02-09 Cleaned files. Improved documentation.
184
b3614b96 »
2011-02-04 Improved documentation.
185 - v1.3.1 - February 04 2011
186 - Improved Documentation
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
187
d1d85e72 »
2011-01-31 Fixed date in changelog for v1.3.0 release
188 - v1.3.0 - January 31 2011
c76ef2c9 »
2011-01-26 Added graceful upgradation of HTML4 States to HTML5 Browsers... but i…
189 - Support for cleaner HTML4 States
190
23d7a97a »
2011-01-31 Clean HTML4 States completed. Tests now have to run longer... 8 secon…
191 - v1.2.1 - January 30 2011
b564e7c8 »
2011-01-30 v1.2.1 - Re-Added History.go, updated the documentation, changed Hist…
192 - Fixed History.log always being called - [reported by dlee](https://github.com/balupton/History.js/issues/#issue/2)
193 - Re-Added `History.go(index)` support
194
23d7a97a »
2011-01-31 Clean HTML4 States completed. Tests now have to run longer... 8 secon…
195 - v1.2.0 - January 25 2011
c76ef2c9 »
2011-01-26 Added graceful upgradation of HTML4 States to HTML5 Browsers... but i…
196 - Support for HTML4 States in HTML5 Browsers (added test)
197 - Updates of Documentation
198
23d7a97a »
2011-01-31 Clean HTML4 States completed. Tests now have to run longer... 8 secon…
199 - v1.1.0 - January 24 2011
c76ef2c9 »
2011-01-26 Added graceful upgradation of HTML4 States to HTML5 Browsers... but i…
200 - Developed a series of automated test cases
201 - Fixed issue with traditional anchors
202 - Fixed issue with differing replaceState functionality in HTML4 Browsers
203 - Fixed issue with Google Chrome artefacts being carried over to the initial state
204 - Provided `onstatechange` and `onanchorchange` events
205
23d7a97a »
2011-01-31 Clean HTML4 States completed. Tests now have to run longer... 8 secon…
206 - v1.0.0 - January 22 2011
c76ef2c9 »
2011-01-26 Added graceful upgradation of HTML4 States to HTML5 Browsers... but i…
207 - Supported `History.pushState` and `History.replaceState` degradation
208 - Supported jQuery, MooTools and Prototype Frameworks
209
210
211 ## Todo for Upcoming Releases
212
dc4cc15d »
2011-02-10 v1.4.0 Release
213 - Normal: Style Demo
519ed6ea »
2011-02-09 Updated readme a bit more.
214 - Normal: Add `History.queue`
09127bad »
2011-02-02 Cleaned documentation, a few other things. Not ready yet as some test…
215 - Minor: Add a compilation test to ensure `.debug = false` and no `History.log` calls exist.
Something went wrong with that request. Please try again.