README.md in x-editable-rails-1.4.0 vs README.md in x-editable-rails-1.5.0
- old
+ new
@@ -16,99 +16,181 @@
$ gem install x-editable-rails
## Usage
-Insert files to your application
+### Assets
+Choose between the following javascripts:
+
+* bootstrap-editable
+* bootstrap2-editable
+* jqueryui-editable
+* jquery-editable-poshytip
+
+You'll also need to include editable/rails in your scripts for this to work.
+
```coffee
#= require editable/bootstrap-editable
+#= require editable/rails
```
-You can choose between bootstrap-editable/bootstrap2-editable/jqueryui-editable/jquery-editable-poshytip
+Choose the corresponding stylesheets:
+
+* bootstrap-editable
+* bootstrap2-editable
+* jqueryui-editable
+* jquery-editable
+
```scss
+// as CSS
*= require editable/bootstrap-editable
+
+// or SCSS
+@import "editable/bootstrap-editable";
```
-You can choose between bootstrap-editable/bootstrap2-editable/jqueryui-editable/jquery-editable
+Enable editing with jQuery:
-You can also insert this file
```coffee
+$('.editable').editable()
+```
+
+For custom inputs like the Wysihtml5 editor, add these dependencies:
+
+```coffee
+#= require editable/bootstrap-editable
+#= require editable/inputs-ext/wysihtml5
+#= require editable/inputs-ext/bootstrap-wysihtml5
+#= require editable/inputs-ext/wysihtml5-editable
#= require editable/rails
```
-This is simple helper using CanCan
+And related stylesheets:
-First you need to create simple helper, which returns true or false (if is editable enabled or not)
+```css
+//= require editable/bootstrap-editable
+//= require editable/inputs-ext/bootstrap-wysihtml5
+//= require editable/inputs-ext/wysiwyg-color
+```
+### Making Things Editable
+
+`x-editable-rails` provides a helper method in your view to make your model values editable.
+By default, you need to specify the model and property that should be editable.
+A `span` element is rendered with `data-*` attributes used by `x-editable`.
+
```ruby
-def xeditable?
- true # Or something like current_user.xeditable?
-end
+# the editable object and the attribute to edit
+%h1= editable @model, :name
```
-and this is how to use helper method
+The helper method automatically adds these `data-*` attributes used by [x-editable](http://vitalets.github.io/x-editable/docs.html).
+* **url** - Uses the `polymorphic_path(model)` helper method.
+* **source** - Only populated if the value is a boolean to convert `true` or `false` to "Yes" and "No".
+* **value** - Uses `model.name`. If `model.name` were a boolean value or if a `source` is specified, the `source` text would be displayed rather than the raw value. (Presumably the value is an ID and the source would have the text associated with that value.)
+* **title** - The model and attribute name are used to create a capitalized title
+* **placeholder** - Uses the `title` value by default
+
```ruby
-%h1= editable @page, :name, e: @page.name
# editable object, what_you_want_update, e: exception - when is xeditable? false or can? :edit, object is false
+%h1= editable @model, :name, url: model_path, value: @model.name.upcase
```
-or with nested attributes (globalize3 example)
+Here are some special features to enhance what's baked into [x-editable](http://vitalets.github.io/x-editable/docs.html):
+
+* **type** - The type of input is automatically detected. By default, if the value is a boolean, the `type` is "select" with a built-in `source` that outputs "Yes" and "No" (unless another `source` is specified).
+* **source** - In addition to hashes or arrays of hashes, you can also use an array of strings for a simpler structure if the name and value are the same:
+
```ruby
-%h1= editable @page, :name, nested: :translations, nid: @page.translation.id, e: @page.name
-# nested: nested attributes, nid: id of nested attribute
+source = [ "Active", "Disabled" ]
+editable @model, :enabled, source: source
```
-Example of nested resource
+* **value** - This option will override the `model.name` value
+* **classes** - This is a custom option for `x-editable-rails` that will change the editable element's CSS class based on the selected value. Use the `source` hash structure to map a CSS class name to a value. (This [functionality](vendor/assets/javascripts/editable/rails/data_classes.js.coffee) is toggled when the value changes and the "save" event is triggered.)
+
```ruby
-%h1= editable [picture.gallery, picture], :name, nested: :translations, nid: picture.translation.id, e: picture.name
+source = [ "Active", "Disabled" ]
+classes = { "Active" => "label-success", "Disabled" => "label-default" }
+editable @model, :enabled, source: source, classes: classes, class: "label"
```
-You can also update everything directly.
-```haml
-%a{href: '#', class: 'editable', data: { type: 'text', model: 'post', name: 'name', url: post_path(post), 'original-title' => 'Your info here'}}= post.name
+* **nested** - Name of a nested attributes (such as [gobalize](https://github.com/globalize/globalize)'s `translations`)
+* **nid** - ID of the nested attribute
+
+```ruby
+%h1= editable @model, :name, nested: :translations, nid: @model.translation.id
+
+# example of nested resource
+%h1= editable [picture.gallery, picture], :name, nested: :translations, nid: picture.translation.id
```
-or if nested
-```haml
-%a{href: '#', class: 'editable', data: { type: 'text', model: 'post', nested: 'translations', name: 'name', nid: "#{post.translation.id}", url: post_path(post), 'original-title' => 'Your info here'}}= post.name
-```
-You need to specify:
-1. data-model
-2. data-name
-3. data-url
+### Authorization
-When updating nested attributes also:
-1. data-nested
-2. data-nid
+Add a helper method to your controllers to indicate if `x-editable` should be enabled.
-And don't forget to activate it
-```coffee
-$('.editable').editable()
+```ruby
+def xeditable?
+ true # Or something like current_user.xeditable?
+end
```
-Wysihtml5 editor
+This gem requires [CanCan](https://github.com/ryanb/cancan) and checks the `:edit` permission for the model being edited.
-If you want edit text with wysihtml5 editor, you need to load his dependencies
-For js
-```coffee
-#= require editable/bootstrap-editable
-#= require editable/inputs-ext/wysihtml5
-#= require editable/inputs-ext/bootstrap-wysihtml5
-#= require editable/inputs-ext/wysihtml5-editable
-#= require editable/rails
+```ruby
+if xeditable? && can?(:edit, model)
+ ... output x-editable HTML ...
+else
+ ... output uneditable value ...
+end
```
-And css
-```sass
-//= require editable/bootstrap-editable
-//= require editable/inputs-ext/bootstrap-wysihtml5
-//= require editable/inputs-ext/wysiwyg-color
+* **e** - Specify a custom (error) message to display if the value isn't editable
+
+### "Don't Repeat Yourself" Templates
+
+To make your views cleaner, you can specify all your options for each class and attribute in a YAML configuration file.
+Attributes where the `title` or `placeholder` are not different except maybe capitalized can be left out because they are automatically capitalized when rendered (see above).
+
+This example uses the `MailingList` class and its attributes.
+The attribute value can be a string, which is used as the `title` and `placeholder`.
+If you want to specify other options, create a hash of options.
+
+Save your YAML file in: `config/x-editable.yml`. Here is an example [example](config/x-editable.yml).
+
+```yaml
+class_options:
+ MailingList:
+ # Specify placeholder text for each attribute or a Hash of options
+ name: Mailing list name
+ enabled:
+ type: select
+ source:
+ - Active
+ - Disabled
+ reply_email:
+ type: email
+ title: Reply-to email
+ User:
+ email:
+ type: email
+ password:
+ type: password
+ mailing_lists:
+ type: select
+ # specify a URL to get source via AJAX (see x-editable docs)
+ source: <%= ::Rails.application.routes.url_helpers.mailing_lists_source_path %>
```
+Now you can specify your editable fields without options because they will be inherited from your YAML config.
+
```ruby
-= editable @page, :content, nested: :translations, nid: @page.translation.id, type: :wysihtml5, e: @page.content.html_safe
+model = MailingList.new
+
+editable model, :name # type: "text", title: "Mailing list name"
+editable model, :enabled # type: "select", title: "Enabled", source: [ "Active", "Disabled" ]
```
## Contributing
1. Fork it