README.md

@@ -1,3 +1,5 @@
+[![Gem Version](https://badge.fury.io/rb/abracadabra.svg)](http://badge.fury.io/rb/abracadabra)
+
 # Abracadabra
 
 The gem that swaps out text with a fully-compliant Rails form in one click.
@@ -20,16 +22,22 @@ Or install it yourself as:
 
 ## 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](#configuration)) 
+* Requires jQuery and jQuery-UJS (rails.js).
+* Bootstrap and Font-Awesome are the default, but are not required. You can override the CSS and/or customize the icon classes (see [Configuration](#configuration)).
 
 In your `application.css`, AFTER Bootstrap, include the css file:
 
 ```css
  *= require abracadabra
 ```
 
-In your `application.js`, AFTER Jquery (required), include the javascript file:
+OR if you're using SASS/SCSS:
+
+```sass
+ @import "abracadabra-scss";
+```
+
+In your `application.js`, AFTER jQuery and jQuery-UJS (required), include the javascript file:
 
 ```js
  //= require abracadabra
@@ -45,100 +53,50 @@ The bread and butter of abracadabra is its helper, `click_to_edit`. It's pretty
 
 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:
 
-![Abracadabra Demo](http://recordit.co/CbgPTahYix.gif "Abracadabra Demo")
+![Abracadabra Demo](http://s7.postimg.org/jbfymynij/abracadabra.gif "Abracadabra Demo")
 
 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)` - Specifies where the form will be submitted.
+
+- `attribute: :name` - Specifies what attribute your text field will be updating.
+
+#### OPTIONAL
+- `class: "my-class"` - Class(es) to be added to the abracadabra link. The class "abracadabra" is added either way. [*Default:* `"abracadabra"`]
+
+- `id: "my-id"` - ID to be added to the abracadabra link. [*Default:* `nil`]
+
+- `value: "blah"` - An alternate value, other than what object.attribute would return. [*Default:* `object.attribute`]
+
+- `method: "patch"` - HTTP REST method to use. Use anything but "get". [*Default:* `"patch"`]
+
+- `buttonless: true` - Removes submit and cancel buttons. Submission and cancellation is then done through the Enter/Tab and Escape keys, respectively. [*Default:* `false`]
+
+- `remote: true` - Same as `link_to`'s `remote: true`, form submits via AJAX. [*Default:* `true`]
+
+- `type: :js` - Content type -- responds to any content type (`:js` and `:script` are interchangeable). [*Default:* `:script`] ***IMPORTANT: `type` will be ignored if `remote = false` is used. HTML is the default in Rails for standard form submissions.***
+
+- `deletable: true` OR `deletable: "Are you sure?"` - Puts a link to DELETE the object (obviously, it always uses DELETE as the HTTP verb). If a boolean is used, it is submitted upon clicking. If a string is used, a confirmation dialog will prompt them using the string before submitting. [*Default:* `false`] ***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.***
+
+- `deletable_path: user_path(@user)` - Specifies where the form will be submitted. [*Default:* `path` (uses the same path as the main form)]
+
+- `deletable_type: :js` - Deletable content type -- responds to any content type (:js and :script can both be used to respond with Javascript). [*Default:* `:script`]
+
+- `tab_to_next: true` OR `tab_to_next: ".my-class"` - Opens the next abracadabra instance after successful form submission (main form, not the DELETE link's submission). If a boolean is used, `.abracadabra` is the selector used to find the next instance to open. If a string is used, that will be the selector, so be sure to use standard jQuery selector syntax (i.e. `.class` and `#id`). [*Default:* `false`] ***IMPORTANT: If you use a string, and it's a class, this abracadabra instance MUST have the same class as well.***
+
+- `submit_on_blur: true` - Submit form when focus leaves the input, rather than simply closing it out. [*Default:* `false`]
+
+#### EXAMPLES
+##### *SIMPLE*
 ```ruby
-### 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
+##### *COMPLEX*
+```ruby
 click_to_edit @friend, 
     path: friend_path(@friend),
     attribute: :name,
@@ -149,12 +107,22 @@ click_to_edit @friend,
     buttonless: true,
     type: :json,
     deletable: "Are you sure?",
-    deletable_path: user_friends_path(@friend),
+    deletable_path: user_friend_path(@friend),
     deletable_type: :json,
     tab_to_next: "#my-abracadabra-#{index+1}",
     submit_on_blur: true
 ```
 
+#### REBINDING
+
+If you add `abracadabra` elements to the page dynamically, you will need to rebind.
+
+Simply call abracadabra's jQuery function:
+
+```javascript
+$.abracadabra();
+```
+
 ## 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. 
@@ -169,11 +137,33 @@ abracadabraCancelIcon = "fa fa-times"; // default
 abracadabraDeleteIcon = "fa fa-times-circle-o"; // default
 ```
 
+## Integration Testing
+
+The most reliable way I've found to test abracadabra is by using the following helper (works with Rspec+Capybara using Capybara Webkit, Selenium Webdriver, or Poltergeist/PhantomJS):
+
+```ruby
+def execute_abracadabra value, selector = ".abracadabra"
+  page.execute_script("$(\"#{selector}\").click();")
+  page.execute_script("$(\".abracadabra-input\").val(\"#{value}\");")
+  page.execute_script("$(\".abracadabra-submit\").click();")
+end
+```
+
+You can place that in a helper file, include it in your integration spec, and call it like so:
+
+```ruby
+execute_abracadabra "new value", "#editable-name"
+```
+
+This will click the abracadabra instance that has an ID of `#editable-name`, input `new value`, and submit it. Obviously, you can use any valid jQuery selector, not just IDs.
+
+If no selector is passed, `.abracadabra` is used. It's highly recommended to pass a specific selector, because as soon as more than one abracadabra instance makes its way on to your page, the default selector (not suprisingly) won't play well.
+
 ## Future & Contributing
 
 1. I would love anyone to add date pickers and other alternate field types to this.
 
-2. 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.
+2. I would love the different Bootstrap classes to be overridable with an initializer (config/initializers/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!