README.md

knockout validations extender

Adds an extender to a knockout object that allows you to validate its values and obtain the errors.

Extender

• receives validation description as a parameter, eg:

name = ko.observable().extend
  validation: {notEmpty:{message: "Hello world!!"}}

name.validate (isValid)->
  name.getAllErrors() # ["Hello World !!!"]

Install

npm install knockout-validations-extender --save

or include in your Page

``get knockout-validations-extender.min.js from github dist fodler`

You can access global variable knockoutValidationsExtender to access the api

Be aware of Dependencies

• lodash (not bundled)
• knockout (not bundled)
• promiz (bundled in)
• loglevel (bundled in)

Example

Html: (Using knockout-punches for css bindings, better syntax!)

<form data-bind="submit: performRegistration">
  <fieldset data-bind="with: registration">
    <div data-bind="with: product">
      <div data-bind="css.has-error: name.isntValid()" class="form-group">
        <input type="text" data-bind="value: name" placeholder="Product Name" class="form-control"/><span data-bind="visible: name.isntValid, text: name.joinedErrors(' / ')" class="help-block"></span>
      </div>
    </div>
    <div data-bind="with: consumer">
      <div data-bind="css.has-error: name.isntValid()" class="form-group">
        <input type="text" data-bind="value: name" placeholder="Consumer Name" class="form-control"/><span data-bind="visible: name.isntValid, text: name.joinedErrors(' / ')" class="help-block"></span>
      </div>
    </div>
    <button type="submit">Submit Registration</button>
  </fieldset>
</form>

Javascript:

var Consumer = (function() {
  function Consumer() {
    this.name = ko.observable().extend({
      validations: {
        required: {
          message: "Please, inform your name!"
        }
      }
    });
  }

  return Consumer;

})();

var Product = (function() {
  function Product() {
    this.name = ko.observable().extend({
      validations: {
        required: {
          message: "Product name is required!!"
        }
      }
    });
  }

  return Product;

})();

var Registration = (function() {
  function Registration() {
    this.product = new Product();
    this.consumer = new Consumer();
  }

  return Registration;

})();


var RegistrationViewModel = (function() {
  function RegistrationViewModel() {
    this.registration = ko.observable(new Registration()).extend({
      validations: {}
    });
    // no validations are need for registration
    // children control their own validations

  }

  RegistrationViewModel.prototype.performRegistration = function() {
    return this.registration.validate(function(isValid) {
      if (!isValid) {
        return alert("hey, please fill all fields");
      }
      alert("everything is good, done");
      this.registration(new Registration());
    });
  };

  return RegistrationViewModel;

})();

var registrationViewModel = new RegistrationViewModel();

ko.applyBindings(registration);

Coffee-script:

class Consumer
  constructor:()->
    @name = ko.observable().extend
      validations:
        required:
          message: "Please, inform your name!"

class Product
  constructor:()->
    @name = ko.observable().extend
      validations:
        required:
          message: "Product name is required!!"

class Registration
  constructor:()->
    @product = new Product()
    @consumer = new Consumer()

class RegistrationViewModel
  constructor:()->
    @registration = ko.observable(new Registration()).extend({validations:{}})
    # no validations are need for registration
    # children control their own validations

  performRegistration:()->
    @registration.validate (isValid)->
      if !isValid then return alert("hey, please fill all fields")
      alert("everything is good, done")
      @registration(new Registration())

registrationViewModel = new RegistrationViewModel()
ko.applyBindings(registration)

Error Concepts

Each knockout object can have:

• calculated errors
  • errors that are calculated based on the given validation descriptions
• manual errors
  • errors added manually to objects
• children errors
  • errors that are resolved based on observables that are contained into the current one.
  • if the current is an observable array, all errors contained in objects inside array will be resolved.
  • algorithm always goes down if the current object is an array/object, and tries to find observables that use validations extender.

All errors are either observable/computable. So they are updated instantly if the object is validated or is in a live mode.

All errors are simple string.

You can override the default error message by passing as a validation option in your field.

Extender Properties/Methods Added to Knockout Object

• observable.getOwnCalculatedErrors() # observable array

• observable.getOwnManualErrors() # observable array

• observable.getOwnErrors() # computed

• observable.hasOwnErrors() # computed

• observable.getChildrenCalculatedErrors() # computed

• observable.getChildrenManualErrors() # computed

• observable.getChildrenErrors() # computed

• observable.getAllCalculatedErrors() # computed

• observable.getAllManualErrors() # computed

• observable.getAllErrors() # computed

• observable.isValid() # computed

  true if there are any errors into object or children

• observable.isntValid() # computed

• observable.errors() # alias to getAllErrors

• observable.joinedErrors(separator) # returns a computed

• observable.validate(options, callback) ASYNC

  • performs the validation to the current object and its children.
  • callback returns boolean determining if its valid or not
  • options available:
    • reset # if true, it will reset all current errors
    • validateChildren # if false, it wont validate children

• observable.resetValidation()

• observable.hasValidation(name)

  • returns computed that returns true if the observable contains that validation

• observable.validation(name, options)

  • adds a new validation to observable
  • if its live, it should trigger a new validation

• observable.removeValidation(name)

  • removes validation

• observable.setValidations(rules)

  • replaces all validations with new object definition with rules

Extender Modes (Available extenders)

• validation
  • only validates if method validate is run
• validationLive
  • validates when something changes
• validationAlwaysLive
  • validates since the start of the object lifecycle, and when something changes.

Validations

1 - Synchronous Validations

You must register validations in order for the extender to use them.

The validations you register are an object that maps a validationName to a validationFunction.

• validationFunction returns a boolean, receives a single data parameter, where data contains:
  • value (the actual value to validate)
  • validationOptions (the options configured for this observable/validation by you)
  • parent (parent observable that called the validate method)
  • container (object that contains the current observable being evaluated.)
    • Eg: if you had an observableArray, that contains objects, that have a field observable, you could access the parent observableArray and the container object to validate that field.

koValidations = require 'knockout-validations-extender'
# or the global variable knockoutValidationsExtender
koValidation.registerValidationMethods
  required:(data)-> return data.value != null

2 - Async Validations

Async validations must have async flag specified when the validation is being registered.

Callback should be called with boolean value.

koValidation.registerValidationMethods
  required:
    async: true
    fn: (data, callback)->
      callback(data.value != null)

3 - All available options

a) Can be a simple function

koValidation.registerValidationMethods
  required:(data)-> return data.value != null

b) Can be an object

  required:
    async: true
    fn: (data, callback)->
      callback(data.value != null)
    defaultMessage: "Field should be required!"

4 - Translate Messages

If you wish to translate the error messages, you can give a function to koValidation.

koValidation.setTranslator (message, ruleOptions)->
  return message.replace('{{max}}', ruleOptions.max)