The verifier() function in CVT forms

How to define the function

The verifier() function in a form XXX (which is output in a template using the #FORMULAIRE_XXX tag) is defined in either the formulaires/xxx.php or the formulaires/xxx/verifier.php file. The formulaires/ folder may be within the specific folder for a plugin or in the generic squelettes folder.

This function must be named
function formulaires_xxx_verifier_dist(). The _dist suffix allows developers to redefine the function to change its behaviour, by creating an overloaded function named function formulaires_xxx_verifier()

The function’s arguments

The verifier() function automatically receives the value of each argument passed to the #FORMULAIRE_XX tag in the same order as they were originally passed to the tag itself.
For example, given

#FORMULAIRE_XX{#ID_ARTICLE,#ID_RUBRIQUE}

and the

formulaires_xxx_verifier_dist($arg1,$arg2){
...
}

function, $arg1 will take the value of #ID_ARTICLE, and $arg2 will take that of #ID_RUBRIQUE.

What the function has to do

The verifier() function must return an array of input errors that arise after checking all of the form’s input data values.

If all of the data values are valid, then the array will be empty, and SPIP will then call the traiter() function for the form, which is loaded once the checking work is completed.

If the array returned by the verifier() function is not empty, then the traiter() function will not be called, but the form will be redisplayed showing whatever error messages are necessary so that the user will correct the errant input fields.

It’s therefore a good idea to make all of the verifications necessary for the processing in the verifier() function to work properly as a way to ensure the best possible interactive exchange between the user and the form.

Each error is returned in the form of an associative array of key=>value pairs, and it is normal practice to use the name of the variable entered on the form as the key value.

An example of the verifier() function
Let’s look at an example

function formulaires_xxx_verifier_dist(){
	$erreurs = array();
	if (!_request('nom'))
		$erreurs['nom'] = _T('info_obligatoire');
	include_spip('inc/filtres');
	if ($email = _request('email')  AND !email_valide($email))
		$erreurs['email'] = _T('form_email_non_valide');

	return $erreurs;
}

In this example, the function

• checks that a name has been entered, and generates an error message if it has not;
• looks to see if an email address has been entered, and if so, checks to make sure that it’s a correctly formatted email address, with a suitable error message generated if it is not valid.

Special values

The verifier() function can return certain special values in the array:

message_erreur
This value is used in the template for the form to display a general error message relating to the form as a whole. It is often sensible to also provide such a message any time that there is any error message generated for any specific field on the form.

message_ok
This value is used to return a success message. This message may be useful when the site visitor has entered an initial value which allows certain details to be verified, without actually finishing data entry on that form definitively.
The presence of this message prevents the call to the traiter() function for the form, which is called if and only if the array returned by the verifier() function is completely empty.

Customisation

Just like the charger() function, the verifier() function of an existing form can be customised in two ways:

Overloading
As indicated above, it is possible to redefine the default verifier() function by defining a new function formulaires_xxx_verifier()
function which will be called instead of the default one, whose name contains the _dist suffix.
This overloaded function can be defined in the formulaires/xxx/verifier.php file, or in an options.php file that is defined as soon as SPIP needs to use it.

Pipeline
The formulaire_verifier pipeline allows modification of the results of the default verifier() function of any CVT form.

This is the method which should normally be used in a plugin.

The pipeline is passed as its argument an array in this format:

array(
	'args'=>array('form'=>$form,'args'=>$args),
	'data'=>$erreurs)
)

By writing the pipeline in the form

function myplugin_formulaire_verifier($flux){
...
}

then you will find that $flux will contain the following entries:

All forms use the same pipeline. As such, the function needs to check the value of $flux[’args’][’form’] in order to only modify data from that particular form.

Also refer to the charger() and traiter() functions.