Validator return value formats

Standard and custom validators may return any of the following values:

• Old formats, don't support warnings:
  • true - value is valid, no error or warning is shown
  • false - value is invalid, error is shown, tooltip message is taken from 'message' property specified in place where observable was extended with the rule or default message from rule or "Error"
  • { isValid: true, message: 'custom message' } - same as true, 'message' property is ignored
  • { isValid: false, message: undefined || null || '' } - same as false,
  • { isValid: false, message: 'custom message' } - same as false, but tooltip shows specified custom message

• New format, supports warnings: { error: <value>, warning: <value> }
  • error: true - value is invalid, error is shown, tooltip message is taken from 'message' property specified in place where observable was extended with the validator or default message from rule or "Error"
  • error: 'custom message' - same as error: true, but tooltip shows specified message
  • warning: true - value validity is not affected, warning is shown if no errors were found, warning tooltip message is taken from 'message' property specified in place where observable was extended with the validator or default message from rule or "Warning"
  • warning: 'custom message' - same as warning: true, but tooltip shows specified custom message
  • {} - same as { error: false, warning: false } or true in old format

• A validator may return results in both formats, old and new, depending on a situation. For example one validator may return:
  • true - if value is valid (old format)
  • false - if value is invalid (old format)
  • { warning: 'custom message' } - if there is a warning (new format)

Validation singleton rules

A singleton rule is a rule with a unique identifier. Only one rule with same identifier can be added to an observable, any consequent call of observable.extend with a rule with same identifier will replace previously added rule with the new one. Order of rules in validation queue is preserved, new rule will be placed in the same position as old one. Most standard validation rules are singletons, rule names play role of unique identifiers. Custom validation rules can also be given unique identifiers making them singletons.

Example

Warnings support details

• warning is shown only if there is no error
• warning is shown as blue wavy line (for now at least)
• warning message is shown as tooltip on hovering of the mouse cursor over the corresponding control, like errors
• warning doesn't prevent data saving, unlike error
• warning can be returned from a validator or set manually, for details see bellow
• warning is reset at the beginning of each validation round, i.e. if warning was set manually outside of a validator it will be removed as soon as next validation round kicks in (the observable value is updated, validators added/modified, e.t.c.)
• warning returned from a validator during validation round doesn't stop that round, unlike error
• only first warning is retained, i.e. if more than one validator returned warning during validation round or warning is manually set between two validation rounds, only warning message that was set first will be retained, until next validation round

Example

Custom validator:

The same as above:

Warning propagation

• ko.validation.group( obj ) adds to the passed object 'warnings' computed property, that property returns array with warnings from all valid observables inside the group, warnings from invalid observables are excluded
• new standard validation rule 'arrayContentWarning' goes through all valid items in the array and checks for presence of warnings, if any warning is present, then validator returns { warning: true }

Example

Named validation rules

Named validation rules may be specified in the list of the anonymous rules, needed to insure order of rules execution, example:

Async validation

• validationRequest normalizes result returned from server to match the new format before passing it to the specified callback
• method setValidationResult is added to set error or warning to a validatable observable, i.e. an observable with one or more validators or an observable that was extended with { validatable: true } extension, the method accepts validation result in new format (see above) and do the following:
  • if observable was valid before and error is present in the result, then the observable becomes invalid with the new error message
  • if observable didn't have a warning before and warning is present in the result, then the new warning message is set the observable
  • if observable had error or warning before, that error or warning will not be removed regardless of the result content

Examples:

Case when async validation should be executed only for one observable and only on change of it's value.

Case when async validation can be executed for multiple observable and at arbitrary times.