README.md

⚠️ Deprecated ⚠️

This gem does not work with Turbolinks 5+, and is not compatible with many jQuery plugins. We do not recommend using it. Instead, please consider writing your JavaScript in a way that makes it compatible with Turbolinks. These resources can help:

• RSJS - A reasonable structure for JS, a document outlining how to write JavaScript as "behaviors" that will be compatible with Turbolinks.

• onmount - 1kb library to run something when a DOM element appears and when it exits.

Rationale: making jQuery plugins compatible with Turbolinks requires more than simply dropping in a library. It should be able to setup and teardown its changes as needed, which is something you can't automate. jQuery Turbolinks's approach worked well enough for many libraries back in 2013, but today this is no longer the case. Given its utility is very limited, we've decided to no longer maintain this library.

---

jQuery Turbolinks

Do you like Turbolinks? It's easy and fast way to improve user experience of surfing on your website.

But if you have a large codebase with lots of $(el).bind(...) Turbolinks will surprise you. Most part of your JavaScripts will stop working in usual way. It's because the nodes on which you bind events no longer exist.

I wrote jquery.turbolinks to solve this problem in my project. It's easy to use: just require it immediately after jquery.js. Your other scripts should be loaded after jquery.turbolinks.js, and turbolinks.js should be after your other scripts.

Initially sponsored by Evil Martians.

This project is a member of the OSS Manifesto.

Important

This readme points to the latest version (v2.x) of jQuery Turbolinks, which features new 2.0 API. For older versions, see v1.0.0rc2 README.

Usage

Gemfile:

gem 'jquery-turbolinks'

Add it to your JavaScript manifest file, in this order:

//= require jquery
//= require jquery.turbolinks
//= require jquery_ujs
//
// ... your other scripts here ...
//
//= require turbolinks

And it just works!

Checkout "Faster page loads with Turbolinks" for deeper explanation how to use jQuery Turbolink in real world.

API and Customization

$.turbo.use

By default, jQuery.Turbolinks is bound to page:load and page:fetch. To use different events (say, if you're not using Turbolinks), use:

$.turbo.use('pjax:start', 'pjax:end');

$.turbo.isReady

You can check if the page is ready by checking $.turbo.isReady, which will be either true or false depending on whether the page is loading.

Troubleshooting

Events firing twice or more

If you find that some events are being fired multiple times after using jQuery Turbolinks, you may have been binding your document events inside a $(function()) block. For instance, this example below can be a common occurrence and should be avoided:

/* BAD: don't bind 'document' events while inside $()! */
$(function() {
  $(document).on('click', 'button', function() { ... })
});

You should be binding your events outside a $(function()) block. This will ensure that your events will only ever be bound once.

/* Good: events are bound outside a $() wrapper. */
$(document).on('click', 'button', function() { ... })

Not working with $(document).on('ready')

jQuery Turbolinks doesn't support ready events bound via $(document).on('ready', function). Instead, use $(document).ready(function) or $(function).

// BAD: this will not work.
$(document).on('ready', function () { /* ... */ });

// OK: these two are guaranteed to work.
$(document).ready(function () { /* ... */ });
$(function () { /* ... */ });

Changelog

This project uses Semantic Versioning for release numbering.

For changelog notes, checkout releases page.

Contributors

Initial idea and code by @kossnocorp, with special thanks to @rstacruz and other the project's contributors.

License

The MIT License