Abracadabra
The gem that swaps out text with a fully-compliant Rails form in one click.
Much of the concepts and html mark-up were taken from the awesome x-editable plugin and the Rails version of this, x-editable-rails. However, this was written from the ground up and uses fully Rails-compliant forms without hacking into x-editable's core files or overriding them.
Installation
Add this line to your application's Gemfile:
gem 'abracadabra'
And then execute:
$ bundle
Or install it yourself as:
$ gem install abracadabra
Usage
- Requires JQuery and JQuery-UJS (rails.js)
- Bootstrap and Font-Awesome are the default, but you can override the CSS and/or customize the icon classes (see Configuration)
In your application.css
, AFTER Bootstrap, include the css file:
*= require abracadabra
In your application.js
, AFTER Jquery (required), include the javascript file:
//= require abracadabra
Helpers
The bread and butter of abracadabra is its helper, click_to_edit
. It's pretty much as readable as it gets:
<%= click_to_edit @user, path: user_path(@user), attribute: :name %>
When a user clicks the link generated by this helper, a form with a text field input will replace the link. It's fully Rails compliant, and the form markup that is generated is identical to a form_for
with remote: true
. Here's what it looks like:
The first parameter of click_to_edit
is the object to be edited, and the only other required parameters are path
and attribute
. path
specifies where the form will be submitted, and attribute
specifies the column being updated.
It accepts the following parameters:
### REQUIRED ###
path: user_path(@user)
# Description: Specifies where the form will be submitted.
attribute: :name
# Description: Specifies what attribute your text field will be updating.
### OPTIONAL ###
class: "my-class"
# Description: Class(es) to be added to the abracadabra link. The class
# "abracadabra" is added # either way.
# Default: only "abracadabra"
id: "my-id"
# Description: ID to be added to the abracadabra link.
# Default: nil (No ID)
value: "blah"
# Description: An alternate value, other than what object.attribute would return.
# Default: object.attribute
method: "patch"
# Description: HTTP REST method to use. Use anything but "get".
# Default: "patch"
buttonless: true
# Description: Removes submit and cancel buttons, submission and cancellation is then
# done through the Enter/Tab and Escape keys, respectively.
# Default: false
remote: true
# Description: Same as link_to's `remote: true`, form submits via AJAX.
# Default: true
type: :js
# IMPORTANT: `type` will be ignored if `remote = false` is used. HTML is the default
# in Rails for standard form submissions.
# Description: Content type -- responds to any content type (:js and :script can both be
# used to respond with Javascript).
# Default: :script (:js)
deletable: true
# OR
deletable: "Are you sure?"
# IMPORTANT: On ajax:success, this will remove the specific abracadabra instance from
# the DOM entirely. ALSO, this will be remote if the main form is remote.
# Boolean: DELETE will be submitted without a confirmation dialog
# String: Confirmation dialog, with the string as the message, will be displayed after
# clicking the DELETE link
# Description: Puts a link to DELETE the object (obviously, it always uses DELETE as
# the HTTP verb).
# Default: false
deletable_path: user_path(@user)
# Description: Specifies where the form will be submitted.
# Default: path (uses the same path as the main form if `deletable_path` isn't declared).
deletable_type: :js
# Description: Deletable content type -- responds to any content type (:js and :script
# can both be used to respond with Javascript).
# Default: :script (:js)
tab_to_next: true
# OR
tab_to_next: ".my-class"
# IMPORTANT: If use a string, and it's a class, this abracadabra instance MUST have the same
# class as well.
# Boolean: Open the next abracadabra instance after successful form submission (main
# form, not the DELETE link's submission) by using `.abracadabra` as the selector.
# String: The class or ID of the next abracadabra instance to open on successful form
# submission. Use `.` before a class selector or `#` before a an ID selector just as you
# would when finding an element in Javascript.
# Description: Puts a link to DELETE the object (obviously, it always uses DELETE as the
# HTTP verb).
# Default: false
submit_on_blur: true
# Description: Submit form when focus leaves the input, rather than simply closing it
# out.
# Default: false
### EXAMPLE ###
# Simple
click_to_edit @friend, path: friend_path(@friend), attribute: :name, deletable: true
# Using a bunch of options
click_to_edit @friend,
path: friend_path(@friend),
attribute: :name,
class: "my-abracadabra",
id: "my-abracadabra-#{index}",
value: @friend.name.titleize,
method: :put,
buttonless: true,
type: :json,
deletable: "Are you sure?",
deletable_path: user_friends_path(@friend),
deletable_type: :json,
tab_to_next: "#my-abracadabra-#{index+1}",
submit_on_blur: true
Configuration
Abracadabra allows some customization. If you would like to change what icon classes are used for the submit
, cancel
, and delete
icons, you can change them globally.
In any Javascript file that loads BEFORE abracadabra's Javascript file that you required above, change any/all of the following variables to suit your project's needs:
abracadabraSubmitIcon = "fa fa-check"; // default
abracadabraCancelIcon = "fa fa-times"; // default
abracadabraDeleteIcon = "fa fa-times-circle-o"; // default
Future & Contributing
I would love anyone to add date pickers and other alternate field types to this.
I would love the different Bootstrap classes to be overridable with an initializer (config/abracadabra.rb), rather than Javascript (not sure if this is even possible), so that any framework could be used. Same with the Font-Awesome button classes.
Any other ideas, feel free to contribute!
- Fork it ( http://github.com/TrevorHinesley/abracadabra/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request