The charger() function in CVT forms

How to define the function

The charger() function in a form XXX (which is output in a template using #FORMULAIRE_XXX) is defined in either the formulaires/xxx.php or the formulaires/xxx/charger.php file. The folder formulaires/ may be within a plugin’s folder or the general squelettes folder.

The function must be named function formulaires_xxx_charger_dist(). The _dist suffix allows developers to redefine the function to change its behaviour by creating a function formulaires_xxx_charger() function.

The function’s arguments

The charger() function automatically receives the value of each argument passed to the #FORMULAIRE_XXX tag, in the same order in which they are passed to the tag.
For example, given

#FORMULAIRE_XX{#ID_ARTICLE,#ID_RUBRIQUE}

and the

formulaires_xxx_charger_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 charger() function must return an array of default values for each input field of the form.
This array serves two purposes:

• declaring the list of input fields (the list of all the name values of the inputs used by the form), and
• providing a default value for each input field.

The default values provided will be used for the initial output of the form, but will thereafter be replaced by the values entered by the user if it is re-output because of an error with one of the values.

Example function
Let’s have a look at the following example:

function formulaires_xxx_charger_dist(){
 $valeurs = array();
 $valeurs['surname'] = 'Enter your last name';
 $valeurs['name'] = '';
 $valeurs['email'] = '';
 return $valeurs;
}

Here, the loading function will return an associative array with three fields, ’surname’, ’name’ and ’email’, each with a default value.

Note that even if the default value is empty, it is important to include it in the array returned by charger(), as SPIP then takes this array to be the definitive list of input fields to use.

It is not necessary to protect fields’ default values if, for example, they contain quotes. SPIP does this automatically.

Each value of the field can be used in the form’s HTML template by means of tags; for the example above: #ENV{surname}, #ENV{name} and #ENV{email}.

Special values

The charger() function can return certain special values.

editable
This value is used in the form’s template to allow or forbid modification of the form. By default, after processing of the form, editable is false and the user is not given the form again to fill in: only messages indicating that the data has been received are output.

It is possible to provide a value for editable to govern special conditions for the activation, or otherwise, of treatment of the form.

message_ok
The success message is in principle provided by the traiter() function, but it is nontheless possible to return it from charger() in special cases.

message_erreur
The error message is in principle provided by the traiter() function, but it is nonetheless possible to return it from charger() in special cases.

action
This value specifies the URL to which the form’s data is sent. By default, this is the URL of the current page and it is usually important to leave this unchanged, because, if a problem occurs during treatment of the form, it has to be possible to show it again.

In certain special cases, it may be useful to change this URL, but this functionality should be used sparingly.

_forcer_request
By default, SPIP checks that data posted to a given form’s treatment page is indeed from that form, in order to allow showing multiple forms of the same type on a given page, while only allowing treatment of the single one that was submitted. This verification is based on the list of arguments passed to the #FORMULAIRE_XXX tag.

In certain cases when these arguments change according to the data entered in the form, SPIP may erroneously believe that the posted data was sent by a different form.

Passing true as _forcer_request indicates to SPIP that it must not perform this verification, but should accept the data received no matter where it came from.

_action
_If the treatment of form xxx needs to call a function defined in the actions/ folder which is protected by securiser_action(), it is possible, by indicating the name of the action, to tell SPIP to automatically provide the corresponding security hash.

_hidden
The value of these fields will be directly output into the HTML of the generated form. This option is used to include hidden inputs, which must be explicitly created:

$valeurs['_hidden'] = "<input type='hidden' name='secret' value='go' />";

_pipeline
This field is used to specifiy that the result of the form’s calculation be passed into the pipeline referenced, thereby making it possible to extend its functions through the plugins.
This can be a simple text string to define the name of the pipeline:

$valeurs['_pipeline'] = "mypipeline";

or an associative array so that you can pass arguemnts to the pipeline:

$valeurs['_pipeline'] = array("mypipeline", array('arg1' => 'firstvalue', ...));

Prefixes and protecting fields for data entry
By default, all of the values in the table will be protected so that they can be securely applied to the value attribute of an input field in the form’s template file. When the value itself is an array, each of its values is protected too, and so on recursively.

However, fields prefixed with an _ (underscore) will not be automatically protected by SPIP. Whenever its necessary to pass values to the squelette template, but ones which will not be used for data entry, it is recommended to systematically use this prefix.

On the other hand, you must not use the _ (underscore) prefix for a data entry field, since the value entered by the user will be ignored when the form is redisplayed in the event of a data entry error.

Customisation

An existing form’s charger() function can be customised in two ways.

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

Pipeline
The formulaire_charger pipeline allows modification of the result of the default charger() 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'=>$values)
)

By writing the pipeline in the form

function myplugin_formulaire_charger($flux){
...
}

$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 verifier() and traiter() functions.