Class: SC.Validator


Extends SC.Object.

Validators provide a way for you to implement simple form field validation and transformation. To use a validator, simply name the validator in the "validate" attribute in your text field. For example, if you want to validate a field using the PhoneNumberValidator use this:

<input value="1234567890" validate="phone-number" />

Validators get notified at three points. You can implement one or all of these methods to support validation. All of the validate methods except for validateKeypress behave the same way. You are passed a form, field, and possibly the oldValue. You are expected to return Validator.OK or an error string. Inside this method you typically do one of all of the following:

  1. You can simply validate the field value and return OK or an error str
  2. You can modify the field value (for example, you could format the string to match some predefined format).
  3. If you need to roundtrip the server first to perform validation, you can return Validator.OK, then save the form and field info until after the roundtrip. On return, if there is a problem, first verify the field value has not changed and then call form.errorFor(field,str) ;

Defined in: validator.js

Since:
SproutCore 1.0

Field Summary

Fields borrowed from SC.Object:
concatenatedProperties, isDestroyed, isObject, nextProperty, object, property, target, toInvalidate
Fields borrowed from SC.Observable:
isObservable

Class Methods

Instance Methods

Field Detail

SC.Validator.NO_CHANGE
Return value when validation was not performed.
SC.Validator.OK
Return value when validation was performed and value is OK.

Class Method Detail

fieldValueForObject(object, form, field)

Convenience class method to call the fieldValueForObject() instance method you define in your subclass.

Parameters:
object
form
field
findFor(form, field, validatorKey)

Invoked by a field whenever a validator is attached to the field.

The passed validatorKey can be a validator instance, a validator class or a string naming a validator. To make your validator visible, you should name your validator under the SC.Validator base. for example SC.Validator.Number would get used for the 'number' validator key.

This understands validatorKey strings in the following format: 'key' or 'multiple_words' will find validators Key and MultipleWords if you want to share a single validator among multiple fields (for example to validate that two passwords are the same) set a name inside brackets. i.e. 'password[pwd]'.

Parameters:
form SC.FormView
the form for the field
field SC.View
the field to validate
validatorKey Object
the key to validate
Returns:
SC.Validator
validator instance or null
objectForFieldValue(value, form, field)

Convenience class method to call the objectForFieldValue() instance method you define in your subclass.

Parameters:
value
form
field

Instance Method Detail

attachTo(form, field)

Called on all validators when they are attached to a field.

You can use this to do any setup that you need. The default does nothing.

Parameters:
form SC.FormView
the form for the field
field SC.View
the field to validate
detachFrom(form, field)

Called on a validator just before it is removed from a field. You can tear down any setup you did for the attachTo() method.

Parameters:
form SC.FormView
the form for the field
field SC.View
the field to validate
fieldValueForObject(object, form, view)

Returns the value to set in the field for the passed object value.

The form and view to be set MAY (but will not always) be passed also. You should override this method to help convert an input object into a value that can be displayed by the field. For example, you might convert a date to a property formatted string or a number to a properly formatted value.

Parameters:
object Object
The object to transform
form SC.FormView
The form this field belongs to. (optional)
view SC.View
The view the value is required for.
Returns:
Object
a value (usually a string) suitable for display
objectForFieldValue(value, form, view)

Returns the object value for the passed string.

The form and view MAY (but wil not always) be passed also. You should override this method to convert a field value, such as string, into an object value suitable for consumption by the rest of the app. For example you may convert a string into a date or a number.

Parameters:
value String
the field value. (Usually a String).
form SC.FormView
The form this field belongs to. (optional)
view SC.View
The view this value was pulled from.
Returns:
Object
an object suitable for consumption by the app.
validate(form, field)

Validate the field value.

You can implement standard behavior for your validator by using the validate() and validateError() methods. validate() should return NO if the field is not valid, YES otherwise. If you return NO from this method, then the validateError() method will be called so you can generate an error object describing the specific problem.

Parameters:
form SC.FormView
the form this view belongs to
field SC.View
the field to validate. Responds to fieldValue.
Returns:
Boolean
YES if field is valid.
validateChange(form, field, oldValue:)

Invoked just before the user ends editing of the field.

This is a primitive validation method. You can implement the two higher-level methods (validate() and validateError()) if you prefer.

The default implementation calls your validate() method and then validateError() if validate() returns NO. This method should return SC.VALIDATE_OK if validation succeeded or an error object if it fails.

Parameters:
form SC.FormView
the form for the field
field SC.View
the field to validate
oldValue: Object
the value of the field before the change
Returns:
SC.VALIDATE_OK or an error object.
validateError(form, field)

Returns an error object if the field is invalid.

This is the other standard validator method that can be used to implement basic validation. Return an error object explaining why the field is not valid. It will only be called if validate() returned NO.

The default implementation of this method returns a generic error message with the loc string "Invalid.Generate({fieldValue})". You can simply define this loc string in strings.js if you prefer or you can override this method to provide a more specific error message.

Parameters:
form SC.FormView
the form this view belongs to
field SC.View
the field to validate. Responds to fieldValue.
Returns:
SC.Error
an error object
validateKeyDown(form, field, char)

Invoked when the user presses a key.

This method is used to restrict the letters and numbers the user is allowed to enter. You should not use this method to perform full validation on the field. Instead use validatePartial().

Parameters:
form SC.FormView
the form for the field
field SC.View
the field to validate
char String
the characters being added
Returns:
Boolean
YES if allowed, NO otherwise
validatePartial(form, field)

Invoked 1ms after the user types a key (if a change is allowed).

You can use this validate the new partial string and return an error if needed. The default will validate a partial only if there was already an error. This allows the user to try to get it right before you bug them.

Unlike the other methods, you should return SC.VALIDATE_NO_CHANGE if you did not actually validate the partial string. If you return SC.VALIDATE_OK then any showing errors will be hidden.

Parameters:
form SC.FormView
the form for the field
field SC.View
the field to validate
Returns:
SC.VALIDATE_OK, SC.VALIDATE_NO_CHANGE or an error object.
validateSubmit(form, field)

Invoked just before the form is submitted.

This method gives your validators one last chance to perform validation on the form as a whole. The default version does the same thing as the validateChange() method.

Parameters:
form SC.FormView
the form for the field
field SC.View
the field to validate
Returns:
SC.VALIDATE_OK or an error object.
Documentation generated by JsDoc Toolkit 2.4.0 on Sun Oct 27 2013 19:58:52 GMT-0600 (CST)