knockout-rails 0.0.5 → 1.0.0

data/HISTORY.md

@@ -1,9 +1,15 @@
 # x.y.z - in progress
 
 - Support collections (fetch multiple records)
-- Client side validation
 - JST templating support
 
+
+# 1.0.0 - 22 December 2011
+
+- Breaking change: `@configure` should be `@persistAt`
+- Custom model events and callbacks
+- Declarative client side validation
+
 # 0.0.4-5 - 20 December 2011
 
 - Fix to inplace edit to be able to switch back to view mode when no value has changed

data/README.md

@@ -25,7 +25,8 @@ After you've referenced the `knockout` you can create your first persistent Mode
 
 ```coffee
 class @Page extends ko.Model
-  @configure 'page' # This is enough to save the model RESTfully to `/pages/{id}` URL
+  @persistAt 'page' # This is enough to save the model RESTfully to `/pages/{id}` URL
+  @fields 'id', 'name', 'whatever' # This is optional and will be inferred if not used
 ```
 
 Too simple. This model conforms to the response of [inherited_resources](https://github.com/josevalim/inherited_resources) Gem.
@@ -71,6 +72,128 @@ Now let's see how we can show the validation errors on the page and bind everyth
         %span.inline-error{:data=>{:bind=>'visible: errors.name, text: errors.name'}}
 ```
 
+## Model Validations
+
+If you are using the model, you can also take advantage of the client-side validation framework.
+
+The client side validation works similarly to the server-side validation.
+This means there is only one place to check for errors, no matter where those are defined.
+
+For example - `page.errors.name()` returns the error message for the `name` field for both client and server side validations.
+
+The piece of code below should explain client-side validation, including some of the options.
+
+```coffee
+class @Page extends ko.Model
+  @persistAt 'page'
+
+  @validates: ->
+    @acceptance  'agree_to_terms' # Value is truthy
+    @presence    'name', 'body' # Non-empty, non-blank stringish value
+    @email       'author' # Valid email, blanks allowed
+
+    @presence      'password'
+    @confirmation  'passwordConfirmation', {confirms: 'password'} # Blanks allowed
+
+    # numericality:
+    @numericality  'rating'
+    @numericality  'rating', min: 1, max: 5
+
+    # Inclusion/exclusion
+    @inclusion   'subdomain', values: ["mine", "yours"]
+    @exclusion   'subdomain', values: ["www", "www2"] 
+
+    @format      'code', match: /\d+/ # Regex validation, blanks allowed
+    @length      'name', min: 3, max: 10 # Stringish value should be with the range
+
+    # Custom message
+    @presence    'name', message: 'give me a name, yo!'
+
+    # Conditional validation - access model using `this`
+    @presence    'name', only: -> @persisted(), except: -> @id() > 5
+
+    # Custom inline validation
+    @custom 'name', (page) ->
+      if (page.name() || '').indexOf('funky') < 0 then "should be funky" else null
+```
+
+It is recommended to avoid custom inline validations and create your own validators instead (and maybe submit it as a Pull Request):
+
+
+```coffee
+ko.Validations.validators.funky = (model, field, options) ->
+  # options - is an optional set of options passed to the validator
+  word = options.word || 'funky'
+  if model[field]().indexOf(word) < 0 "should be #{word}" else null
+```
+
+so that you can use it like so:
+
+```coffee
+@validates: ->
+  funky 'name', word: 'yakk'
+```
+
+Here's how you would check whether the model is valid or not (assuming presence validation on `name` field):
+
+```coffee
+page = new @Page name: ''
+page.isValid() # false
+page.errors.name() # "can't be blank"
+
+page.name = 'Home'
+page.isValid() # true
+page.errors.name() # null
+
+```
+
+Every validator has its own set of options. But the following are applied to all of them (including yours):
+
+- `only: -> truthy or falsy` - only apply the validation when the condition is truthy. `this` points to the model so you can access it.
+- `except:` - is the opposite to only. Both `only` and `except` can be used, but you should make sure those are not mutually exclusive.
+
+
+And at the end of this exercise, you can bind the errors using `data-bind="text: page.error.name"` or any other technique.
+
+## Model Events
+
+```coffee
+class @Page extends ko.Model
+  @persistAt 'page'
+
+  # Subscribe to 'sayHi' event
+  @upon 'sayHi', (name) ->
+    alert name + @name
+
+page = Page.new name: 'Home'
+page.trigger 'sayHi', 'Hi '
+# will show "Hi Home"
+
+```
+
+
+## Model Callbacks
+
+The callbacks are just convenience wrappers over the predefined events.
+Some of them are:
+
+```coffee
+class @Page extends ko.Model
+  @persistAt 'page'
+
+  @beforeSave ->
+    @age = @birthdate - new Date()
+
+# This would be similar to
+
+class @Page extends ko.Model
+  @persistAt 'page'
+
+  @on 'beforeSave', ->
+    @age = @birthdate - new Date()
+```
+
+
 ## Bindings
 
 This gem also includes useful bindings that you may find useful in your application.
@@ -81,7 +204,7 @@ Or if you want to include all of the bindings available, then require `knockout/
 The list of currently available bindings:
 
 - `autosave` - automatically persists the model whenever any of its attributes change.
-  Apply it to a `form` element. Examples: `autosave: page`, `autosave: {model: page, when: page.isEnabled, unless: viewModel.doNotSave }`.
+  Apply it to a `form` element. Examples: `autosave: page`, `autosave: {model: page, when: page.isEnabled, unless: viewModel.doNotSave }`. *NOTE*: It will not save when a model is not valid.
 - `inplace` - converts the input elements into inplace editing with 'Edit'/'Done' buttons. Apply it on `input` elements similarly to the `value` binding.
 - `color` - converts an element into a color picker. Apply it to a `div` element: `color: page.fontColor`. Depends on [pakunok](https://github.com/dnagir/pakunok) gem (specifically - its `colorpicker` asset).
 - `onoff` - Converts checkboxes into iOS on/off buttons. Example: `onoff: page.isPublic`. It depends on [ios-chechboxes](https://github.com/dnagir/ios-checkboxes) gem.

data/lib/assets/javascripts/knockout/model.js.coffee

@@ -1,4 +1,6 @@
 #=require jquery
+#=require knockout/validations
+#=require knockout/validators
 
 # Module is taken from Spine.js
 moduleKeywords = ['included', 'extended']
@@ -17,10 +19,31 @@ class Module
     obj.extended?.apply(@)
     @
     
+Events =
+  ClassMethods:
+    extended: ->
+      @events ||= {}
+      @include Events.InstanceMethods
+    upon: (eventName, callback) ->
+      @events[eventName] || = []
+      @events[eventName].push callback
+      this # Just to chain it if we need to
+
+  InstanceMethods:
+    trigger: (eventName, args...) ->
+      events = @constructor.events
+      handlers = events[eventName] || []
+      callback.apply(this, args) for callback in handlers
+      this # so that we can chain
+
+
+Callbacks =
+  ClassMethods:
+    beforeSave: (callback) -> @upon('beforeSave', callback)
 
 Ajax =
   ClassMethods:
-    configure: (@className) ->
+    persistAt: (@className) ->
       @getUrl ||= (model) ->
         return model.getUrl(model) if model and model.getUrl
         collectionUrl = "/#{className.toLowerCase()}s"
@@ -42,6 +65,9 @@ Ajax =
     toJSON: -> ko.mapping.toJS @, @mapping()
 
     save: ->
+      allowSaving = @isValid()
+      return false unless allowSaving
+      @trigger('beforeSave') # Consider moving it into the beforeSend or similar
       data = {}
       data[@constructor.className] =@toJSON()
       params =
@@ -70,11 +96,19 @@ Ajax =
 
 class Model extends Module
   @extend Ajax.ClassMethods
+  @extend Events.ClassMethods
+  @extend Callbacks.ClassMethods
+  @extend ko.Validations.ClassMethods
+
+  @fields: (fieldNames...) ->
+    fieldNames = fieldNames.flatten() # when a single arg is given as an array
+    @fieldNames = fieldNames
 
   constructor: (json) ->
     me = this
     @set json
     @id ||= ko.observable()
+    # Overly Heavy, heavy binding to `this`...
     @mapping().ignore.exclude('constructor').filter (v)->
         not v.startsWith('_') and Object.isFunction me[v]
       .forEach (fn) ->
@@ -85,15 +119,19 @@ class Model extends Module
 
     @persisted = ko.dependentObservable -> !!me.id()
 
-  proxy: -> @mapping().ignore
-
   set: (json) ->
     ko.mapping.fromJS json, @mapping(), @
     me = this
     @errors ||= {}
     ignores = @mapping().ignore
-    for key, value of this
-      @errors[key] ||= ko.observable() unless ignores.indexOf(key) >= 0
+    availableFields = @constructor.fieldNames
+    availableFields ||= @constructor.fields Object.keys(json) # Configure fields unless done manually
+
+    #for key, value of json
+    for key in availableFields when ignores.indexOf(key) < 0
+      @[key] ||= ko.observable()
+      @errors[key] ||= ko.observable()
+    @enableValidations()
     @
 
   updateErrors: (errorData) ->
@@ -111,3 +149,4 @@ class Model extends Module
 # Export it all:
 ko.Module = Module
 ko.Model = Model
+ko.Events = Events

data/lib/assets/javascripts/knockout/validations.js.coffee

@@ -0,0 +1,67 @@
+class ValidationContext
+
+  constructor: (@subject) ->
+
+  getDsl: (source = ko.Validations.validators) ->
+    dsl = {}
+    me = this
+    @wrapValidator dsl, name, func for name, func of source
+    dsl
+
+  wrapValidator: (dsl, name, func)->
+    me = this
+    dsl[name] = (fields..., options) ->
+      if typeof(options) is 'string'
+        # Last argument isn't `options` - it's a field
+        fields.push options
+        options = {}
+      me.setValidator(func, field, options) for field in fields
+      dsl
+
+  setValidator: (validator, field, options) ->
+    me = this
+    me._validations ||= {}
+    me._validations[field] ||= []
+
+    validatorSubscriber = ko.dependentObservable ->
+      {only, except} = options
+      allowedByOnly = !only or only.call(me.subject)
+      deniedByExcept = except and except.call(me.subject)
+
+      shouldValidate = allowedByOnly and not deniedByExcept
+
+      validator.call(me, me.subject, field, options) if shouldValidate
+
+    validatorSubscriber.subscribe (newError) ->
+      currentError = me.subject.errors[field]
+      actualError = [currentError(), newError].exclude((x) -> !x).join(", ")
+      me.subject.errors[field]( actualError or null)
+
+    # Clear the error only once before the value gets changed
+    validatorSubscriber.subscribe ->
+        me.subject.errors[field](null)
+      , me.subject, "beforeChange" if me._validations[field].isEmpty()
+
+    me._validations[field].push validatorSubscriber
+    me
+
+
+Validations =
+  ClassMethods:
+    extended: -> @include Validations.InstanceMethods
+
+  InstanceMethods:
+    isValid: ->
+      return true unless @errors
+      for key, value of @errors
+        return false unless Object.isEmpty value()
+      return true
+
+    enableValidations: ->
+      return false unless @constructor.validates
+      @validationContext = new ValidationContext(this)
+      dsl = @validationContext.getDsl()
+      @constructor.validates.call(dsl, this)
+      true
+
+ko.Validations = Validations

data/lib/assets/javascripts/knockout/validators.js.coffee

@@ -0,0 +1,84 @@
+#= require knockout/validations
+
+ko.Validations.validators =
+  acceptance: (model, field, options) ->
+    val = model[field]()
+    unless val then options.message || "needs to be accepted" else null
+
+  presence: (model, field, options) ->
+    val = model[field]()
+    isBlank = !val or val.toString().isBlank()
+    if isBlank then options.message || "can't be blank" else null
+
+
+  email: (model, field, options) ->
+    val = model[field]()
+    isValid = !val or val.toString().match /.+@.+\..+/
+    unless isValid then options.message or "should be a valid email" else null
+
+
+  confirmation: (model, field, options) ->
+    otherField = options.confirms
+    throw "Please specify which field to apply the confirmation to using {confirms: 'otherField'}" unless otherField
+    orig = model[field]()
+    other = model[otherField]()
+    if orig != other and orig then options.message or "should confirm #{otherField}" else null
+
+
+  numericality: (model, field, options) ->
+    val = model[field]()
+    return unless val
+    looksLikeNumeric = val.toString().match /^-?\d+$/ # We should do better than this
+    num = parseInt val, 10
+    min = if options.min? then options.min else num
+    max = if options.max? then options.max else num
+    if looksLikeNumeric and min <= num <= max then null else options.message or "should be numeric"
+
+
+  inclusion: (model, field, options) ->
+    values = options.values
+    throw "Please specify the values {values: [1, 2, 5]}" unless values
+    val = model[field]()
+    return unless val
+    if values.indexOf(val) < 0 then options.message or "should be one of #{values.join(', ')}" else null
+
+
+  exclusion: (model, field, options) ->
+    values = options.values
+    throw "Please specify the values {values: [1, 2, 5]}" unless values
+    val = model[field]()
+    return unless val
+    if values.indexOf(val) >= 0 then options.message or "should not be any of #{values.join(', ')}" else null
+
+  format: (model, field, options) ->
+    matcher = options.match
+    throw "Please specify the match RegEx {match: /\d+/}" unless matcher
+    val = model[field]()
+    return unless val
+    if val.toString().match matcher then null else options.message or "should be formatted properly"
+
+  length: (model, field, options) ->
+    val = model[field]()
+    return unless val
+    val = val.toString().length
+    {min, max} = options
+    min = val unless min?
+    max = val unless max?
+    createMsg = ->
+      minMsg = if options.min?
+        "at least #{min} characters long"
+      else
+        ""
+      maxMsg = if options.max?
+        "no longer than #{max} characters"
+      else
+        ""
+      separator = if minMsg and maxMsg then " but " else ""
+      "should be #{minMsg}#{separator}#{maxMsg}"
+    if min <= val <= max then null else options.message or createMsg()
+
+  custom: (model, field, options) ->
+    # Treat options as a mandatory callback
+    options.call(model, model)
+
+

data/lib/knockout-rails/version.rb

@@ -1,3 +1,3 @@
 module KnockoutRails
-  VERSION = "0.0.5"
+  VERSION = "1.0.0"
 end

data/spec/javascripts/knockout/bindings/autosave_spec.js.coffee

@@ -1,7 +1,7 @@
 #= require knockout/bindings/autosave
 
 class Page extends ko.Model
-  @configure 'page'
+  @persistAt 'page'
 
 describe "AutoSave", ->
   beforeEach ->

data/spec/javascripts/knockout/model_spec.js.coffee

@@ -1,10 +1,16 @@
 class Page extends ko.Model
- @configure 'page'
+  @persistAt 'page'
+  @upon 'sayHi', (hi) ->
+    @sayHi = hi
+ 
+  @beforeSave ->
+    @beforeSaved = true
 
 
 describe "Model", ->
 
   beforeEach ->
+    jasmine.Ajax.useMock()
     @page = new Page
       id: 123
       name: 'Home'
@@ -24,9 +30,6 @@ describe "Model", ->
     expect(@page.persisted()).toBeFalsy()
 
   describe "Ajax", ->
-    beforeEach ->
-      jasmine.Ajax.useMock()
-
     it "should return jQuery deferred when saving", ->
       expect( @page.save().done ).toBeTruthy()
 
@@ -56,7 +59,20 @@ describe "Model", ->
           name: 'Home'
           content: 'Hello'
 
+    it "should not save if invalid", ->
+      @page.errors.name 'whatever'
+      expect(@page.save()).toBeFalsy()
+      expect(mostRecentAjaxRequest()).toBeFalsy()
+
     describe "errors", ->
+
+      it "should have errors on fields only", ->
+        keys = Object.keys(@page.errors)
+        expect(keys).toContain 'id'
+        expect(keys).toContain 'name'
+        expect(keys).toContain 'content'
+        expect(keys.length).toBe 3
+
       it "should have errors for fields", ->
         e = @page.errors
         e.name('a')
@@ -66,13 +82,12 @@ describe "Model", ->
         expect(e.content()).toBe 'b'
 
       describe "on 200 response", ->
-        it "should clear all errors", ->
-          @page.errors.name('something is incorrect for whatever reason')
-          @page.save() # Probably we should not allow to save in the first place
+        it "should be valid", ->
+          @page.save()
           mostRecentAjaxRequest().response
             status: 200
             responseText: "{}"
-          expect( @page.errors.name() ).toBeFalsy()
+          expect( @page.isValid() ).toBeTruthy()
               
 
       describe "on 422 resposne (unprocessible entity = validation error)", ->
@@ -83,3 +98,12 @@ describe "Model", ->
             responseText: '{"name": ["got ya", "really"]}'
           expect( @page.errors.name() ).toBe "got ya, really"
 
+  describe "events", ->
+    it "should raise events", ->
+      @page.trigger('sayHi', 'abc')
+      expect(@page.sayHi).toBe 'abc'
+
+  describe "callbacks", ->
+    it "beforeSave should be called ", ->
+      @page.save()
+      expect(@page.beforeSaved).toBeTruthy()