Turboboost

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+/4+ 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.

Installation

In your Gemfile:

gem "turboboost"

In your application.js:

//= require turboboost

Then in your view files, add turboboost: true to your form helpers:

= form_for :resource, turboboost: true do |f| ...

or add the data attribute manually:

<form data-turboboost> ...

Usage

Redirection with Turbolinks

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.

Error Handling and Flash Messages

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

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

Currently Turboboost will handle invalid ActiveRecord and ActiveModel error messages as well as basic HTTP error messages.

There is also a turboboost:success event that is triggered and passed a hash of all current flash messages if they are present:

$(document).on "turboboost:success", (e, flash) ->
  console.log(flash) # -> {'notice': 'Post was successfully created.'}

Scoped response rendering

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()

The value can be any jQuery selector. Examples usage:

respond_to do |format|
  format.html
  format.js { render partial: 'task', object: @task, prepend: "#todo-list" }
end