Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/waymondo/turboboost
Enhanced AJAX handling for Rails apps
https://github.com/waymondo/turboboost
Last synced: 4 days ago
JSON representation
Enhanced AJAX handling for Rails apps
- Host: GitHub
- URL: https://github.com/waymondo/turboboost
- Owner: waymondo
- Created: 2013-12-04T00:15:42.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2023-08-23T21:40:04.000Z (over 1 year ago)
- Last Synced: 2025-01-03T12:36:36.876Z (6 days ago)
- Language: Ruby
- Homepage:
- Size: 114 KB
- Stars: 167
- Watchers: 6
- Forks: 17
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
## 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+ 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.##### Disclaimer #####
In recent history [Turbolinks](https://github.com/rails/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.
### Installation ###
##### In your `Gemfile` #####
``` ruby
gem 'turboboost'
```Or to live on the very edge:
``` ruby
gem 'turboboost', github: 'waymondo/turboboost'
```Then `bundle install`.
##### In your `application.js` #####
``` javascript
//= require turboboost
```This will also require jQuery, [jquery-ujs](https://github.com/rails/jquery-ujs), Turbolinks, if not already required. If you wish to register your scripts manually, you can like so:
``` javascript
//= require path/to/vendored/jquery
//= require jquery_ujs
//= require turbolinks
//= require turboboost/turboboost
```##### In your view files #####
Add `turboboost: true` to your form / link helpers:
``` erb
<%= form_for :resource, turboboost: true do |f| ... %><%= link_to "Turboboosted Link", resource_path, turboboost: true %>
```Or you can add the data attribute manually:
```
### Redirection with Turbolinks ###
In its simplest server-side implementation, a basic Turboboost controller action with redirection might look like this:
``` ruby
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`.
### Form GET requests ###
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).
### Automatic form disabling handling ###
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:
``` coffee
Turboboost.handleFormDisabling = false
```### Error handling ###
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:
``` coffee
$(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:
``` ruby
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](https://github.com/waymondo/turboboost#scoped-response-rendering).
Check out the [test controllers](https://github.com/waymondo/turboboost/tree/master/test/controllers) for more examples of controller syntax.
#### Automatic error message insertion ####
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:
``` html
{{#errors}}
- {{this}}
{{/errors}}
```To turn it on:
``` coffeescript
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'
```#### Error internationalization ####
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](http://guides.rubyonrails.org/i18n.html#translations-for-active-record-models) 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}`:
``` yaml
en:
turboboost:
errors:
"ActiveRecord::RecordNotFound": "Shoot, didn't find anything."
```### Ajax flash message handling ###
There is also a `turboboost:success` event that is triggered and passed all current flash messages if they are present:
``` coffeescript
$(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()` |
|`:before` |`before()` |
|`:after` |`after()` |The value can be any jQuery selector. Example usage:
``` ruby
respond_to do |format|
format.html
format.js { render partial: 'task', object: @task, prepend: "#todo-list" }
end
```