x-editable-rails 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3eb8f0f4f7d40565313f05708fe73abaeb438429
-  data.tar.gz: 01a513b8dbc3881ed6e6528638b632d042b0d61a
+  metadata.gz: 658565005fa676f034fc99c545ba7e60158b983b
+  data.tar.gz: 67c484363471f28a725164ffbdbb8476ac9268d2
 SHA512:
-  metadata.gz: 643633fb1a63c4f8f50555596ff9b9b9814804c1598076ce39ac10492927690f0a61922e25cb1201e8f66116fc890b01b6ed25c16eb05ba33adfd8de370a7ab0
-  data.tar.gz: 38f8fefcb625fce171347ca11800450ed5c9c77bc4d3c2da87dc2214ac44601aa38eab3412e492c7c4f6173d59561b0d04be8aafb6b7d785a9568f9fb67b016a
+  metadata.gz: fb098d43de97de7c8a9b71495a79f8d7ace85d76792f0476a55381da194491e25d74bf6ae4236de79948b15ca65aa907616bb3fa00e23b38416947ccb3ca1a73
+  data.tar.gz: f40ec85577f7b1d4cb6ce0d36123918a1b77c4e4f7a56d1394bbb5d17a7356e028bf377da90513cd40e5768425c83d9a47876ae9426b358f443b38352622fa1f

data/README.md

@@ -18,96 +18,178 @@ Or install it yourself as:
 
 ## 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
-```
-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
+* **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
 ```
 
-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

data/lib/x-editable-rails.rb

@@ -1,4 +1,5 @@
 require 'x-editable-rails/version'
+require 'x-editable-rails/configuration'
 require 'x-editable-rails/view_helpers'
 
 module X

data/lib/x-editable-rails/configuration.rb

@@ -0,0 +1,68 @@
+module X
+  module Editable
+    module Rails
+      module Configuration
+        
+        def method_options_for(object, method)
+          class_options_for(object).fetch(method, {})
+        end
+        
+        def class_options_for(object)
+          class_options = options.fetch(:class_options, {})
+          class_options.fetch(object.class.name, {})
+        end
+        
+        def class_options
+          options.fetch(:class_options, {})
+        end
+        
+        def options
+          default_options.deep_merge custom_options
+        end
+        
+        def default_options
+          @defaults ||= begin
+            options = load_yaml_file File.expand_path(File.join(File.dirname(__FILE__), "..", "..", "config", "x-editable.yml"))
+            format_class_options! options
+          end
+        end
+        
+        def custom_options
+          @custom_options ||= begin
+            options = load_yaml_file ::Rails.root.join("config", "x-editable.yml")
+            format_class_options! options
+          end
+        end
+        
+        def load_yaml_file(path)
+          source = File.read path
+          source = ERB.new(source).result
+          
+          result = YAML.load(source)
+          result = {} if result.blank?
+          
+          result.with_indifferent_access
+        end
+        
+        private
+        
+        # if the specified options are a string, convert to Hash and make the string the title
+        def format_class_options!(options)
+          if class_options = options[:class_options]
+            class_options.each do |class_name, methods|
+              methods.each do |method, method_options|
+                unless method_options.is_a? Hash
+                  methods[method] = { title: method_options }.with_indifferent_access
+                end
+              end
+            end
+          end
+          
+          options
+        end
+        
+        extend self
+      end
+    end
+  end
+end

data/lib/x-editable-rails/version.rb

@@ -1,7 +1,7 @@
 module X
   module Editable
     module Rails
-      VERSION = "1.4.0"
+      VERSION = "1.5.0"
     end
   end
 end

data/lib/x-editable-rails/view_helpers.rb

@@ -1,30 +1,142 @@
 module X
   module Editable
     module Rails
-      module ViewHelpers  
-        def editable object, method, options = {}
-          data_url = polymorphic_path(object)
-          object = object.last if object.kind_of?(Array)
-          if can? :edit, object and xeditable?
-            model = object.class.to_s.downcase
-            model_param = model.gsub('::', '_')
-            klass = options[:nested] ? object.class.const_get(options[:nested].to_s.singularize.capitalize) : object.class
-            content_tag :a, href: '#', class: 'editable', title: options.fetch(:title, klass.human_attribute_name(method)),
-            data: { 
-              type: options.fetch(:type, 'text'), 
-              model: model_param, 
-              name: method, 
-              url: data_url, 
-              nested: options[:nested], 
-              nid: options[:nid]
-            } do
-                object.send(method).try(:html_safe)
+      module ViewHelpers
+        #
+        # Options determine how the HTML tag is rendered and the remaining options are converted to data-* attributes.
+        #
+        # options:
+        #   tag:   tag name of element returned
+        #   class: "class" attribute on element
+        #   placeholder: "placeholder" attribute on element
+        #   title: "title" attribute on element (defaults to placeholder)
+        #   data:  "data-*" attributes on element
+        #     source: a Hash of friendly display values used by input elements based on (object) value
+        #       - boolean shorthand ['Enabled', 'Disabled'] becomes { '1' => 'Enabled', '0' => 'Disabled' }
+        #       - enumerable shorthand ['Yes', 'No', 'Maybe'] becomes { 'Yes' => 'Yes', 'No' => 'No', 'Maybe' => 'Maybe' }
+        #     classes: a Hash of classes to add based on the value (same format and shorthands as source)
+        #   value: override the object's value
+        #   
+        def editable(object, method, options = {})
+          options = Configuration.method_options_for(object, method).deep_merge(options).with_indifferent_access
+          # merge data attributes for backwards-compatibility
+          options.merge! options.delete(:data){ Hash.new }
+          
+          url     = options.delete(:url){ polymorphic_path(object) }
+          object  = object.last if object.kind_of?(Array)
+          value   = options.delete(:value){ object.send(method) }
+          source  = options[:source] ? format_source(options.delete(:source), value) : default_source_for(value)
+          classes = format_source(options.delete(:classes), value)
+          error   = options.delete(:e)
+          
+          if xeditable? and can?(:edit, object)
+            model   = object.class.name.split('::').last.underscore
+            nid     = options.delete(:nid)
+            nested  = options.delete(:nested)
+            title   = options.delete(:title) do
+              klass = nested ? object.class.const_get(nested.to_s.singularize.capitalize) : object.class
+              klass.human_attribute_name(method)
             end
+            
+            output_value = output_value_for(value)
+            css_list = options.delete(:class).to_s.split(/s+/).unshift('editable')
+            css_list << classes[output_value] if classes
+            
+            css   = css_list.compact.uniq.join(' ')
+            tag   = options.delete(:tag){ 'span' }
+            placeholder = options.delete(:placeholder){ title }
+            
+            # any remaining options become data attributes
+            data  = {
+              type:   options.delete(:type){ default_type_for(value) }, 
+              model:  model, 
+              name:   method, 
+              value:  output_value, 
+              placeholder: placeholder, 
+              classes: classes, 
+              source: source, 
+              url:    url, 
+              nested: nested, 
+              nid:    nid
+            }.merge(options)
+            
+            data.reject!{|_, value| value.nil?}
+            
+            content_tag tag, class: css, title: title, data: data do
+              source_values_for(value, source).join('<br/>').html_safe
+            end
+          else
+            # create a friendly value using the source to display a default value (if no error message given)
+            error || source_values_for(value, source).join('<br/>').html_safe
+          end
+        end
+        
+        private
+        
+        def output_value_for(value)
+          value = case value
+          when TrueClass
+            '1'
+          when FalseClass
+            '0'
+          when NilClass
+            ''
+          when Array
+            value.map{|item| output_value_for item}.join(',')
+          else
+            value.to_s
+          end
+          
+          value.html_safe
+        end
+        
+        def source_values_for(value, source = nil)
+          source ||= default_source_for value
+          
+          values = Array.wrap(value)
+          
+          if source
+            values.map{|item| source[output_value_for item]}
           else
-            options[:e]
+            values
           end
         end
+        
+        def default_type_for(value)
+          case value
+          when TrueClass, FalseClass
+            'select'
+          when Array
+            'checklist'
+          else
+            'text'
+          end
+        end
+        
+        def default_source_for(value)
+          case value
+          when TrueClass, FalseClass
+            { '1' => 'Yes', '0' => 'No' }
+          end
+        end
+        
+        # helper method that take some shorthand source definitions and reformats them
+        def format_source(source, value)
+          formatted_source = case value
+            when TrueClass, FalseClass
+              if source.is_a?(Array) && source.first.is_a?(String) && source.size == 2
+                { '1' => source[0], '0' => source[1] }
+              end
+            when String
+              if source.is_a?(Array) && source.first.is_a?(String)
+                source.inject({}){|hash, key| hash.merge(key => key)}
+              end
+            end
+          
+          formatted_source || source
+        end
+        
       end
     end
   end
-end
+end

data/vendor/assets/javascripts/editable/rails.js.coffee

@@ -1,37 +1,2 @@
-jQuery ($) ->
-  EditableForm = $.fn.editableform.Constructor
-  EditableForm.prototype.saveWithUrlHook = (value) ->
-    originalUrl = @options.url
-    model = @options.model
-    nestedName = @options.nested
-    nestedId =  @options.nid
-    nestedLocale = @options.locale
-    @options.url = (params) =>
-      if typeof originalUrl == 'function'
-        originalUrl.call(@options.scope, params)
-      else if originalUrl? && @options.send != 'never'
-        myName = params.name
-        myValue = params.value.replace(/(\r\n|\n|\r)/gm,"<br/>")
-        obj = {}
-        if nestedName
-          nested = {}
-          nested[myName] = myValue
-          nested['id'] = nestedId
-          if nestedLocale
-            nested['locale'] = nestedLocale
-          obj[nestedName + '_attributes'] = nested
-        else
-          obj[myName] = myValue
-        params[model] = obj
-        delete params.name
-        delete params.value
-        delete params.pk
-        $.ajax($.extend({
-          url     : originalUrl
-          data    : params
-          type    : 'PUT'
-          dataType: 'json'
-        }, @options.ajaxOptions))
-    @saveWithoutUrlHook(value)
-  EditableForm.prototype.saveWithoutUrlHook = EditableForm.prototype.save
-  EditableForm.prototype.save = EditableForm.prototype.saveWithUrlHook
+#= require ./rails/editable_form
+#= require ./rails/data_classes

data/vendor/assets/javascripts/editable/rails/data_classes.js.coffee

@@ -0,0 +1,23 @@
+
+# make things editable that can be edited
+
+# $('.editable').editable(
+  # success: (response, value) ->
+    # element = $(this)
+    # css = element.data('classes') || {}
+    # element.removeClass(class_name) for key, class_name of css
+    # element.addClass(css[value])
+    # element.css('background-color', '')
+# )
+
+# swap CSS classes when the value changes
+
+jQuery ($) ->
+  $("[data-classes]").on "save", (e, data) ->
+    value = data.newValue
+    element = $(this)
+    css = element.data('classes') || {}
+    element.removeClass(class_name) for key, class_name of css
+    element.addClass(css[value])
+    element.css('background-color', '')
+    

data/vendor/assets/javascripts/editable/rails/editable_form.js.coffee

@@ -0,0 +1,40 @@
+jQuery ($) ->
+  EditableForm = $.fn.editableform.Constructor
+  EditableForm.prototype.saveWithUrlHook = (value) ->
+    originalUrl = @options.url
+    model = @options.model
+    nestedName = @options.nested
+    nestedId =  @options.nid
+    nestedLocale = @options.locale
+    @options.url = (params) =>
+      if typeof originalUrl == 'function'
+        originalUrl.call(@options.scope, params)
+      else if originalUrl? && @options.send != 'never'
+        myName = params.name
+        if typeof params.value == 'string'
+          myValue = params.value.replace(/(\r\n|\n|\r)/gm,"<br/>")
+        else
+          myValue = params.value
+        obj = {}
+        if nestedName
+          nested = {}
+          nested[myName] = myValue
+          nested['id'] = nestedId
+          if nestedLocale
+            nested['locale'] = nestedLocale
+          obj[nestedName + '_attributes'] = nested
+        else
+          obj[myName] = myValue
+        params[model] = obj
+        delete params.name
+        delete params.value
+        delete params.pk
+        $.ajax($.extend({
+          url     : originalUrl
+          data    : params
+          type    : 'PUT'
+          dataType: 'json'
+        }, @options.ajaxOptions))
+    @saveWithoutUrlHook(value)
+  EditableForm.prototype.saveWithoutUrlHook = EditableForm.prototype.save
+  EditableForm.prototype.save = EditableForm.prototype.saveWithUrlHook

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: x-editable-rails
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Jiri Kolarik
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-02 00:00:00.000000000 Z
+date: 2013-11-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,20 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: cancan
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: X-editable for Rails
 email:
 - jiri.kolarik@imin.cz
@@ -59,6 +73,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/x-editable-rails/configuration.rb
 - lib/x-editable-rails/version.rb
 - lib/x-editable-rails/view_helpers.rb
 - lib/x-editable-rails.rb
@@ -74,6 +89,8 @@ files:
 - vendor/assets/javascripts/editable/inputs-ext/wysihtml5.js
 - vendor/assets/javascripts/editable/jquery-editable-poshytip.js
 - vendor/assets/javascripts/editable/jqueryui-editable.js
+- vendor/assets/javascripts/editable/rails/data_classes.js.coffee
+- vendor/assets/javascripts/editable/rails/editable_form.js.coffee
 - vendor/assets/javascripts/editable/rails.js.coffee
 - vendor/assets/stylesheets/editable/bootstrap-editable.scss
 - vendor/assets/stylesheets/editable/bootstrap2-editable.scss
@@ -110,3 +127,4 @@ signing_key:
 specification_version: 4
 summary: X-editable for Rails
 test_files: []
+has_rdoc: