Field Validation

Field validation is useful to confirm the value(s) that you are getting in from the field on the form, is what you are expecting it to be or matches what you want it to be. The form in formularizes uses some basic validation already. if the field can be required and that option is enabled, it makes sure the field isn't empty. However, the basic validation is limited in what it can do. With field validation, it allows you to configure your own input validation from the field, to make sure the value(s) being submitted by the user is what you want it to be. Only visible fields will be validated, so if a field is "hidden" by a conditional being met, then the validation of that field will be skipped. 

There are several reasons you might want to do this, one of the most common reason, is if you are expecting a certain type of value and the user doesn't submit a value that conforms to that. It might also be, that you want the expected value to change based on another fields value. If you have 2 number fields, one represents a max value and the other is a minimum value, you want to confirm that the min value isn't greater than the max value. In the follow example, we will use this concept.

First thing you want to do is create your fields in the form builder.

Next you will want to go to your ACP, Go to Community->Formularize->Field Validation

Next click "Create New":

Here you want to type the form name in the "Form" field, it will bring up available forms that match, select the right one. It will then proceed to populate the field list.

after you select the form, the Field and Validation code section will refresh. Select the field you want the validation to happen on. Now in the validation code section, you will se a codemirror editor and a tags section to the right of the editor. In the "tags", you will find a list of tags that the validation code can use (note: you can use any php or IPS class or php class that is available to IPS here, these tags are what is related to this particular form).

We have selected the "minimum value" field, so we want to make sure the that its value does not exceed or equals the maximum value. $value will be the value submitted for this field, on the right in tags, you will find shortcuts that will insert and get the values from other fields on the form thru the \IPS\Request, these values will be in their raw form, and not all fields will have easily accessible values, not in their raw form. this is a limitation of the IPS form class, as formularize only augments this process, it doesn't replace it. Keep that in mind when using these shortcuts, cause it might not be the in a form that you can readily use, you will need to do your own processing on it. However for the number field, the value will be as it is expected, an integer or float.

After the PHP opening tag in the editor, we are going to create a IF control structure, to check the values:

if(\IPS\formularize\Math::of($value)->isGreaterThan(\IPS\Request::i()->aw5gq8zywhzg_id)){

}

Here we are using the math class in formularize (it uses the Brick/Math included in IPS, but the class is designed to make it easier to work with). We will pass the $value of the Minimum field to Math::of(), and then we will check to see if it is greater than the Maximum Value (which we access via \IPS\Request):

Once we have the IF control structure in place, it will check the values, and if Minimum is greater than the Maximum value, it will be TRUE, and will execute the code inside the IF control structure. Here we will want to throw an exception, the most common you will want to throw is an InvalidArgumentException (any LogicException exceptions can be used here, but for simplicities sake, InvalidArgumentException is usually the appropriate one). 

you can add any message you want to be deliver by the exception, this is the message that will appear below the form, to let the user know what the form was rejected. You can also use IPS language strings here if you prefer. I will be using a english string for this example however. Once you have this done, you can save the the Field Exception and test it out.

As you can see, the validation works! it wont let the form be submitted, cause the value is greater than the maximum value. We can duplicate this with the maximum field, but reverse it, check the max value is lesser than the minimum value:

With that in place, now both fields will show an error message, that tells the user why the form wasn't accepted.

There is a lot you could do with validation, it will be up to you on what you can do with it. I would also like to point out, that since field validation exposes PHP and the IPS framework, you should take caution with who you give access to this section. the validation should never return anything, it should never output or be sending or receiving data from any where but the form itself. So be vigilant with this section, as it is a powerful tool to have access too, but it could be used for malicious reasons. 

If you have any questions or comments, ask below.