Turboboost extends the power of Turbolinks into the forms of your Rails app and provides additional convenient AJAX handlers for forms and links. It aims to be a seemless and logical addition to any Turbolinks-rocking Rails 3.2+ app. Currently it depends on jQuery. The main features are:
- Form response redirection is handled by Turbolinks.
- Customizable success and error handling through registered JavaScript, with support for Rails' Flash and optional error rendering built-in.
- Responses can also be rendered within a scoped DOM target using jQuery selectors.
In recent history Turbolinks has started to emulate some of these features with a slightly different approach. I will continue to support this library if people are still finding it useful.
gem 'turboboost'
Or to live on the very edge:
gem 'turboboost', github: 'waymondo/turboboost'
Then bundle install
.
//= require turboboost
This will also require jQuery, jquery-ujs, Turbolinks, if not already required. If you wish to register your scripts manually, you can like so:
//= require path/to/vendored/jquery
//= require jquery_ujs
//= require turbolinks
//= require turboboost/turboboost
Add turboboost: true
to your form / link helpers:
<%= form_for :resource, turboboost: true do |f| ... %>
<%= link_to "Turboboosted Link", resource_path, turboboost: true %>
Or you can add the data attribute manually:
<form data-remote data-turboboost action="/foo"></form>
<a data-remote data-turboboost href="/bar"></a>
In its simplest server-side implementation, a basic Turboboost controller action with redirection might look like this:
def create
post = Post.create!(params[:post]) # <- trigger exception if model is invalid
redirect_to post, notice: 'Post was successfully created.'
end
If the post is successfully created through a Turboboost-ed form, the app will visit the post's URL with Turbolinks. Otherwise, the redirect will happen like normal. You can opt out of redirecting through Turboboost with the attribute flag data-no-turboboost-redirect
.
If a Turboboost form makes a GET request, it will serialize the form's data and then visit its action URL with the data serialized as parameters with Turbolinks. This allows Turbolinks-powered cached push/popState history navigation of controller actions with different parameter values (like a search form).
To prevent double-clicks on submit buttons from firing the form's action twice, Turboboost comes with automatic form disabling/enabling by default. When you restore a page from Turbolinks' cache, it will re-enable any submit buttons that it had disabled. You can disable this behavior and control your form's submittable state manually with:
Turboboost.handleFormDisabling = false
If the post in our example above is invalid, no redirect will happen and a rescue_from
handler will pass the errors to JavaScript through the turboboost:error
event:
$(document).on "turboboost:error", (e, errors) ->
console.log(errors) # <- JSON array of errors messages
You can also trigger the JSON error messages explicitly with the method render_turboboost_errors_for(record)
if you don't want to use the default rescue_from
handler:
def create
@post = Post.new(post_params)
if @post.save
flash[:notice] = 'Post was successfully created.'
redirect_to @post
else
respond_to do |format|
format.html { render :new }
format.js { render_turboboost_errors_for(@post) }
end
end
end
To note: If you are rendering a response from a Turboboost-ed form or link, you will need to specify its rendering scope.
Check out the test controllers for more examples of controller syntax.
Optionally, Turboboost can render returned errors with the same HTML structure used in the default Rails generators and prepend it to the form. The HTML structure looks like this:
<div id="error_explanation">
<ul>
{{#errors}}
<li>{{this}}</li>
{{/errors}}
</ul>
</div>
To turn it on:
Turboboost.insertErrors = true # same as 'prepend'
# other possible values:
# Turboboost.insertErrors = 'append'
# Turboboost.insertErrors = 'beforeSubmit'
# Turboboost.insertErrors = 'afterSubmit'
# can also be a jQuery selector:
# Turboboost.insertErrors = '.error-wrap'
Turboboost will handle invalid ActiveRecord
and ActiveModel
error messages as well as basic HTTP error messages. For ActiveRecord validations, it will use Rails' I18n lookup to retrieve the message wording. For other raised exceptions, you can customize the basic wording using the I18n namespace format turboboost.errors.#{error.class.name}
:
en:
turboboost:
errors:
"ActiveRecord::RecordNotFound": "Shoot, didn't find anything."
There is also a turboboost:success
event that is triggered and passed all current flash messages if they are present:
$(document).on "turboboost:success", (e, flash) ->
console.log(flash) # -> {'notice': 'Post was successfully created.'}
Turboboost also provides some options for rendering AJAX responses at specific locations in the DOM:
Rails controller render option | jQuery function |
---|---|
:within |
html() |
:replace |
replaceWith() |
:prepend |
prepend() |
:append |
append() |
:before |
before() |
:after |
after() |
The value can be any jQuery selector. Example usage:
respond_to do |format|
format.html
format.js { render partial: 'task', object: @task, prepend: "#todo-list" }
end