[Summary view] [Print] [Text view]

   1  ## pushState + ajax = pjax
   2  
   3              .--.
   4             /    \
   5            ## a  a
   6            (   '._)
   7             |'-- |
   8           _.\___/_   ___pjax___
   9         ."\> \Y/|<'.  '._.-'
  10        /  \ \_\/ /  '-' /
  11        | --'\_/|/ |   _/
  12        |___.-' |  |`'`
  13          |     |  |
  14          |    / './
  15         /__./` | |
  16            \   | |
  17             \  | |
  18             ;  | |
  19             /  | |
  20       jgs  |___\_.\_
  21            `-"--'---'
  22  
  23  
  24  ## what is it?
  25  
  26  pjax loads HTML from your server into the current page
  27  without a full reload. It's ajax with real permalinks,
  28  page titles, and a working back button that fully degrades.
  29  
  30  pjax enhances the browsing experience - nothing more.
  31  
  32  You can find a demo on <http://pjax.heroku.com/>
  33  
  34  
  35  ## three ways to pjax on the client side:
  36  
  37  One. Functionally obtrusive, loading the href with ajax into data-pjax:
  38  
  39  ```html
  40  <a href='/explore' data-pjax='#main'>Explore</a>
  41  ```
  42  
  43  ```js
  44  $('a[data-pjax]').pjax()
  45  ```
  46  
  47  
  48  Two. Slightly obtrusive, passing a container and binding an error handler:
  49  
  50  ```html
  51  <a href='/explore' class='js-pjax'>Explore</a>
  52  ```
  53  
  54  ```js
  55  $('.js-pjax').pjax('#main')
  56  
  57  $('#main').live('pjax:error', function(e, xhr, err) {
  58    $('.error').text('Something went wrong: ' + err)
  59  })
  60  ```
  61  
  62  
  63  Three. Unobtrusive, showing a 'loading' spinner:
  64  
  65  ```html
  66  <div id='main'>
  67    <div class='loader' style='display:none'><img src='spin.gif'></div>
  68    <div class='tabs'>
  69      <a href='/explore'>Explore</a>
  70      <a href='/help'>Help</a>
  71    </div>
  72  </div>
  73  ```
  74  
  75  ```js
  76  $('a').pjax('#main').live('click', function(){
  77    $(this).showLoader()
  78  })
  79  ```
  80  
  81  
  82  ## $(link).pjax( container, options )
  83  
  84  The `$(link).pjax()` function accepts a container, an options object,
  85  or both. The container MUST be a string selector - this is because we
  86  cannot persist jQuery objects using the History API between page loads.
  87  
  88  The options are the same as jQuery's `$.ajax` options with the
  89  following additions:
  90  
  91  * `container`      - The String selector of the container to load the
  92                       reponse body. Must be a String.
  93  * `target`         - The Element that was clicked to start the pjax call.
  94  * `push`           - Whether to pushState the URL. Default: true (of course)
  95  * `replace`        - Whether to replaceState the URL. Default: false
  96  * `timeout`        - pjax sets this low, <1s. Set this higher if using a
  97                       custom error handler. It's ms, so something like
  98                       `timeout: 2000`
  99  * `fragment`       - A String selector that specifies a sub-element to
 100                       be pulled out of the response HTML and inserted
 101                       into the `container`. Useful if the server always returns
 102                       full HTML pages.
 103  
 104  
 105  ## $.pjax( options )
 106  
 107  You can also just call `$.pjax` directly. It acts much like `$.ajax`, even
 108  returning the same thing and accepting the same options.
 109  
 110  The pjax-specific keys listed in the `$(link).pjax()` section work here
 111  as well.
 112  
 113  This pjax call:
 114  
 115  ```js
 116  $.pjax({
 117    url: '/authors',
 118    container: '#main'
 119  })
 120  ```
 121  
 122  Roughly translates into this ajax call:
 123  
 124  ```js
 125  $.ajax({
 126    url: '/authors',
 127    dataType: 'html',
 128    beforeSend: function(xhr){
 129      xhr.setRequestHeader('X-PJAX', 'true')
 130    },
 131    success: function(data){
 132      $('#main').html(data)
 133      history.pushState(null, $(data).filter('title').text(), '/authors')
 134    })
 135  })
 136  ```
 137  
 138  
 139  ## pjax on the server side
 140  
 141  You'll want to give pjax requests a 'chrome-less' version of your page.
 142  That is, the page without any layout.
 143  
 144  As you can see in the "ajax call" example above, pjax sets a custom 'X-PJAX'
 145  header to 'true' when it makes an ajax request to make detecting it easy.
 146  
 147  In Rails, check for `request.headers['X-PJAX']`:
 148  
 149  ```ruby
 150  def my_page
 151    if request.headers['X-PJAX']
 152      render :layout => false
 153    end
 154  end
 155  ```
 156  
 157  Or as a before filter in application controller:
 158  
 159  ```ruby
 160  layout :set_layout
 161  
 162  private
 163    def set_layout
 164      if request.headers['X-PJAX']
 165        false
 166      else
 167        "application"
 168      end
 169    end
 170  ```
 171  
 172  Rails: <https://github.com/rails/pjax_rails>
 173  
 174  Django: <https://github.com/jacobian/django-pjax>
 175  
 176  Asp.Net MVC3: <http://biasecurities.com/blog/2011/using-pjax-with-asp-net-mvc3/>
 177  
 178  
 179  ## page titles
 180  
 181  Your HTML should also include a `<title>` tag if you want page titles to work.
 182  
 183  When using a page fragment, pjax will check the fragment DOM element
 184  for a `title` or `data-title` attribute and use any value it finds.
 185  
 186  
 187  ## events
 188  
 189  pjax will fire two events on the container you've asked it to load your
 190  reponse body into:
 191  
 192  * `pjax:start` - Fired when a pjax ajax request begins.
 193  * `pjax:end`   - Fired when a pjax ajax request ends.
 194  
 195  This allows you to, say, display a loading indicator upon pjaxing:
 196  
 197  ```js
 198  $('a.pjax').pjax('#main')
 199  $('#main')
 200    .on('pjax:start', function() { $('#loading').show() })
 201    .on('pjax:end',   function() { $('#loading').hide() })
 202  ```
 203  
 204  Because these events bubble, you can also set them on the document:
 205  
 206  ```js
 207  $('a.pjax').pjax()
 208  $(document)
 209    .on('pjax:start', function() { $('#loading').show() })
 210    .on('pjax:end',   function() { $('#loading').hide() })
 211  ```
 212  
 213  In addition, custom events are added to complement `$.ajax`'s
 214  callbacks.
 215  
 216  * `pjax:beforeSend` - Fired before the pjax request begins. Returning
 217                        false will abort the request.
 218  * `pjax:complete`   - Fired after the pjax request finishes.
 219  * `pjax:success`    - Fired after the pjax request succeeds.
 220  * `pjax:error`      - Fired after the pjax request fails. Returning
 221                        false will prevent the the fallback redirect.
 222  * `pjax:timeout`    - Fired if after timeout is reached. Returning
 223                        false will disable the fallback and will wait
 224                        indefinitely until the response returns.
 225  
 226  **CAUTION** Callback handlers passed to `$.pjax` **cannot** be persisted
 227  across full page reloads. Its recommended you use custom events instead.
 228  
 229  ## browser support
 230  
 231  pjax only works with browsers that support the history.pushState API.
 232  
 233  For a table of supported browsers see: <http://caniuse.com/#search=pushstate>
 234  
 235  To check if pjax is supported, use the `$.support.pjax` boolean.
 236  
 237  When pjax is not supported, `$('a').pjax()` calls will do nothing (aka links
 238  work normally) and `$.pjax({url:url})` calls will redirect to the given URL.
 239  
 240  
 241  ## install it
 242  
 243  ```
 244  $ cd path/to/js
 245  $ wget https://raw.github.com/defunkt/jquery-pjax/master/jquery.pjax.js
 246  ```
 247  
 248  Then, in your HTML:
 249  
 250  ```html
 251  <script src="path/to/js/jquery.pjax.js"></script>
 252  ```
 253  
 254  Replace `path/to/js` with the path to your JavaScript directory,
 255  e.g. `public/javascripts`.
 256  
 257  
 258  ## minimize it
 259  
 260  ```
 261  curl \
 262    -d output_info=compiled_code \
 263    -d compilation_level=SIMPLE_OPTIMIZATIONS \
 264    -d code_url=https://github.com/defunkt/jquery-pjax/raw/master/jquery.pjax.js \
 265    http://closure-compiler.appspot.com/compile
 266  ```