ember-advanced-validations v1.10.2

Ember-advanced-validations

A quick summary of features provided by this validation framework:

• Validate any Ember object, such as ember-data model, Object, Controller, .. basically anything
• Apply pre-defined validations or easily create your own (and reuse them afterwards)
• Configure validations
• Run validations in async (by default - without the need to configure it)
• Apply validations on multiple fields (e.g. when field1 is empty, field2 is required)
• Apply multiple validations on the same field (e.g. this field must not be empty and it must be an integer and it must be greater than 10)
• Conditionally run validations
  • based on simple conditions (e.g. when field1 equals some value, then run this validation)
  • based on other validations (e.g. run this validation only if these two validations pass)
• Validation messages per field
  • Full support of i18n (via ember-i18n addon)
  • Custom validation messages can override default ones provided by this framework
• helper to check if speficiec field is valid or retrieve its validation message

Usage

To run a validation on an object, run:

 validationService: Ember.inject.service('adv-validation-manager'),


  this.get('validationService').validateObject(objectToValidate)
      .then((validationResult) => {
      //handle validationResult
  });

An object you want to validate must have a validations array with validation definitions:

validations: [
    Numeric: 'field1', // 'field1' must be a number
    NotEmpty: ['field2', 'field3'] // 'field2' and 'field3' must be both non-empty
]

You can also define validations in more complex way that enables more customizations (explained below):

validations: [
  {
    fields: 'field1',
    validator: 'Numeric'
  },
  {
    fields: ['field2', 'field3'],
    validator: 'NotEmpty'
  }
]

Note that both notations above are equivalent, the second one however enables more features and more customization options like these:

Validation parameters

Optionally you can pass a JSON with validation parameters to the validation process. Validation parameters will be available in runIf and validate functions as a last argument.

let params = {hello: 'world'};

this.get('validationService').validateObject(objectToValidate, params)

Available pre-defined validations

Custom validations

You can easily create your own validation - either with validation definition or globally available for all validation for all objects.

Custom validations within validation definition

All fields defined in fields are passed into validation function (in order specified in fields)

  validations: [
        {
          fields: ['field1', 'field2'],
          validator: function (field1Value, field2Value) {
            return field1Value === 'test' && field2Value === 42;
          }
        }
    ]

Custom validations accesible globally

If you want to reuse a specific validation it is a good idea to define it once. All you need to do is to create validation file in app/validators/ directory (you can also use a generator for this - just run ember generate adv-validator <validator-name>).

app/validators/my-validator.js

import Ember from 'ember';
import AdvValidator from 'adv-validator';

export default Ember.Service.extend(AdvValidator, {

  validate: function (config, field1, field2, field3) { //any number of fields based on your validation
   //TODO your validator goes here
   return true;
  }
});

Usage:

 validations: [
   {
     fields: 'field1',
     validator: 'MyValidator'
   }
 ]

Besides a required validate function you can also define these properties:

Conditional validations

Sometimes you do not want a certain validation to be executed. For this you can use runIf property in validation definition.

export default Ember.Controller.extend({

     runProperty1: true,  //<---- ordinary boolean property
     runProperty2: false //<---- ordinary boolean property

      validations: [
        {
          fields: 'field1',
          validator: 'numeric',
          runIf: 'runProperty1' <---- this validation will be executed, because 'runProperty1' is currently 'true'
        },
        {
          fields: 'field1',
          validator: 'test-validator',
          runIf: ['runProperty1', 'runProperty2'] // <--- will ne run, because at least one of the properties is currently 'false'
        }
      ],
      field1: 'test'

    }

Optionally you can run a certain validation based on some dynamic condition:

 export default Ember.Controller.extend(AdvValidable, {
      validations: [
        {
          fields: 'field1',
          validator: 'NotEmpty',
          runIf: [
            'field2', //<--- list of fields that will be passed as input parameters to runIf function            
            'field3',
            function (f2, f3, validationConfig, validationParams) { //values of fields specified above in the same order + validation config (see 'config' attribute in chapter 'Usage' in README) + validation params (see chapter README 'Validation parameters')
              return f2 === 'runMe';
            }
          ]
        }
      ],
      field1: 'test',
      field2: 'runMe',
      field3: 'hello'
    }

Complete list of arguments of runIf function are (in this order): fields that are being validated, validation configuration,

Validation helpers

You can make use of 2 helpers provided by this addon:

• getValidationMessage - retrieves validation message for specified field
• isFieldValid - returns simple true/false if specified field is valid

{{getValidationMessage field='myField' validationResult=validationResult}}

{{isFieldValid field='myField' validationResult=validationResult}}

or in JS

import {isFieldValid, getValidationMessage} from 'ember-advanced-validations/helpers/is-field-valid';

var fieldValid = isFieldValid(validationResult, 'myField');
var validationMessage = getValidationMessage(validationResult, 'myField');

Global configuration

In your config/environmnet.js file you can configure ember-advanced-validations:

var ENV = {
 ...
   adValidations: {
      i18n_enabled: false, //true if ember-i18n translations for validation messages should be enabled; default is false
      realtime_debounce: 500 //applied for 'realtime' validations; the validation is executed after this timeout (in msec)
    }
 ...

}