X::Editable::Rails

X-editable for Rails

Installation

Add this line to your application's Gemfile:

gem 'x-editable-rails'

And then execute:

$ bundle

Or install it yourself as:

$ gem install x-editable-rails

Usage

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.

#= require editable/bootstrap-editable
#= require editable/rails

Choose the corresponding stylesheets:

• bootstrap-editable
• bootstrap2-editable
• jqueryui-editable
• jquery-editable

// as CSS
*= require editable/bootstrap-editable

// or SCSS
@import "editable/bootstrap-editable";

Enable editing with jQuery:

$('.editable').editable()

For custom inputs like the Wysihtml5 editor, add these dependencies:

#= require editable/bootstrap-editable
#= require editable/inputs-ext/wysihtml5
#= require editable/inputs-ext/bootstrap-wysihtml5
#= require editable/inputs-ext/wysihtml5-editable
#= require editable/rails

And related stylesheets:

//= 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.

# the editable object and the attribute to edit
%h1= editable @model, :name

You can customize the tag name and title attribute:

• tag - span by default.
• title - The model and attribute name are used to create a capitalized title

The editable helper method automatically adds these data-* attributes used by x-editable.

• 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.)
• placeholder - Uses the title value by default

# 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

Here are some special features to enhance what's baked into x-editable:

• 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:

source = [ "Active", "Disabled" ]
editable @model, :enabled, source: source

• 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 is toggled when the value changes and the "save" event is triggered.)

source  = [ "Active", "Disabled" ]
classes = { "Active" => "label-success", "Disabled" => "label-default" }
editable @model, :enabled, source: source, classes: classes, class: "label"

• nested - Name of a nested attributes (such as gobalize's translations)
• nid - ID of the nested attribute

%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

Authorization

Add a helper method to your controllers to indicate if x-editable should be enabled.

def xeditable?
  true # Or something like current_user.xeditable?
end

This gem requires CanCan and checks the :edit permission for the model being edited.

if xeditable? && can?(:edit, model)
  ... output x-editable HTML ...
else
  ... output uneditable value ...
end

• 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.

Install configuration file like this: rails g x_editable_rails:install, this step is not necessary

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.

model = MailingList.new

editable model, :name    # type: "text",   title: "Mailing list name"
editable model, :enabled # type: "select", title: "Enabled", source: [ "Active", "Disabled" ]

Examples

Gem also contains demo application with integrated x-editable

cd test/dummy
rake db:migrate
rake db:seed
rails g x_editable_rails:install # optional, it generate config example
rails s

Contributing

1. Fork it
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