Commits

Matthew Schinckel committed 40ae157

Added initial documentation.

  • Participants
  • Parent commits f8d151f

Comments (0)

Files changed (2)

+# Knockout-Validators
+
+Why another knockout validation plugin?
+
+Something just didn't quite feel right about [Knockout-validation][ko-validation].
+
+Having said that, lots of things I have done with this plugin are based on concepts used there.
+
+## Getting Started
+
+Instead of using `.extend()`, you use `.validate()` to apply a validator:
+
+    var value = ko.observable().validate({required: true});
+
+    value.errors();     // -> ["This value is required"]
+    value('value');
+    value.errors();     // -> []
+
+As you see, the `.errors()` property of the observable contains an array of validation errors based on the current value of the observable. Empty implies the value is valid.
+
+You can remove a validator that has already been applied:
+
+    value.validate({required: false});
+    value(null);
+    value.errors();     // -> []
+
+You can also pass a message string to an existing validator:
+
+    value.validate({required: "Enter a value, tiger"});
+    value(null);
+    value.errors();     // ["Enter a value, tiger"]
+
+Note: any truthy value will cause a validator to come into effect: a string will be used as the message, a function will be used as the test.
+
+### Custom Validators
+
+You can pass in an object containing the validation data:
+
+    value = ko.observable().validate({
+      number: {
+        test: function(obj) {
+          return obj === Number(obj) + "";
+        },
+        message: "You must enter a valid number",
+        html5attr: {attr: "pattern", value: "[0-9]*\.*[0-9]*"}
+      }
+    });
+
+One a validator has been applied like this, you can then still use the forms described above:
+
+    value.validate({number: false});
+    value.validate({number: "Enter a number, tiger"});
+
+You can add a re-usable validator to `ko.subscribable.fn.validate.defaultValidators`:
+
+    ko.subscribable.fn.validate.defaultValidators['integer'] = {
+      message: "This value must be a whole number",
+      test: function(value) { return value === parseInt(value, 10) + "";},
+      html5attr: {attr: "pattern", value: "-?[0-9]+"}
+    };
+
+### HTML5 Attributes
+
+If this is present on a validator, it will apply this attribute to the element.
+
+## Knockout Bindings
+
+
+    <form data-bind="allValid: $root, submit: sendData">
+      <input type="text" data-bind="value: someValue">
+      <!-- validation errors will automatically be inserted here -->
+      <input type="submit" value="Okay">
+    </form>
+    

File src/knockout.validators.js

       }
       
       if (value.errors) {
-        var $validationMessageElement = $("<label class='help-inline'></label>");
+        var $validationMessageElement = $(ko.subscribable.fn.validate.validationMessageTemplate);
         var $targets = $validationMessageElement.add('[for="' + element.id + '"]').add(element);
         $validationMessageElement.insertAfter($element);
         // Append/remove the validation message
           $validationMessageElement.html(message.join("<br>"));
           // Also apply the error class to relevant elements.
           // Note that this is not sufficient for Bootstrap: you need to
-          // have a class on 'error' on a parent div.
+          // have a class on 'error' on a parent div, and a .control-group if there is one.
           if ($('link[href*=bootstrap][rel=stylesheet]').length) {
-            $targets = $targets.add($targets.parent());
+            $targets = $targets.add($targets.parent()).add($targets.closest('.control-group'));
           }
           if (message.length) {
             $targets.addClass('error');
         }
     }
     
-    Note that the first three forms will only work if the validator you are
+    Note that the first four forms will only work if the validator you are
     attempting to apply is a known validator (ie, is in the list of defaultValidators,
     or has been applied previously).
     
     return this;
   };
 
+
+  // Now, the actual default validators. If what you want is not here, 
+  // you'll need to make it yourself!
   ko.subscribable.fn.validate.defaultValidators = {
     required: {
       message: "This value is required",
     }
   };
   
+  ko.subscribable.fn.validate.validationMessageTemplate = "<label class='help-inline'></label>";
 })();