The igValidator provides a number of built-in validation rules that define a certain criteria values must conform to - including type checks, range limits, regular expression pattern and custom function.
You need to first read the following topics:
Rule checks are applied each time validation is performed on the target or field in their specified order to asses the validity of the current value. All rule configurations accept at least an errorMessage to allow setting a custom text just for that particular check, while some might include additional options. The igValidator locale also has a predefined set of appropriate rule messages, so in case setting one is not needed most rules support a shorthand configuration.
In some scenarios the igValidator control or field options needs to use multiple validation rules in order to validate upon different criteria or supplement (for example required and number). In those cases it is important to mention that those are performed in a particular order to prevent unnecessary checks and also present the user correct information about what requirement the value did not meet. The simplest, more general validations pass with priority and then the more sophisticated, specialized conditions are performed.
Note: By default, if one of the rules in the chain fails then the value is considered invalid and no further rules will be checked. This way if a value is empty, the error message will state the value is required, even though it would also technically not pass as valid email as well.
By default, the validations priority is as follows:
The executeAllRules option allows multiple rules to run even if one has already failed, overriding the default behavior. This causes each validation to run all applicable rules, accumulate and display multiple error messages. Can be set at the root level options, inherited by entries in the fields collection as well as set separately for each field.
$("#editor").igValidator({
onchange: true,
executeAllRules: true,
lengthRange: { min: 8 },
pattern: {
expression: /\d/,
errorMessage: "Must contain at least one number"
},
custom: {
method: function (val, opts) {
var valid = true;
if (val === $("#name").val()) {
valid = false;
}
return valid;
},
errorMessage: "Value can't be the same as the name"
}
});
Normally, most rules won't execute without a value after required and this option will not force those checks. It will however allow the validation process to continue regardless, reaching the Custom function that can run on an empty field. This allows the custom logic to determine the validity of an empty value independently of the required option.
The required rule validates that a value was entered. This applies to multiple scenarios - inputs and editors cannot have empty text as value, multiple choice targets (such as a checkbox group or an igCombo) are required to have at least one item selected. A single checkbox control will be required to be checked.
Note: As this rule is first in priority, no other rule should be concerned with or fail if the value is empty as validation stops after checking the required condition, unless
executeAllRulesis enabled in which case all but the Custom rule ignore empty values.
Can be configured as both a boolean value or an object with message:
$('#editor').igValidator({
required: true
});
// OR
$('#editor').igValidator({
required: {
errorMessage : "This field is required."
}
});
This step is optional and is fired only when you use an igEditor. The validator will call isValid on the editor to check if its specific requirements (selection, required mask fields, etc.) are fulfilled. The igValidator will attempt to use an error-specific message from the editor, but if no such is available will revert to the generic "default" locale one. There are no additional options related to this functionality.
The number rule checks if the value is a valid number. The rule allows to specify decimals and thousands separators, so number formats beyond the native JavaScript parsing can be validated. Globally defined in the defaults obejct separators for decimals and thousands are '.' and ',' respectively. Can be used help guide the ValueRange validation.
Number check can be configured as both a boolean shorthand or an object with settings:
$('#editor').igValidator({
number: true
});
// OR
$('#editor').igValidator({
number: {
errorMessage : "Not a valid number",
decimalSeparator: ".",
thousandsSeparator: " "
}
});
The date checks if a value (usually sting-based) can be successfully parsed as a JavaScript Date object. Can be used help guide the ValueRange validation.
Note: Dependat on JavaScript Date parsing which will accept a wide range of formats, but also partial values.
Can be configured as both a boolean value or an object with message:
$('#editor').igValidator({
date: true
});
// OR
$('#editor').igValidator({
date: {
errorMessage : "Not a valid date"
}
});
The lengthRange rule checks if the value length falls between a certain minimum, maximum or both. This applies equally to string values length and array values length.
For error messages this rule can use a wide variety of locale entries based on the value type and options - "minSelectMessage" for array values (multi-selection targets), "maxLengthMessage" for string values exceeding the maximum or "rangeLengthMessage" that fully states the range when both ends are defined. All messages make use of placeholders such as "{0}" to replace min and max in case those change at runtime and can also be used in the errorMessage option.
Can be configured as array shorthand or an object with options:
$('#editor').igValidator({
lengthRange: [ 1, 10]
});
// OR
$('#editor').igValidator({
lengthRange: {
min: 6,
max: 20,
errorMessage: "Must be at least {0} long and no more than {1}."
}
});
Note: Only one of the
minandmaxrange values can be set, so shorthand configurations such aslengthRange: [ 1 ]orlengthRange: [, 10]are also valid as falsy (undefined, null or 0) values are ignored.
The valueRange rule checks if the value is between a certain minimum, maximum or both. This applies equally to comparable values - numbers and dates. Since dates can also have a numeric representation, setting the number or date rules can help guide the validation. When working with numbers, this rule inherits the number rule parsing capabilities reusing either its separator options or the defaults.
Like the LengthRange this rule uses different messages depending on which the range ends defined and those can also contain placeholders. Similarly, ranges can be defined with only one end, but 0 is an accepted value.
Can be configured as array shorthand or an object with options:
$('#editor').igValidator({
valueRange: [ 1, 10]
});
// OR
$('#editor').igValidator({
valueRange: {
min: 6,
max: 20,
errorMessage: "Value must be between {0} and {1}."
}
});
The equalTo validation requires the value of the target and another field to be the same. The selector for the other field can point to different types of input and including elements on which other supported Ignite UI for jQuery editor controls are initialized. This check is performed based on the igValidator triggers where the rule is defined.
Can be configured with a valid jQuery selector/reference or and object with selector option additional message:
$('#editor').igValidator({
equalTo: $("#myEditor")
});
// OR
$('#editor').igValidator({
equalTo: {
selector: "#myEditor"
errorMessage: "Value did not match."
}
});
The email rule checks if the value is a valid email address. Note that the full email address specification allows for a very wide range of characters and format and is considered mostly impossible to fit in a rule and rarely applied, so the default regular expression used for email validation closely follows the one defined in the HTML5 specification for email input.
Can be configured as both a boolean value or an object with message:
$('#editor').igValidator({
email: true
});
// OR
$('#editor').igValidator({
email: {
errorMessage : "Enter a valid email"
}
});
The creditCard verifies the given value is a valid payment card (often commonly referred to as credit card) number. This check does not depend or check on the card type as it uses the Luhn algorithm that can validate all of the active issuers. Values can contain spaces and dashes and any number of digits. In case of specific type length and format requirements, those can be validated using the Length Range in advance and Pattern (regular expression) rule, which will pass after this one.
Note: Keep in mind this validation only confirms the card number conforms to the algorithm and not that such card actually exists, as such numbers can be easily generated.
Can be configured as both a boolean value or an object with message:
$('#editor').igValidator({
creditCard: true
});
// OR
$('#editor').igValidator({
creditCard: {
errorMessage : "Enter a valid card number"
}
});
The pattern matches the value against a JavaScript regular expression. Accepts either a RegExp object or a valid string that can be passed to the new RegExp() constructor.
Can be configured with both a RegExp value or an object with expression and message:
$('#editor').igValidator({
pattern: "^[a-z]+$"
});
// OR
$('#editor').igValidator({
pattern: {
expression: /^[a-z]+$/,
errorMessage : "Value did not match"
}
});
The custom rule allows to execute an external function to determine the validity of the value. The function can be provided as direct reference or by name as long as it's visible in the global scope (i.e. window["name"]). The function will be executed in the context of the control, so 'this' can be used as a reference the calling igValidator widget. Should accept value and optional field settings arguments to determine and return the state of the field as a boolean.
Can be configured with both a RegExp value or an object with expression and message:
$('#editor').igValidator({
custom: function(value, fieldOptions){
return false;
}
});
// OR
$('#editor').igValidator({
custom: {
method: function(value, fieldOptions){
return false;
},
errorMessage : "Value did not match"
}
});
Like other options when the igValidator is configured with a fields collection, some rule settings can also be set globally in the options and be inherited by all fields. All type-based rules and range rules can be inherited, leaving out only the field-specific equalTo and pattern. Each field can also define its own rules to override the globals.
$('#validationForm').igValidator({
required : true, //global
fields : [{
selector : "#requiredField"
}, {
selector : "#notRequired",
required : false, // override
}
]
});
The $.ui.igValidator.defaults holds the global defaults used by all instances of the igValidator. Those include the following properties:
showAllErrorsOnSubmit Boolean option to show all errors on submit. Value false will show error message only for the first failed target. Default value is true.decimalSeparator Default decimal separator (".") to use when no explicit number option property is definedthousandsSeparator Default decimal thousands (",") to use when no explicit number option property is definedemailRegEx Default email checking RegExp object matching the HTML5 specification for email input.To globally override one of those settings set the property after loading the required Ignite UI for jQuery resources and before initializing the igValidator control.
// override default thousands separator:
$.ui.igValidator.defaults.thousandsSeparator = "";
View on GitHub