knockout_forms-rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4d733f242bb995739e41da161277091e2f707972
+  data.tar.gz: 9f1e588416553454d9d17e8224098982e5d8fa03
+SHA512:
+  metadata.gz: 88754d82d026c355c610ef71bc6e13436fcf1770b8f7dd88820cf4bccdf7c8e7f2527a7f5c69093cf8f91214ba0d3aa695f3a28c05811b8d89239e2713146fac
+  data.tar.gz: df37feb8697a0bf138db112e177a8ad32ca3b82eddf91f807479e1bcaf131390ef20a99115694c57f6283aa5f85557424fa3e64ef5316157162cd2794c3c29f0

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in knockout_forms-rails.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Santiago Palladino
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,203 @@
+# KnockoutForms::Rails
+
+Knockoutjs powered form builder for Rails. This gem provides a `knockout_form_for` helper that creates forms automatically bound to a viewmodel created for your model via the mapping plugin.
+
+## Why?
+
+There was a large gap between how Rails standard forms and knockoutjs based forms are written: where the former make use of handy form builders, the latter require the markdown the be manually set up and wired with `data-bind` attributes, even if the viewmodel is rather simple.
+
+This gem intends to bridge this gap by allowing a Rails form to be easily converted in a knockoutjs aware one, by allowing you to keep using form builders while automatically handling data binding under the covers.
+
+That being said, the gem provides several endpoints for customisation, making it easy to insert your custom logic whenever needed.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'knockout_forms-rails'
+```
+
+And add the following directive to your Javascript manifest file (application.js):
+
+```javascript
+//= require knockout-forms.rails
+```
+
+## Dependencies
+
+This gem requires both knockoutjs and the knockoutjs mapping plugin. The easiest way to do this is via the [knockoutjs-rails gem](https://github.com/jswanner/knockoutjs-rails); though it is not listed as a dependency in case you want to manage your javascript libraries somehow else.
+
+## Example application
+
+There is an [example application](https://github.com/spalladino/knockout_forms-rails-example) available with a simple [User form](https://github.com/spalladino/knockout_forms-rails-example/blob/master/app/views/users/_form.html.erb) and a complex [Questionnaire form](https://github.com/spalladino/knockout_forms-rails-example/blob/master/app/views/questionnaires/_form.html.erb) with a N-to-1 relation to Questions.
+
+## Usage
+
+This gem provides a `KnockoutForms::Rails::FormBuilder` class, accessible via the `knockout_form_for` method, which must be bound invoking the javascript `ko.form(f)` method with a reference to it.
+
+### Basic usage
+
+The easiest example is to use the `knockout_form_for` helper instead of a regular form, and invoke `ko.form()` on page load for the form you want to bind. For example, given a simple `user` model:
+
+```haml
+= knockout_form_for(@user) do |f|
+
+  .form-group
+    = f.label :name
+    = f.text_field :name
+
+  .form-group
+    = f.label :registered
+    = f.check_box :registered
+
+  .form-group{"data-bind" => "visible: registered"}
+    = f.label :email
+    = f.text_field :email
+
+  .actions
+    = f.submit class: 'btn btn-primary'
+```
+
+The `data-bind` with value `visible: registered` on the `email` field. This will display the email field only if the registered property is set to true.
+
+The gem automatically creates a viewmodel for you based on the `user` model via the mapping plugin, bind it to the form, and set `value` bindings for all inputs.
+
+To ensure `ko-forms` are always initialized, you can use this script:
+
+```coffeescript
+$ ->
+  $('.ko-form').each ->
+    ko.form this
+```
+
+### Providing your own viewmodel
+
+You can use your own viewmodel with your custom functions instead of an empty object. There are a few ways of doing this:
+
+-   The easiest way is to simple define a javascript class in the global scope with the same name as the model, which will be picked up by the `ko.form()` function:
+
+
+        class @Questionnaire
+          preview:
+            alert "Questionnaire: #{@title()}"
+
+
+    You can then invoke the `preview` function in your viewmodel class from `click` handler, or using the `action` method in the form builder:
+
+        = f.action 'Preview question', 'preview'
+
+-   The other option is to manually provide a reference to the class in the `ko.form()` method invocation:
+
+        class Questionnaire
+          preview:
+            alert "Questionnaire: #{@title()}"
+
+        $ ->
+          form = $('.questionnaire-ko-form')[0]
+          ko.form form, class: Questionnaire
+
+-   Alternatively, you can provide your own already populated viewmodel instance, in which case the `model` information will not be used and the mapping plugin will not be required. Just pass a `viewmodel` option to the `ko.form` function to do this:
+
+        questionnaire = new Questionnaire()
+        ko.form form, viewmodel: questionnaire
+
+-   Furthermore, you can skip using the `ko.form` function altogether and simply run a simple `ko.applyBindings` to the form using a viewmodel of your choice.
+
+### Mapping options
+
+A custom mapping for your viewmodel can be provided as well. This will be passed directly as an argument to the `ko.mapping.fromJSON` invocation used to populate your viewmodel. It can be specified in the following ways:
+
+-   If you have supplied a viewmodel class and it has a `mapping` attribute, then it will be used automatically:
+
+        class Questionnaire
+          @mapping:
+            copy: ["description"]
+
+-   As an option to the `ko.form` method:
+
+        ko.form form, mapping: myCustomMapping
+
+### Model data
+
+The model used to populate the knockout viewmodel is the result of a `to_json` call to the Rails model. If there are certain properties you want to include that are not ActiveRecord fields, you need to specify that when creating the form.
+
+-   Add the fields to be included as a `model_options` option in the `knockout_form_for` declaration:
+
+        model_options: { include: :custom_field }
+
+-   Or directly specify the model you want to be used via `model`:
+
+        model: @questionnaire.to_json({ include: :custom_field })
+
+Keep in mind that the model information is not required if you specify your own viewmodel via the `viewmodel` option in the `ko.form` invocation.
+
+### Nested forms
+
+Nested 1-to-N forms can be easily set up, and was one of the main drivers in the development of this gem. They do require some custom options to be properly handled, which are listed next. Refer to the questionnaire form (a questionnaire has_many questions) in the example application for a complete reference.
+
+-   Child elements must be included in the `model` when serializing it to populate the viewmodel, otherwise the children will not be included when editing an instance of the parent:
+
+        model_options: { include: :questions }
+
+-   In order to use custom viewmodel classes for both the parent and child elements, a custom mapping needs to be set up:
+
+        class @Question
+
+        class @Questionnaire
+          @mapping:
+            questions:
+              create: (opts) ->
+                ko.mapping.fromJS(opts.data, {}, new Question())
+
+    This will instruct the knockout mapping plugin to use a new instance of Question for each question in questionnaire that needs to be populated.
+
+-   The `fields_for` method in the form builder is overriden so it will use a `foreach` binding to display one template for each child. A `hidden_field` for the `id` must be included to keep track of existing instances.
+
+        = f.fields_for :questions do |g|
+
+          %h3 Question
+          = g.hidden_field :id
+
+          .form-group
+            = g.label :text
+            = g.text_field :text
+
+    Inside the `fields_for` body, all the markdown will be rendered once per question, and will be bound to the corresponding instance.
+
+-   A method `add_item` is provided in the form builder for convenience, which will attempt to automatically add an empty instance of the specified child viewmodel, populated from an empty child using the mapping plugin:
+
+        = f.add_item :questions, label: "Add new question", viewmodel: 'Question'
+
+    The usage of this helper is complete optional, as adding new items to the collection can be handled manually, by writing your own `addQuestion` function in the `Questionnaire` class and invoking it as:
+
+        = f.action "Add new question", 'addQuestion'
+
+-   As with all nested forms, remember to include the `accepts_nested_attibutes_for` option in your model, so the `fields_for` generated parameters will work correctly, which need to be permitted in the controller as well.
+
+### Using your own form builder
+
+All methods in the form builder are provided in a mixin `KnockoutForms::Rails::FormBuilder::Methods` which you can include to your own FormBuilder to have it render knockout based forms.
+
+## Internals
+
+The `KnockoutForms::Rails::FormBuilder` is the core of this gem. It overrides standard input helpers by adding a `data-bind` mapping to either their value or checked state, so they are automatically bound to the viewmodel attributes.
+
+The input helpers currently supported are the following, you are welcome to send a pull request with your own:
+
+- `text_field`
+- `number_field `
+- `hidden_field`
+- `check_box `
+- `radio_button`
+- `select`
+
+The counterpart of the form builder is the javascript code that binds it: the `knockout-forms.rails.js` script contains the `ko.form` function that either directly binds the form to the chosen viewmodel, or creates the viewmodel using the `model` JSON representation and the mapping plugin.
+
+## Contributing
+
+1. Fork it ( https://github.com/manastech/knockout_forms-rails/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 a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/knockout_forms-rails.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'knockout_forms/rails/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "knockout_forms-rails"
+  spec.version       = KnockoutForms::Rails::VERSION
+  spec.authors       = ["Santiago Palladino"]
+  spec.email         = ["spalladino@manas.com.ar"]
+  spec.summary       = %q{Knockout-js powered Rails form builder}
+  spec.description   = %q{Provides a Rails form builder to seamlessly setup a Knockout-js based view model on your forms.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake"
+
+  spec.add_runtime_dependency "railties", [">= 3.1", "< 5"]
+  spec.add_runtime_dependency "actionview", [">= 3", "< 5"]
+end

data/lib/assets/javascripts/knockout-forms.rails.js

@@ -0,0 +1,33 @@
+(function() {
+  var _global = this;
+  ko.form = function(target, opts) {
+
+    var options = opts || {},
+        form = target,
+        klazz = options.class || form.getAttribute('data-viewmodel'),
+        model = options.model || form.getAttribute('data-model'),
+        viewmodel,
+        mapping;
+
+    // Get constructor function based on name
+    if (typeof(klazz) == 'string') {
+      klazz = _global[klazz];
+    }
+
+    // Use viewmodel from options or create a new one
+    if (options.viewmodel) {
+      viewmodel = options.viewmodel;
+    } else if (klazz){
+      viewmodel = new klazz;
+      mapping = klazz.mapping || options.mapping || {};
+      ko.mapping.fromJSON(model, mapping, viewmodel);
+    } else {
+      mapping = options.mapping || {};
+      viewmodel = ko.mapping.fromJSON(model, mapping);
+    }
+
+    // Apply ko bindings
+    ko.applyBindings(viewmodel, target);
+
+  };
+})(this);

data/lib/knockout_forms/rails.rb

@@ -0,0 +1,15 @@
+require "knockout_forms/rails/version"
+require "knockout_forms/rails/form_builder"
+require "knockout_forms/rails/helpers/form_helper"
+
+module KnockoutForms
+  module Rails
+    class Engine < ::Rails::Engine
+      initializer 'knockout_forms-rails.initialize' do
+        ActiveSupport.on_load(:action_view) do
+          include KnockoutForms::Rails::Helpers::FormHelper
+        end
+      end
+    end
+  end
+end

data/lib/knockout_forms/rails/form_builder.rb

@@ -0,0 +1,82 @@
+module KnockoutForms
+
+  module Rails
+
+    class FormBuilder < ActionView::Helpers::FormBuilder
+
+      module Methods
+
+        # Define attribute to bind based on input kind
+        MAPPINGS = {
+          value: %W(text_field number_field hidden_field),
+          checked: %W(check_box radio_button)
+        }
+
+        def self.included(form)
+          # Wrap all input fields so they add a KO value data bind
+          MAPPINGS.each do |bind, fields|
+            fields.each do |field_name|
+              form.send(:define_method, field_name) do |name, *args|
+                opts = args.extract_options!
+                opts['data-bind'] = "#{bind}: #{name}" unless opts.delete(:bind) == false
+                super(name, *(args << opts))
+              end
+            end
+          end
+        end
+
+        # Handle select differently due to the html opts
+        def select(method, choices = nil, options = {}, html_options = {}, &block)
+          html_options['data-bind'] = "value: #{method}" unless options.delete(:bind) == false
+          super(method, choices, options, html_options, &block)
+        end
+
+        def fields_for(collection_name, options={}, &block)
+          empty_child = options[:empty] || object.association(collection_name).klass.new
+          collection = options[:collection] || collection_name
+          # Run fields_for with a single empty child that will act as the KO template for each item
+          # and use foreach data bind to delegate the iteration to KO
+          @template.content_tag(:div,
+              super(collection_name, [empty_child], options.merge(child_index: ""), &block),
+            :'data-bind' => "foreach: #{collection}",
+            :'data-collection' => collection,
+            :'class' => "children-collection #{collection}-collection")
+        end
+
+        def add_item(collection_name, options={})
+          child_klass = object.association(collection_name).klass
+          empty_child = child_klass.new
+
+          label = options.delete(:label) || "Add new #{child_klass.model_name.singular}"
+          viewmodel_collection = options.delete(:collection) || collection_name
+          viewmodel = options.delete(:child_class) || child_klass.name
+
+          # Create an empty child to inject attributes via KO mapping
+          model = empty_child.to_json
+
+          # Create new child viewmodel augmented with model attributes and
+          # automatically add to viewmodel collection on click
+          click_handler = options[:handler] || <<-JS_HANDLER
+            function(data, event) {
+              var viewmodel = new #{viewmodel}(data);
+              ko.mapping.fromJS(#{model}, {}, viewmodel);
+              #{viewmodel_collection}.push(viewmodel);
+            };
+          JS_HANDLER
+
+          action(label, click_handler, options)
+        end
+
+        def action(label, action, options={})
+          @template.link_to(label, '#', options.merge('data-bind' => "click: #{action}"))
+        end
+
+      end
+
+      include Methods
+
+    end
+
+  end
+
+end

data/lib/knockout_forms/rails/helpers/form_helper.rb

@@ -0,0 +1,17 @@
+module KnockoutForms::Rails::Helpers
+  module FormHelper
+
+    def knockout_form_for(object, options={}, &block)
+      options[:builder]   ||= KnockoutForms::Rails::FormBuilder
+
+      html = (options[:html] ||= {})
+
+      html[:'class']          ||= "ko-form"
+      html[:'data-model']     ||= (options.delete(:model) || object.to_json(options.delete(:model_options) || {}))
+      html[:'data-viewmodel'] ||= object.class.to_s
+
+      form_for(object, options, &block)
+    end
+
+  end
+end

data/lib/knockout_forms/rails/version.rb

@@ -0,0 +1,5 @@
+module KnockoutForms
+  module Rails
+    VERSION = "1.0.0"
+  end
+end

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: knockout_forms-rails
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Santiago Palladino
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-10-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+description: Provides a Rails form builder to seamlessly setup a Knockout-js based
+  view model on your forms.
+email:
+- spalladino@manas.com.ar
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- knockout_forms-rails.gemspec
+- lib/assets/javascripts/knockout-forms.rails.js
+- lib/knockout_forms/rails.rb
+- lib/knockout_forms/rails/form_builder.rb
+- lib/knockout_forms/rails/helpers/form_helper.rb
+- lib/knockout_forms/rails/version.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Knockout-js powered Rails form builder
+test_files: []