Please choose from our list of builds for Ember-Validations

You will require Ruby to be installed on your system. If it is please run the following:

gem install bundler
git clone git://github.com/dockyard/ember-validations.git
cd ember-validations
bundle install
bundle exec rake dist

The builds will be in the dist/ directory.

If it is a bug please open an issue on GitHub.

You need to mixin Ember.Validations.Mixin into any object you want to add validations to:

var App.User = Ember.Object.extend(Ember.Validations.Mixin);

You define your validations as a JSON object on the object you want to validate. The keys in the object should map to properties. If you pass a JSON object as the value this will be seen as validation rules to apply to the property. If you pass true then the property itself will be seen as a validatable object.

App.User.reopen({
  validations: {
    firstName: {
      presence: true,
      length: { minimum: 5 }
    },
    age: {
      numericality: true
    },
    profile: true
  }
});

The currently supported validators

Validates the property has a value that is null, undefined, or ''

• true - Passing just true will activate validation and use default message
• message - Any string you wish to be the error message. Overrides i18n.

// Examples
absence: true
absence: { message: 'must be blank' }

By default the values '1', 1, and true are the acceptable values

• true - Passing just true will activate validation and use default message
• message - Any string you wish to be the error message. Overrides i18n.
• accept - the value for acceptance

// Examples
acceptance: true
acceptance: { message: 'you must accept', accept: 'yes' }

Expects a propertyConfirmation to have the same value as property

• true - Passing just true will activate validation and use default message
• message - Any string you wish to be the error message. Overrides i18n.

// Examples
confirmation: true
confirmation: { message: 'you must confirm' }

A list of values that are not allowed

• message - Any string you wish to be the error message. Overrides i18n.
• allowBlank - If true skips validation if value is empty
• in - An array of values that are excluded
• range - an array with the first element as the lower bound the and second element as the upper bound. Any value that falls within the range will be considered excluded

// Examples
exclusion: { in: ['Yellow', 'Black', 'Red'] }
exclusion: { range: [5, 10], allowBlank: true, message: 'cannot be between 5 and 10' }

A regular expression to test with the value

• message - Any string you wish to be the error message. Overrides i18n.
• allowBlank - If true skips validation if value is empty
• with - The regular expression to test with

// Examples
format: { with: /^([a-zA-Z]|\d)+$/, allowBlank: true, message: 'must be letters and numbers only'  }

A list of the only values allowed

• message - Any string you wish to be the error message. Overrides i18n.
• allowBlank - If true skips validation if value is empty
• in - An array of values that are allowed
• range - an array with the first element as the lower bound the and second element as the upper bound. Only values that fall within the range will be considered allowed

// Examples
inclusion: { in: ['Yellow', 'Black', 'Red'] }
inclusion: { range: [5, 10], allowBlank: true, message: 'must be between 5 and 10' }

Define the lengths that are allowed

• number - Alias for is
• array - Will expand to minimum and maximum. First element is the lower bound, second element is the upper bound.
• allowBlank - If true skips validation if value is empty
• minimum - The minimum length of the value allowed
• maximum - The maximum length of the value allowed
• is - The exact length of the value allowed
• tokenizer - A function that should return a object that responds to length

• tooShort - the message used when the minimum validation fails. Overrides i18n
• tooLong - the message used when the maximum validation fails. Overrides i18n
• wrongLength - the message used when the is validation fails. Overrides i18n

// Examples
length: 5
length: [3, 5]
length: { is: 10, allowBlank: true }
length: { minimum: 3, maximum: 5, messages: { tooShort: 'should be more than 3 characters', tooLong: 'should be less than 5 characters' } }
length: { is: 5, tokenizer: function(value) { return value.split(''); } }

Will ensure the value is a number

• true - Passing just true will activate validation and use default message
• allowBlank - If true skips validation if value is empty
• onlyInteger - Will only allow integers
• greaterThan - Ensures the value is greater than
• greaterThanOrEqualTo - Ensures the value is greater than or equal to
• equalTo - Ensures the value is equal to
• lessThan - Ensures the value is less than
• lessThanOrEqualTo - Ensures the value is less than or equal to
• odd - Ensures the value is odd
• even - Ensures the value is even

• greaterThan - Message used when value failes to be greater than. Overrides i18n
• greaterThanOrEqualTo - Message used when value failes to be greater than or equal to. Overrides i18n
• equalTo - Message used when value failes to be equal to. Overrides i18n
• lessThan - Message used when value failes to be less than. Overrides i18n
• lessThanOrEqualTo - Message used when value failes to be less than or equal to. Overrides i18n
• odd - Message used when value failes to be odd. Overrides i18n
• even - Message used when value failes to be even. Overrides i18n

// Examples
numericality: true
numericality: { odd: true, messages: { odd: 'must be an odd number' } }
numericality: { onlyInteger, greaterThan: 5, lessThanOrEqualTo : 10 }

Validates the property has a value that is not null, undefined, or ''

• true - Passing just true will activate validation and use default message
• message - Any string you wish to be the error message. Overrides i18n.

// Examples
presence: true
presence: { message: 'must not be blank' }

Not yet implemented.

Each validator can take an if or an unless in its options hash. The value of the conditional can be an inline function, a string that represents a property on the object, or a string that represents a function on the object. The result should be a boolean.

// function form
firstName: {
  presence: {
    if: function(object, validator) {
      return true;
    }
  }
}

// string form
// if 'canValidate' is a function on the object it will be called
// if 'canValidate' is a property object.get('canValidate') will be called
firstName: {
  presence: {
    unless: 'canValidate'
  }
}

Validations will automatically run when the object is created and when each property changes. isValid states bubble up and help define the direct parent's validation state.

If you want to force all validations to run simply call .validate() on the object. isValid will be set to true or false. All validations are run as deferred objects, so the validations will not be completed when validate is done. So validate returns a promise, call then with a function containing the code you want to run after the validations have completed.

user.validate().then(function() {
  user.get('isValid');
  // true
})

After mixing in Ember.Validations.Mixin into your object it will now have a .errors object. All validation error messages will be placed in there for the corresponding property. Errors messages will always be an array.

App.User = Ember.Object.extend(Ember.Validations.Mixin,
  validations:
    firstName: { presence: true }
  }
});

user = App.User.create();
user.validate().then(function() {
  user.get('isValid'); // false
  user.errors.get('firstName'); // ["can't be blank"]
  user.set('firstName', 'Brian');
  user.validate().then(function() {
    user.get('isValid'); // true
    user.errors.get('firstName'); // []
  })
})

• Brian Cardarella

We are very thankful for the many contributors

This library follows Semantic Versioning

Please do! We are always looking to improve this gem. Please see our Contribution Guidelines on how to properly submit issues and pull requests.

DockYard, LLC © 2013

@dockyard

Licensed under the MIT license