Validations - adammcarth/instance.js GitHub Wiki

Instance ships with a handy set of client side validation rules that let you check if user inputted data is in the correct format or not (such as an email address). By default, Instance won't make a request to the server if a validation fails.

Validations are defined in the definition of an Instance Model...

var Comment = new Instance({
   validations: {
      username: { // the name of the attribute/field that you want to validate
         min_length: { // name of a preset validation rule (full list below)
            value: 6,
            pass: function() { // callback function if validation is OK
               // highlight the field in green
            },
            fail: function() { // callback function if validation FAILS
               // highlight the field in red and display a message!
            }
         }
      }
   }
});

01. Presence: Checks if the attribute contains anything.

presence: {
   value: true || false
}

02. Length: The attribute must be x characters long.

length: {
   value: <integer>
}

03. Maximum Length: The attribute must be less than x characters long.

max_length: {
   value: <integer>
}

04. Minimum Length: The attribute must be greater than x characters long.

min_length: {
   value: <integer>
}

05. Numeric: Checks if the attribute contains only numbers [0-9] (spaces allowed).

numeric: {
   value: true || false
}

06. Alphabetic: Checks if the attribute contains only letters [aA-zZ] (spaces allowed).

alphabetic: {
   value: true || false
}

07. Alphanumeric: Checks if the attribute contains both letters and numbers [aA-zZ0-9] (spaces allowed).

presence: {
   value: true || false
}

08. Spaces: Checks if the attributes contains one or more spaces.

spaces: {
   value: true || false
}

09. Must Include: The attribute must include certain characters or phrases.

must_include: {
   value: <string> || <array>
}

10. Must Exclude: The attribute must exclude certain characters or phrases.

must_exclude: {
   value: <string> || <array>
}

11. Starts With: Checks if the attribute starts with x.

starts_with: {
   value: <string>
}

12. Ends With: Checks if the attribute ends with x.

ends_with: {
   value: <string>
}

13. Email Address: Checks if the attribute is in the form [email protected].

email: {
   value: true || false
}

14. Custom: Checks if the instance matches a custom regular expression.

regex: {
   value: /^(Oh hai der!)/g
}

15. URL: Sends the attribute value to the specified URL in an asynchronous GET request for external validation. Useful for checking username availability etc.

url: {
   value: "/api/check_username" [string]
}

• In your server script, you can access the value of the attribute using the value parameter. The above example would generate /api/check_username?value=<attribute>. For advanced users, the value can also be retrieved from a request header called Instance-Validation.
• To tell Instance the validation/test failed, you can:
  • Return any http status code other than 200 OK
  • or output the text false
  • or output the text 0
• Anything else with a 200 status will be interpreted as passing.
• Callbacks (fail, pass) will be executed by Instance as per usual once a response is received.

There's also some additional callbacks you can use. Define these at the top level of your Instance Model (outside of the validations object).

var Comment = new Instance({
   before_validation: function() {
      ...
   },
   after_validation: function() {
      ...
   },
   validation_passed: function() {
      ...
   },
   validation_failed: function() {
      ...
   }
});

Don't forget, you can skip validation at any time so that Instance sends data to the server regardless of if it fails validations or not. Simply pass false to the validations argument of the send function...

Comment.send("/comments/new", "post", false); // skip validation

Don't forget you can tell Instance to run validations at any time (without sending data to the server if they pass). All callback functions will be executed after the tests have been completed.

Comment.validate();