PJAX is javascript project that loads HTML pages from your server straight into the current page without refreshing the entire thing. You can know more about this project, including a very curious demo application, in http://pjax.heroku.com.

I’ve been using it in some of my projects, and I gotta say: it’s just awesome. The website becomes so much more fluid and fast, it’s a beautiful thing.

As almost everything in Ruby, to use it in your very own project, there’s a gem that goes by the name of pjax_rails, with contribution by David Heinemeier Hansson (creator of Ruby on Rails), that does almost everything for you.

1. Include the gem in your Gemfile

gem 'pjax_rails'

After that, don’t forget to execute bundle install to actually install the gem:

bundle install

2. Include the Javascript library on your application

Add the following line to your app’s main javascript file (usually it’s in app/assets/javascripts/application.js):

//= require pjax

3. Setup the dynamic part of the layout

Go to your layout file (usually in app/views/layouts/application.html.erb), and wrap the dynamic area (the layout section that’s going to change) with the following tag:

<div data-pjax-container="">

With that, all the links inside this area will make this request with PJAX. But, maybe, there may be a few links you really don’t want all these PJAX stuff on, right? On to the next part of our tutorial then!

4. Links that shouldn’t use PJAX

To make a link invulnerable to the PJAX sexyness, just add this attribute to it:

'data-skip-pjax' => true

That’s it. Now your app will be using PJAX for most of its requests. For more advanced uses, I suggest a visit to the gem’s page on GitHub: http://github.com/rails/pjax_rails. Our sincere thanks to the truly awesome work of Chris Wanstrath (PJAX’s creator), David Heinemeier Hansson (Rails creator and pjax_rails contributor) and to all other contributors of these projects.