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
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
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
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.
The verifier() function can return certain special values in the array:
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.
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.
Just like the charger() function, the verifier() function of an existing form can be customised in two ways:
As indicated above, it is possible to redefine the default verifier() function by defining a new
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.
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:
By writing the pipeline in the form
then you will find that $flux will contain the following entries:
||name of the form (xxx in the example above)|
||the arguments of the charger() function in the same order that they were passed to the #FORMULAIRE_XXX tag|
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.