The CVT forms of SPIP 2.0

One view plus 3 steps

Take the example of a contact form that we wish to insert using the tag #FORMULAIRE_CONTACT.

Display
When SPIP sees the tag #FORMULAIRE_CONTACT, it recognises it as a tag of the type #FORMULAIRE_xxx. So it looks for the template formulaires/contact.html in order to display the form.
Nothing else is required for the form to be displayed. This means that the styling and visual integration on the page can be carried out entirely independently of the 3 steps outlined below.

Charging (loading)
Before displaying the form, SPIP calls, if it exists, the function formulaires_contact_charger_dist() to fill the form’s fields with any default values. These fields and values are passed to the template, formulaires/contact.html, which makes use of them.

Verifying
When a visitor fills in the form and and clicks the submit button, SPIP calls the function formulaires_contact_verifier_dist() to check the data’s validity. The function sends back a list of messages corresponding to each field for which errors have been detected, or else an empty list if no error is found.

Treating
If the verification process has not detected any error, then SPIP automatically calls the function which treats the form’s data: formulaires_contact_traiter_dist(). This function can undertake any operation with the form’s data: sending an email, saving to a database, ...

The treating function returns a list of information, including a message that confirms that the data which the user has submitted has been received.

Arguments

Any arguments which are passed by the tag, in a form such as #FORMULAIRE_CONTACT{#ID_AUTEUR} are automatically communicated to the functions which charge, verify and treat, in the same order.

Customising

The separation of forms into a display template plus the three “CVT” functions means that each of these elements can be customised independently:

• the template of a SPIP form can be customised in the squelettes/ directory;
• the function formulaires_contact_charger_dist() can be customised by defining a function named formulaires_contact_charger()
• the function formulaires_contact_verifier_dist() can be customised by defining a function named formulaires_contact_verifier()
• the function formulaires_contact_traiter_dist() can be customised by defining a function named formulaires_contact_traiter()

These functions should be placed in a file named contact.php.

AJAX

The standardisation of SPIP of the CVT process makes it possible for forms to benefit from additional features without any development.

In particular, the ease of navigation and the response time experienced by the visitor can be improved by submitting the form using asynchronous requests. Programming in this way, using AJAX is complex. But SPIP and CVT radically simplify the treating of your forms by AJAX.

It is sufficient simply to surround the form in a div with the ajax class, thus:

When the visitor submits the form, it is sent to SPIP by an asynchronous request; SPIP only returns the result after checking and treating the submitted data. The visitor receives a faster response because the whole page is not reloaded, but only the zone containing the form!

Compatibility with SPIP’s previous dynamic forms

The old dynamic forms of SPIP which used a template plus a series of functions balise_formulaires_xxx, balise_formulaires_xxx_stat, et balise_formulaires_xxx_dyn will still function. However you are advised to migrate to move towards the CVT system for your forms.

Technically CVT is an additional layer implemented by the generic functions balise_formulaires_xxx, balise_formulaires_xxx_stat, et balise_formulaires_xxx_dyn.

Therefore it would be possible, for example for the automatic collecting of arguments, to define one’s own balise_formulaires_contact_stat function.