How to define the function
The traiter() function in a form XXX (which is output in a template using the
#FORMULAIRE_XXX tag) is defined either in the
formulaires/xxx.php file or in the
formulaires/xxx/traiter.php file. The
formulaires/ folder may be within the folder of a plugin or in the generic squelettes folder.
This function must be named
function formulaires_xxx_traiter_dist(). The _dist allows developers to redefine the function to change its behaviour, by creating an overloaded function named
The function’s arguments
Just like the charger() and verifier() functions, the traiter() 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 traiter() function performs all the processing necessary after submission of the form that the site visitor has filled out, and after the verifications that have been performed by the verifier() function.
The important point to note here is that the traiter() function will always be called just after the verifier() function and only if that previous function has returned an empty array, thereby indicating that there weren’t any errors.
Once the actions have been performed (e.g. saving the data, writing to a file, sending an email ...), the traiter() function must return an array of the values describing the results of the actions.
This array returned by traiter() must include at least one of the two values
message_erreur to indicate the corresponding success or failure of the processing.
If everything went ok, indicating as such in a message allows the user to be reassured that the action(s) have been performed. It is always good form to return this kind of message, even if everything went well!
Despite the verification checks performed by the verifier() function, the processing might fail for other reasons that can not be detected in advance. In such cases, the traiter() function indicates the cause of the error in message_erreur, and the user will be informed about the problem that occurred.
By default, once the form has been filled out and processed successfully, the form will not be offered again to the user, but only the success or error message will be displayed.
By returning a value of
true in this field, the user will be again offered to enter a new set of data into the form.
If the processing has inserted or modified one (or more) data records in the database, it is a good idea to return the corresponding primary keys for those records, which generally all start with
In this way, a plugin which wishes to intervene following the default processing will know on which object(s) the operation applied to and take suitable follow-up actions.
Simply entering a URL in this field to redirect the site visitor to another page after data entry.
Attention: it is important that the traiter() function does not execute the redirection itself, since that will prevent any intervention of a plugin that wishes to perform tasks after the traiter() function.
An example of the traiter() function
Let’s look at an example
In this example, the function
- retrieves the data entered;
- adds an author into SPIP’s standard authors table;
- saves the surname, first name and email address for that author;
- provides the id_auteur added in the results, as well as the success message.
If the author could not be added, an error message is returned instead.
Forms can easily be ajax-enabled by including them in an ajax class. The charger(), verifier() and traiter() functions don’t recognise anything particular about such form classes and simply don’t see any difference.
Nonetheless, it is sometimes necessary that the traiter() function not be called in ajax mode. For example, perhaps it will make massive changes to the database, and it would then be preferable to redisplay the entire page after the data entry, and not just the part that includes the form itself (which is what ajax forms generally do).
In such cases, the traiter() function should start by calling the
If the form has not been submitted in ajax mode, then this function won’t do anything anyway, and the rest of the traiter() function will be executed as per normal.
It is therefore essential that the traiter() function start by making this call to
refuser_traiter_formulaire_ajax(), and to not perform any operation at all prior to calling that function, since otherwise such tasks will be executed twice.
Just like the charger() and verifier() function, the traiter() function of an existing form can be customised in two ways:
As indicated above, it is possible to redefine the default traiter() function by defining a new function formulaires_xxx_traiter() 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/traiter.php file, or in an options.php file that is defined as soon as SPIP needs to use it.
The formulaire_traiter pipeline allows modification of the results of the default traiter() 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|
||the $res array returned by the default traiter() function|
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.