evolutionValidation jQuery Plugin

jQuery.fn.evolutionValidation

Supports validation related to one or more button/link click events.

Usage

Initializes validation.

$('SELECTOR').evolutionValidation(options)

Initializes validation. The selector should represent one or more links/buttons that can submit the form being validated.

Options

• validateOnLoad: True/false/null. If true, validation will be performed when the page loads. If false, it will not. If null, the form will be validated on load if any textual input fields have values.
• onValidated: Function called when validation is performed. Parameters are: validationSuccessful (bool), submitButtonClicked (bool), failedValidationContext (object).
• onSuccessfulClick: Function called when a submit button is clicked and validation was successful. Parameters are: event.

Methods

addField

Registers an input field for validation associated to the selected submit buttons/links given:

$('SELECTOR').evolutionValidation('addField', inputSelector, { ruleName: true, messages: { ruleName: 'Error message' } }, errorMessageSelector, validationContext)

• inputSelector: the jQuery selector for the input field.
• validationRules: the validation rules dictionary, consisting of a validation method as key and it's configuration as value. A key of messages, optional, can be specified as a dictionary of validate method name to error message (to override default error messages).
• errorMessageSelector: the element, jQuery object, or jQuery selector for the element(s) to be populated with validation information associated to this field.
• validationContext: any object providing context for this field. This value is passed to the onValidated function associated to this set of submission links/buttons.

Supported validation rules

• date: The input contains a valid date. Configuration value should always be true
• dateISO: The input contains a valid ISO date. Configuration value should always be true
• digits: The input contains only numeric digits. Configuration value should always be true
• email: The input contains a valid email address. Configuration value should always be true
• emailexists: The input contains an email address not used by a currently registered member in the community. Configuration value should always be true
• emails: The input contains one or more valid email addresses separated by commas or semi-colons. Configuration value should always be true
• equalTo: The input's value is equal to the value of another input. The configuration value is a string jQuery selector representing the input to validate against.
• groupnameexists: The input contains a group name that does not currently exist within the provided parent group in the community. Configuration value should be an object with a function named getParentId() that returns the integer ID of the parent group in which to search for names.
• mailinglistnameexists: The input contains a mailing list name that is not currently in use within the community. Configuration value should be an object with a property id with the integer value of the existing mailing list being edited or true
• max: The input represents a number that is at most the configured maximum value. Configuration value is the numeric maximum allowed.
• maxlength: The input must be shorter (or fewer selections of a select or checkbox group must be made) than the configured maximum. Configuration value is the numeric maximum allowed.
• min: The input represents a number that is at least the configured minimum value. Configuration value is the numeric minimum required.
• minlength: The input must be longer (or more selections of a select or checkbox group must be made) than the configured minimum. Configuration value is the numeric minimum required.
• number: The input represents a valid decimal number. Configuration value should always be true
• passwordvalid: The input contains a value that meets the password requirements of the community. Configuration value should always be true
• pattern: The input contains a value that matches the provided regular expression. Configuration value is the string representation of the regular expression to validate against.
• range: A numeric input must be between a given numeric range, represented as an array of [minimum, maximum]
• rangelength: The input's string length must be between a given numeric length range, represented as an array of [minimum, maximum]
• required: The input must contain a value. The configuration value should be true or a function that returns true if the field should be required.
• step: The input contains a number that is a multiple of the provided configuration value. The configuration value is the number that the input must be a multiple of.
• url: The input contains a valid URL. The configuration value is always true
• username: The input contains a value that matches the required username requirements set by the community. The configuration value should always be true
• usernameexists: The input contains a value that does not exist as a username in the community. The configuration value should always be true
• wikipageexists: The input contains a value that does not exist as the name of a wiki page within the provided context. The configuration value should be an object with a property wikiId set to the contextual wiki's integer ID, pageId set to the contextual wiki page's integer ID, and a function parentPageId() that returns the contextual parent wiki page's integer ID.

addCustomValidation

Registers a custom validation function for validation associated to the selected submit buttons/links given:

$('SELECTOR').evolutionValidation('addCustomValidation', id, validationFunction, errorMessage, errorMessageSelector, validationContext)

• id: the identifier for this validation rule
• validationFunction: the function that, when called, returns a boolean or a promise that resolves to a boolean identifying whether the test is valid or not.
• errorMessage: the text to show when this custom validation fails.
• errorMessageSelector: the element, jQuery object, or jQuery selector for the element(s) to be populated with validation information associated to this custom rule.
• validationContext: any object providing context for this rule. This value is passed to the onValidated function associated to this set of submission links/buttons.

This method returns a function reference that can be called to execute this custom validation rule. For example, the returned function could be attached to an onchange event for another jQuery plugin.

isValid

Returns whether the set of fields and custom rules are valid for the selected submit button/link set. When a validation rule is based on a callback/promise, the immediate return may be false but the callback will resolve to the result of the delayed validation.

$('SELECTOR').evolutionValidation('isValid', callback)

• callback: a function that receives a boolean when validation has fully calculated.

validate

Forces validation to occur on all fields and custom rules associated to the selected submit button/link set and returns the result. When a validation rule is based on a callback/promise, the immediate return may be false but the callback will resolve to the result of the delayed validation.

$('SELECTOR').evolutionValidation('validate', callback)

• callback: a function that receives a boolean when validation has fully calculated.

validateField

Forces validation on the field or fields identified by the fieldSelector within the context of the selected submit button/link set. The result of the validation is returned. When a validation rule is based on a callback/promise, the immediate return may be false but the callback will resolve to the result of the delayed validation.

$('SELECTOR').evolutionValidation('validateField', fieldSelector, callback)

• callback: a function that receives a boolean when validation has fully calculated.

validateCustom

Forces validation on the custom validation rule referenced by the given ID within the context of the selected submit button/link set. The result of the validation is returned. When a the custom validation is based on a callback/promise, the immediate return may be false but the callback will resolve to the result of the delayed validation.

$('SELECTOR').evolutionValidation('validateCustom', id, callback)

• callback: a function that receives a boolean when validation has fully calculated.

reset

Resets the validation state for all registered fields as if the form was completely reloaded. This is suitable for resetting the form after an AJAX submission and clearing of the form's values.

$('SELECTOR').evolutionValidation('reset')