How to use the validation in your UI

Validation in Monster-UI is done using the jQuery Validation plugin. Their documentation is very complete, and it is strongly advised that you take look at it to have a better understanding of how it works.

In this document, we will go over the basics of validation in Monster-UI, and the different options it offers.

How to use it

First, validation is done on html forms, so you need to make sure that all the fields that you want to validate are nested in a <form> tag.

Then, you need to set up validation on your form, by using the monster.ui.validate(form, options) method. This will activate the validation on the provided form. Note: You should not call directly the validate(options) method from the plugin, it will be called by the monster.ui.validate(form, options) method.

	var formToValidate = template.find('#demoapp_form');
	monster.ui.validate(formToValidate);

Finally, you can use the monster.ui.valid(form) to “run” the validation. This method will return true if the validation succeeded, or false if it failed.

	if(!monster.ui.valid(formToValidate)) {
		monster.ui.alert('error', 'There are errors in your form');
	} else {
		//Your code...
	}

In addition, the validation process will append a label element after each invalid field, with the class ‘monster-invalid’. You can use this class to customize these labels within your application. If you do so, make sure to namespace it with a container id from your template so that you don’t affect other apps. The content and position of these labels can be customized using the validate options, as detailed below.

Standard validation rules

The validation plugin comes with a set of standard rules that should cover most of your validation needs. There are two ways to define them: with inline html or through the monster.ui.validate method.

Inline rules

Some of the basic validation rules can be defined directly inside the html, using the HTML5 standards. Below are a few examples:

required: The element is required. <input type="text" required>
minlength: The element requires a given minimum length. <input type="text" minlength="2">
maxlength: The element requires a given maximum length. <input type="text" maxlength="10">
min: The element requires a given minimum number. <input type="text" min=5>
max: The element requires a given maximum number. <input type="text" max=15>
email: The element should contain an email address. <input type="email">

Through the monster.ui.validate method

The monster.ui.validate method has an option parameter that can contain a rules object. This object should be a map with input names as keys and maps of rules as value.

Let’s say we want an required input that contains digits only, and an optional input that contains an URL. Here’s what it would look like:

<form id="demoapp_form">
	<input type="text" name="digits_input">
	<input type="text" name="url_input">
</form>

monster.ui.validate(formToValidate, {
	rules: {
		digits_input: {
			required: true,
			digits: true
		},
		url_input: {
			//required is false by default, so it can be omitted
			url: true
		}
	}
});

For the full list of standard validation rules, see here.

Cutsom validation rules

We added the following custom rules to the set of usable validation rules:

checkList: The value of this element should not appear in the provided list (array or map).
greaterDate: The element should contain a date greater than the one in the provided input.
greaterThan: The element should contain a number greater than or equal to the one in the provided input.
hexadecimal: The element should contain a valid hexadecimal value.
ipv4: The element should contain a valid IPv4 address.
lowerThan: The element should contain a number lower than or equal to the one in the provided input.
mac: The element should contain a valid MAC address.
notEqualTo: The element should not contain a value equal to any in the provided inputs.
phoneNumber: The element should contain a valid phoneNumber.
protocol: The element should contain a valid protocol prefix.
realm: The element should contain a valid realm.
regex: The element should contain a value that matches the provided regular expression.
time12h: The element should contain a time in 12-hour format (AM/PM).
time24h: The element should contain a time in 24-hour format.

We didn’t make a simplified function to add custom rules directly within your app, but you can do it using the jQuery.validator.addMethod method.

Other options

Several different options can be set in the monster.ui.validate method, below is a quick overview of those options. See here for the complete list.

Key	Description	Type	Default	Required
`autoScrollOnInvalid`	Scroll the viewport to display the first error in the form after validation, if there is any. This is a specific setting for Monster UI.	`Boolean`	`false`	`false`
`messages`	Allows you to customize the content of the appended error labels. This is only if you want to override the default messages.	`Object`		`false`
`errorPlacement`	Allows you to choose where to append your error labels.	`Function`		`false`
`errorClass`	Allows you to set a custom class for your error labels. This is not advised as it will replace the monster-invalid class.	`String`	`monster-invalid`	`false`

Example:

monster.ui.validate(formToValidate, {
	rules: {
		digits_input: {
			required: true,
			digits: true
		}
	},
	messages: {
		digits_input: {
			required: 'Required!',
			digits: 'Digits only!'
		}
	},
	errorPlacement: function(error, element) {
		error.appendTo(element.parent());
	},
	errorClass: "demoapp-invalid",
	autoScrollOnInvalid: true
});