Need help with ember-validations?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

lcoq
126 Stars 26 Forks MIT License 144 Commits 12 Opened issues

Description

Ember-Validations - An Ember.js library for handling object validations

Services available

!
?

Need anything else?

Contributors list

No Data

Ember Validations Build Status

Warning: This project is no longer updated. dockyard/ember-validations is a great similar library

Ember-validations is a Ember.js library that can handle object validations. If you have to check the validity of object properties, this library does it for you. You just have to declare which property you want to validate, and which kind of validation you want for this property.

This library is inspired by the validations of the Ruby gem

ActiveRecord
.

Getting ember-validations

Currently you must build ember-validations yourself. Clone the repository, run

bundle
then
rake dist
. You'll find
ember-validations.js
in the
dist
directory.

Example

App.User = Ember.Object.extend( Ember.Validations, {
  country: null,

validations: { name: { presence: true }, age: { numericality: true, length: { moreThan: 21, lessThan: 99 }, }, email: { format: /[email protected]+..{2,4}/ } } });

Usage

  • Extend
    Ember.Validations
    mixin:
App.User = Ember.Object.extend( Ember.Validations );
  • Define its validations by settings them in its
    validation
    property. The following example is a
    presence
    validation that ensures the
    name
    of the
    User
    is set:
App.User = Ember.Object.extend( Ember.Validations, {
  validations: {
    name: {
      presence: true
    }
  }
});
  • Launch validations on an object using the
    validate
    method.
var user = App.User.create();
user.validate();
  • The
    isValid
    property is now set as
    true
    , or
    false
    depending on the validations result:
user.get('isValid'); // => false

Errors

Once the

validate
method is called, if some properties are invalid, the
validationErrors
property is updated.

For the example below, we assume we have a

User
defined like this:
App.User = Ember.Object.extend( Ember.Validations, {
  validations: {
    name: {
      presence: true
    },
    age: {
      numericality: {
        moreThanOrEqualTo: 21,
        lessThan: 99
      }
    },
    'address.zipCode': {
      numericality: true
    }
  }
});

An error is defined by a

key
, a
message
, and a
path
. There are three types of error messages:
  • allMessages
    : It returns all errors. Each of them is an array that contains the
    path
    and the
    message
    error, as follows:
user.get('validationErrors.allMessages');

Will return this array:

[
  [ "name", "can't be blank" ],
  [ "age", "is not greater than or equal to 21" ],
  [ "age", "is not less than 99" ],
  [ "address.zipCode", "is not a number" ]
]
  • fullMessages
    : It has the same behaviour as
    allMessages
    , except that errors are the
    path
    and the
    message
    concatenated:
[
  "name can't be blank",
  "age is not greater than or equal to 21",
  "age is not less than 99",
  "address.zipCode is not a number"
]
  • messages
    : It returns only errors messages corresponding the path specified (
    age
    here):
user.get('validationErrors.age.messages');

Will return this array:

[
  "is not greater than or equal to 21",
  "is not less than 99"
]

Remark: There are also

keys
and
allKeys
properties that works like messages, but for error keys.

Validators

Presence

It ensures the attribute is not blank. You can define it as follow, in the

validation
property:
name: {
  presence: true
}

Length

The

length
validation is used to check the
length
of the property. Three options can be passed:
  • minimum
  • is
  • maximum

Example:

password: {
  length: {
    minimum: 6,
    maximum: 12
  }
}

When no option is specified, the

is
option is set by default:
phone: {
  length: 10
}

Is equivalent to:

phone: {
  length: {
    is: 10
  }
}

Numericality

The

numericality
validation can have multiple usage, defined by its option:
  • onlyInteger
  • greaterThan
  • greaterThanOrEqualTo
  • lessThan
  • lessThanOrEqualTo
  • equalTo

Example:

amount: {
  numericality: {
    moreThanOrEqualTo: 1,
    lessThan: 100
  }
}

When no option is passed, it just add an error if the value can not be parsed as a number (e.g. when the value contains letter):

amount: {
  numericality: true
}

Format

It validates whether the attribute has (or not, depending on the option specified) the supplied regexp.

The simplest way to use it is as follow:

email: {
  format: /[email protected]+\..{2,4}/
}

But you can specify options

with
and/or
without
:
password: {
  format: {
    with: /[a-zA-Z]+/,
    without: /[0-9]+/
  }
}

Match

It validates whether the contents of 2 properties are the same

There is only 1 option:

  • match

Example:

password: {
  match: {
    property: {
      "confirmPassword"
    }
  }
},
confirmPassword: {
  ....
}

Single property validation

Sometime you could want to validate only one property. You can do this by calling

validateProperty('attributeName')
instead of
validate()
. It will also update the
isValid
property if the validity of the object changes.

Runtime validations

A function can be passed to the validations options for runtime validations. An example could be:

age: {
  length: {
    moreThan: function() {
      return this.get('country') === 'France' ? 18 : 21;
    }
  }
}

Skipping validations

Validators will, by default, skip validations on blank values. The

presence
validation ignores this option for obvious reasons.

You can disable this behaviour by setting the

allowBlank
option to
false
.

Custom validations

On-the-fly

You can define custom validation function, like this:

password: {
  myCustomValidator: {
    validator: function(object, attribute, value) {
      if (!value.match(/[A-Z]/)) {
        object.get('validationErrors').add(attribute, 'invalid');
      }
    }
  }
}

Write your own validator

You can write your own validator easily.

  • Define your validator in the
    Ember.Validators
    namespace. It allows to use via its name. For example, writing an
    Ember.Validators.FooValidator
    allows you to use it using:
validations: {
  name: {
    foo: true
  }
}
  • Extend

    Ember.Validator
    and implement the
    _validate
    method. Just take a look at the existing validators to see how to write it.
  • That's all folks!

Building Ember-Validations

  1. Run
    rake dist
    task to build Ember-validations.js. Two builds will be placed in the
    dist/
    directory.
    • ember-validations.js
      is a unminified version (generally used for development)
    • ember-validations.min.js
      is the minified version, production ready

If you are building under Linux, you will need a JavaScript runtime for minification. You can either install nodejs or

gem install
therubyracer
.

Build API Docs

NOTE: Require

node.js
to generate it.

Preview API documentation

Run

rake docs:preview
.

The

docs:preview
task will build the documentation and make it available at http://localhost:9292/index.html

Build API documentation

Run

rake docs:build

The HTML documentation is built in the

docs
directory

How to run Unit Tests

Setup

  1. Install Ruby 1.9.2+. There are many resources on the web can help; one of the best is rvm.

  2. Install Bundler:

    gem install bundler
  3. Run

    bundle
    inside the project root to install the gem dependencies.

In Your Browser

  1. To start the development server, run

    rackup
    .
  2. Then visit: `http://localhost:9292/tests/index.html

From the CLI

  1. Install phantomjs from http://phantomjs.org

  2. Run

    rake test
    to run a basic test suite or run
    rake test[all]
    to run a more comprehensive suite.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.