Permalink
Browse files

markdown changes

  • Loading branch information...
1 parent 8c63aaf commit a7ad47928d18fe94206b28c6d21d19569b2ef210 @defunkt defunkt committed Jun 29, 2011
Showing with 102 additions and 74 deletions.
  1. +102 −74 README.md
View
176 README.md
@@ -34,85 +34,102 @@ You can find a demo on <http://pjax.heroku.com/>
## three ways to pjax on the client side:
-1. Functionally obtrusive, loading the href with ajax into data-pjax:
+One. Functionally obtrusive, loading the href with ajax into data-pjax:
- <a href='/explore' data-pjax='#main'>Explore</a>
-
- $('a[data-pjax]').pjax()
+```html
+<a href='/explore' data-pjax='#main'>Explore</a>
+```
+```js
+$('a[data-pjax]').pjax()
+```
-2. Slightly obtrusive, passing a container and jQuery ajax options:
- <a href='/explore' class='js-pjax'>Explore</a>
-
- $('a.js-pjax').pjax('#main', { timeout: null, error: function(xhr, err){
- $('.error').text('Something went wrong: ' + err)
- })
+Two. Slightly obtrusive, passing a container and jQuery ajax options:
+```html
+<a href='/explore' class='js-pjax'>Explore</a>
+```
-3. Unobtrusive, showing a 'loading' spinner:
+```js
+$('.js-pjax').pjax('#main', { timeout: null, error: function(xhr, err){
+ $('.error').text('Something went wrong: ' + err)
+})
+```
- <div id='main'>
- <div class='loader' style='display:none'><img src='spin.gif'></div>
- <div class='tabs'>
- <a href='/explore'>Explore</a>
- <a href='/help'>Help</a>
- </div>
- </div>
-
- $('a').pjax('#main').live('click', function(){
- $(this).showLoader()
- })
+
+Three. Unobtrusive, showing a 'loading' spinner:
+
+```html
+<div id='main'>
+ <div class='loader' style='display:none'><img src='spin.gif'></div>
+ <div class='tabs'>
+ <a href='/explore'>Explore</a>
+ <a href='/help'>Help</a>
+ </div>
+</div>
+```
+
+```js
+$('a').pjax('#main').live('click', function(){
+ $(this).showLoader()
+})
+```
## $(link).pjax( container, options )
-The $(link).pjax() function accepts a container, an options object,
+The `$(link).pjax()` function accepts a container, an options object,
or both. The container MUST be a string selector - this is because we
cannot persist jQuery objects using the History API between page loads.
-The options are the same as jQuery's $.ajax options with the
+The options are the same as jQuery's `$.ajax` options with the
following additions:
- container - The String selector of the container to load the reponse
- body. Must be a String.
- clickedElement - The element that was clicked to start the pjax call.
- push - Whether to pushState the URL. Defaults to true (of course).
- replace - Whether to replaceState the URL. Defaults to false.
- timeout - pjax sets this low, <1s. Set this higher if using a custom
- error handler. It's ms, so something like `timeout: 2000`
- error - By default this callback reloads the target page once
- `timeout` ms elapses.
+* `container` - The String selector of the container to load the
+ reponse body. Must be a String.
+* `clickedElement` - The element that was clicked to start the pjax call.
+* `push` - Whether to pushState the URL. Default: true (of course)
+* `replace` - Whether to replaceState the URL. Default: false
+* `error` - By default this callback reloads the target page once
+ `timeout` ms elapses.
+* `timeout` - pjax sets this low, <1s. Set this higher if using a
+ custom error handler. It's ms, so something like
+ `timeout: 2000`
## $.pjax( options )
-You can also just call $.pjax directly. It acts much like $.ajax, even
+You can also just call `$.pjax` directly. It acts much like `$.ajax`, even
returning the same thing and accepting the same options.
-The pjax-specific keys listed in the $(link).pjax() section work here
+The pjax-specific keys listed in the `$(link).pjax()` section work here
as well.
This pjax call:
- $.pjax({
- url: '/authors',
- container: '#main'
- })
+```js
+$.pjax({
+ url: '/authors',
+ container: '#main'
+})
+```
Roughly translates into this ajax call:
- $.ajax({
- url: '/authors',
- dataType: 'html',
- beforeSend: function(xhr){
- xhr.setRequestHeader('X-PJAX', 'true')
- },
- success: function(data){
- $('#main').html(data)
- history.pushState(null, $(data).filter('title').text(), '/authors')
- })
- })
+```js
+$.ajax({
+ url: '/authors',
+ dataType: 'html',
+ beforeSend: function(xhr){
+ xhr.setRequestHeader('X-PJAX', 'true')
+ },
+ success: function(data){
+ $('#main').html(data)
+ history.pushState(null, $(data).filter('title').text(), '/authors')
+ })
+})
+```
## pjax on the server side
@@ -125,11 +142,13 @@ header to 'true' when it makes an ajax request to make detecting it easy.
In Rails, check for `request.headers['X-PJAX']`:
- def my_page
- if request.headers['X-PJAX']
- render :layout => false
- end
- end
+```ruby
+def my_page
+ if request.headers['X-PJAX']
+ render :layout => false
+ end
+end
+```
Django: <https://github.com/jacobian/django-pjax>
@@ -146,23 +165,26 @@ Your HTML should also include a `<title>` tag if you want page titles to work.
pjax will fire two events on the container you've asked it to load your
reponse body into:
-* start.pjax - Fired when a pjax ajax request begins.
-* end.pjax - Fired when a pjax ajax request ends.
+* `start.pjax` - Fired when a pjax ajax request begins.
+* `end.pjax` - Fired when a pjax ajax request ends.
This allows you to, say, display a loading indicator upon pjaxing:
- $('a.pjax').pjax('#main')
- $('#main')
- .bind('start.pjax', function() { $('#loading').show() })
- .bind('end.pjax', function() { $('#loading').hide() })
+```js
+$('a.pjax').pjax('#main')
+$('#main')
+ .bind('start.pjax', function() { $('#loading').show() })
+ .bind('end.pjax', function() { $('#loading').hide() })
+```
Because these events bubble, you can also set them on the body:
- $('a.pjax').pjax()
- $('body')
- .bind('start.pjax', function() { $('#loading').show() })
- .bind('end.pjax', function() { $('#loading').hide() })
-
+```js
+$('a.pjax').pjax()
+$('body')
+ .bind('start.pjax', function() { $('#loading').show() })
+ .bind('end.pjax', function() { $('#loading').hide() })
+```
## browser support
@@ -178,21 +200,27 @@ work normally) and `$.pjax({url:url})` calls will redirect to the given URL.
## install it
- $ cd path/to/js
- $ wget https://github.com/defunkt/jquery-pjax/raw/master/jquery.pjax.js
+```
+$ cd path/to/js
+$ wget https://github.com/defunkt/jquery-pjax/raw/master/jquery.pjax.js
+```
Then, in your HTML:
- <script src="path/to/js/jquery.pjax.js"></script>
+```html
+<script src="path/to/js/jquery.pjax.js"></script>
+```
Replace `path/to/js` with the path to your JavaScript directory,
e.g. `public/javascripts`.
## minimize it
- curl \
- -d output_info=compiled_code \
- -d compilation_level=SIMPLE_OPTIMIZATIONS \
- -d code_url=https://github.com/defunkt/jquery-pjax/raw/master/jquery.pjax.js \
- http://closure-compiler.appspot.com/compile
+```
+curl \
+ -d output_info=compiled_code \
+ -d compilation_level=SIMPLE_OPTIMIZATIONS \
+ -d code_url=https://github.com/defunkt/jquery-pjax/raw/master/jquery.pjax.js \
+ http://closure-compiler.appspot.com/compile
+```

0 comments on commit a7ad479

Please sign in to comment.