The traiter() function in CVT forms

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 function formulaires_xxx_traiter()

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

#FORMULAIRE_XX{#ID_ARTICLE,#ID_RUBRIQUE}

and the

formulaires_xxx_traiter_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 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_ok or message_erreur to indicate the corresponding success or failure of the processing.

message_ok
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!

message_erreur
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.

editable
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.

id_xx
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 id_.

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.

redirect
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

function formulaires_xxx_traiter_dist() {
	$res = array();
	$surname = _request('surname');
	$firstname = _request('firstname');
	$email = _request('email');
	
	include_spip('action/editer_auteur');
	if ($id_auteur = insert_auteur()) {
		auteurs_set($id_auteur,array('surname'=>"$surname $firstname",'email'=>$email));
		$res['message_ok'] = "Save successful!";
		$res['id_auteur'] = $id_auteur;
	}
	else
		$res['message_erreur'] = "A problem occurred - it was not possible to save your data";

	return $res;
}

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.

Special scenarios

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
refuser_traiter_formulaire_ajax() function.

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.

But if the form has been submitted in ajax mode, then this function will pre-empt everything by returning a special code to the page’s JavaScript. When the JavaScript receives this code, it provokes a resending of the forms data, but this time without the ajaxification. SPIP will then call the verifier() function again, and then the traiter() function, which this time will execute completely and be allowed to perform its normal tasks.

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.

Customisation

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

Overloading
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.

Pipeline
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:

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

By writing the pipeline in the form

function myplugin_formulaire_traiter($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.

See also

Functions

• The charger() function in CVT forms
• The verifier() function in CVT forms

On programmer.spip.net

• le pipeline formulaire_traiter
• les formulaires CVT
• d’autres exemples