Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/TrevorHinesley/abracadabra
The gem that swaps out text with a fully-compliant Rails form in one click.
https://github.com/TrevorHinesley/abracadabra
Last synced: 3 months ago
JSON representation
The gem that swaps out text with a fully-compliant Rails form in one click.
- Host: GitHub
- URL: https://github.com/TrevorHinesley/abracadabra
- Owner: TrevorHinesley
- License: mit
- Archived: true
- Created: 2014-03-26T13:41:55.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2015-04-26T17:12:37.000Z (almost 10 years ago)
- Last Synced: 2024-09-26T02:14:51.528Z (4 months ago)
- Language: Ruby
- Homepage:
- Size: 440 KB
- Stars: 239
- Watchers: 14
- Forks: 11
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
- awesome-ruby - Abracadabra - The gem that swaps out text with a fully-compliant Rails form in one click. (Form Builder)
README
[](http://badge.fury.io/rb/abracadabra)
# 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](http://vitalets.github.io/x-editable/) plugin and the Rails version of this, [x-editable-rails](https://github.com/werein/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 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
```
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
```
## Helpers
The bread and butter of abracadabra is its helper, `click_to_edit`. It's pretty much as readable as it gets:
```ruby
<%= 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)` - 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
click_to_edit @friend, path: friend_path(@friend), attribute: :name, deletable: true
```
##### *COMPLEX*
```ruby
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_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.
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:
```javascript
abracadabraSubmitIcon = "fa fa-check"; // default
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/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!
1. Fork it ( http://github.com/TrevorHinesley/abracadabra/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request