Adding your own custom validation

Although a number of users have figured this out on their own, the example below shows one way of adding your own custom validation methods into your form. A lot of extra user interface functionality can simply be programmed into your pages with jQuery Validation. Remember that FormItBuilder simply sits on top of two existing frameworks, FormIt (the back-end form program written for ModX) and jQuery Validation (adding a lot of inline validation and user interface).

What you need to keep in mind is that to add a validation method correctly, you really should add a validation method for both the back end PHP (FormIt) as well as a mirror validation method for jQuery Validation. This is of course assuming that you are using jQuery Validation (as this is optional). Some may wish to simply add in some jQuery Validation alone and leave it at that (you just need to keep in mind that people can diable javascript validation very easily and send whatever data they want through to the back end PHP).

Adding a custom FormIt hook

Firstly we want to write a FormIt hook snippet (see the FormIt documentation for more detail) that will handle our new validation method. More than one validation method could be written into this one snippet of course. Lets assume our custom hook is called "myCustomValidation". Simply add this to the FormItBuilder setHooks method like so.

$o_fe_phone	= new FormItBuilder_elementText('phone','Phone');
$o_form->setHooks(array('myCustomValidation', 'spam','email','redirect'));

We then want to actually make the snippet. The code below is a fairly simple phone number validation method that used a regular expression. The validation method or methods could be whatever you like.

$phoneVal = $hook->getValue('phone');
$foundMatches = preg_match ('/^\(?(\d{3})\)?[- ]?(\d{3})[- ]?(\d{4})$/',$phoneVal);
if($foundMatches===1){
	return true;
}else{
	$hook->addError('phone','Phone number must be in format ###-###-####');
	return false;
}

This should take care of the FormIt validation. However if you are using jQuery Validation you want to make this same validation method there as well (ah.. wouldn't it be nice if you didn't need to write things twice).

Adding a custom jQuery Validation method

To make our custom jQuery Validation method you sould place your javascript into a separate javascript file, however for the simplicity of this example we will show it written inline. Right after your FormItBuilder snippet call (in your form output resource) you can add a javascript block to add your custom validation method and apply the rule to one or more elements in the form.

[[!FormItBuilder_TestForm? &outputType=`dynamic`]]
<script type="text/javascript">
// <![CDATA[
$().ready(function() {
	//Make a custom validation method for jQuery Validate (Could be included as an additional JS file
	jQuery.validator.addMethod("phoneNum", function(phone_number, element) {
		phone_number = phone_number.replace(/\s+/g, "");
		return this.optional(element) || phone_number.match(/^\(?(\d{3})\)?[- ]?(\d{3})[- ]?(\d{4})$/);
	}, "Please specify a valid phone number");
	
	//Add the rule to one or more elements in your form
	$("#phone").rules("add",{
		phoneNum:true,
		messages:{phoneNum:"Phone number must be in format ###-###-####"}
	});
	
});
// ]]>
</script>

If you look at the output source when loading this form page you should see the form output and javascript in place of the FormItBuidler snippet call. It is VERY important that your custom validation method is added AFTER the initialisation of jQuery Validation. It is also VERY important that your rules("add",{...}) commands are added AFTER the forms validate function has completed. Otherwise you will get javascript errors.

What if you are using a placeholder for your javascript output?

NOTE: If you are using a placeholder for your javascript output (e.g. if you are forcing it to output in the HEAD tags or just before BODY close as is frequently recommended) then you need to add your custom javascript in the appropriate places to ensure the correct running order is followed. There is no point adding a custom validation method if the form has not been given its validate method yet.