You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+28-8Lines changed: 28 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,6 +3,7 @@ Welcome to History.js <br/> v1.8b2, June 22 2013
3
3
4
4
[](https://flattr.com/submit/auto?user_id=balupton&url=https://github.com/browserstate/history.js&title=History.js&language=&tags=github&category=software)
5
5
6
+
6
7
## News
7
8
- 22/06/2013: Beta 2 of v1.8 is released. Fixes and uncompressed bundled files.
8
9
- 31/05/2013: Beta 1 of v1.8 is released. Fixes.
@@ -11,14 +12,15 @@ Welcome to History.js <br/> v1.8b2, June 22 2013
11
12
- 21/01/2013: Alpha 2 of v1.8 is released. Correct statechange behaviour.
12
13
- 19/01/2013: Alpha 1 of v1.8 is released. Started to categorize old balupton's issues.
13
14
15
+
14
16
### History
17
+
[See the `History.md` file for a detailed list of features, changes, solved issues and bugs](https://github.com/browserstate/history.js/blob/master/History.md#files)
15
18
16
-
See the [`History.md`](https://github.com/browserstate/history.js/blob/master/History.md#files) file for a detailed list of features, changes, solved issues and bugs
17
19
18
20
### Involve
19
-
20
21
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.
21
22
23
+
22
24
## Aims
23
25
24
26
- Follow the [HTML5 History API](https://developer.mozilla.org/en/DOM/Manipulating_the_browser_history) as much as possible
@@ -27,16 +29,21 @@ Please create an issue if something doesn't work or if there is a browser specif
27
29
- 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)
28
30
- Provide support for as many javascript frameworks as possible via adapters; especially [Dojo](http://dojotoolkit.org/), [ExtJS](http://www.sencha.com/), [jQuery](http://jquery.com/), [MooTools](http://mootools.net/), [Right.js](http://rightjs.org/) and [Zepto](http://zeptojs.com/).
29
31
30
-
## Usage
31
32
32
-
### Instant
33
+
##Quick Install
33
34
34
-
To ajaxify your entire website with the HTML5 History API, History.js and jQuery the [Ajaxify Script](https://github.com/browserstate/ajaxify) is all you need. It's that easy.
35
+
### Via Ajaxify Script
36
+
To ajaxify your entire website with the HTML5 History API, History.js and jQuery the [Ajaxify script](https://github.com/browserstate/ajaxify) is all you need. It's that easy.
35
37
36
-
### Ruby On Rails
38
+
### Via Ajaxify Extension
39
+
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](https://github.com/browserstate/historyjsit.crx) to try out History.js via Ajaxify on select websites without actually installing History.js/Ajaxify on your server.
37
40
41
+
### Via Ruby On Rails Gem
38
42
If you are using Rails, then the easiest way for you to try History.js would be to use [Wiselinks](https://github.com/igor-alexandrov/wiselinks) gem. Wiselinks integrates into Rails application and allows you to start using History.js with three lines of code.
39
43
44
+
45
+
## Direct Install
46
+
40
47
### Working with History.js directly
41
48
42
49
```javascript
@@ -60,6 +67,7 @@ If you are using Rails, then the easiest way for you to try History.js would be
60
67
})(window);
61
68
```
62
69
70
+
63
71
### How would the above operations look in a HTML5 Browser?
64
72
65
73
1.www.mysite.com
@@ -74,6 +82,7 @@ If you are using Rails, then the easiest way for you to try History.js would be
74
82
75
83
> 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/browserstate/history.js/wiki/Intelligent-State-Handling).
76
84
85
+
77
86
### How would they look in a HTML4 Browser?
78
87
79
88
1.www.mysite.com
@@ -92,6 +101,7 @@ If you are using Rails, then the easiest way for you to try History.js would be
92
101
>
93
102
> 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/browserstate/history.js/wiki/Intelligent-State-Handling)
94
103
104
+
95
105
### What's the deal with the SUIDs used in the HTML4 States?
96
106
97
107
- 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).
@@ -100,11 +110,13 @@ If you are using Rails, then the easiest way for you to try History.js would be
100
110
- It works with domains, subdomains, subdirectories, whatever - doesn't matter where you put it. It's smart.
101
111
- Safari 5 will also have a SUID appended to the URL, it is entirely transparent but just a visible side-effect. It is required to fix a bug with Safari 5.
102
112
113
+
103
114
### Is there a working demo?
104
115
105
116
- Sure is, give it a download and navigate to the demo directory in your browser :-)
106
117
- 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.
107
118
119
+
108
120
## Download & Installation
109
121
110
122
- Download History.js and upload it to your webserver. Download links: [tar.gz](https://github.com/browserstate/history.js/tarball/master) or [zip](https://github.com/browserstate/history.js/zipball/master)
@@ -183,6 +195,7 @@ If you are using Rails, then the easiest way for you to try History.js would be
183
195
Thanks! every bit of help really does make a difference!
184
196
185
197
198
+
186
199
## Browsers: Tested and Working In
187
200
188
201
### HTML5 Browsers
@@ -193,6 +206,7 @@ Thanks! every bit of help really does make a difference!
193
206
- Safari 5.0+
194
207
- Safari iOS 4.3+
195
208
209
+
196
210
### HTML4 Browsers
197
211
198
212
- IE 6, 7, 8, 9, (10)
@@ -202,11 +216,13 @@ Thanks! every bit of help really does make a difference!
202
216
- Safari iOS 4.2, 4.1, 4.0, 3.2
203
217
204
218
219
+
205
220
## Exposed API
206
221
207
222
### Functions
208
223
209
224
#### States
225
+
210
226
-`History.pushState(data,title,url)` <br/> Pushes a new state to the browser; `data` can be null or an object, `title` can be null or a string, `url` must be a string
211
227
-`History.replaceState(data,title,url)` <br/> Replaces the existing state with a new state to the browser; `data` can be null or an object, `title` can be null or a string, `url` must be a string
212
228
-`History.getState()` <br/> Gets the current state of the browser, returns an object with `data`, `title` and `url`
@@ -215,16 +231,19 @@ Thanks! every bit of help really does make a difference!
215
231
-`History.getHash()` <br/> Gets the current hash of the browser
216
232
217
233
#### Adapter
234
+
218
235
-`History.Adapter.bind(element,event,callback)` <br/> A framework independent event binder, you may either use this or your framework's native event binder.
219
236
-`History.Adapter.trigger(element,event)` <br/> A framework independent event trigger, you may either use this or your framework's native event trigger.
220
237
-`History.Adapter.onDomLoad(callback)` <br/> A framework independent onDomLoad binder, you may either use this or your framework's native onDomLoad binder.
221
238
222
239
#### Navigation
240
+
223
241
-`History.back()` <br/> Go back once through the history (same as hitting the browser's back button)
224
242
-`History.forward()` <br/> Go forward once through the history (same as hitting the browser's forward button)
225
243
-`History.go(X)` <br/> If X is negative go back through history X times, if X is positive go forwards through history X times
226
244
227
245
#### Debug
246
+
228
247
-`History.log(...)` <br/> Logs messages to the console, the log element, and fallbacks to alert if neither of those two exist
229
248
-`History.debug(...)` <br/> Same as `History.log` but only runs if `History.debug.enable === true`
230
249
@@ -243,6 +262,7 @@ Thanks! every bit of help really does make a difference!
243
262
-`History.options.html4Mode` <br/> If true, will force HTMl4 mode (hashtags)
244
263
-`History.options.delayInit` <br/> Want to override default options and call init manually.
245
264
265
+
246
266
### Events
247
267
248
268
-`window.onstatechange` <br/> Fired when the state of the page changes (does not include hash changes)
@@ -283,10 +303,10 @@ Thanks! every bit of help really does make a difference!
283
303
284
304
## History
285
305
286
-
You can discover the history inside the [History.md](https://github.com/browserstate/history.js/blob/master/History.md#files) file
306
+
[You can discover the history inside the `History.md` file](https://github.com/browserstate/history.js/blob/master/History.md#files)
287
307
288
308
289
309
## License
290
310
291
311
Licensed under the [New BSD License](http://opensource.org/licenses/BSD-3-Clause)
0 commit comments