La función charger() de los formularios CVT

Como definir la función

La función charger() (cargar()) de un formulario XXX (que aparecerá en los esqueletos con #FORMULAIRE_XXX) está definida en el archivo formulaires/xxx.php o en el archivo formulaires/xxx/charger.php. La carpeta formulaires/ puede situarse en la carpeta de un plugin, o en la carpeta de esqueletos, squelettes.

Esta función debe denominarse function formulaires_xxx_charger_dist(). El sufijo _dist permite a un desarrollador redefinir la función para cambiar su comportamiento creando una función function formulaires_xxx_charger()

Los argumentos de la función

La función charger() recibe automáticamente, en el mismo orden, el valor de cada argumento pasado a la baliza #FORMULAIRE_XX. Por ejemplo al escribir

#FORMULAIRE_XX{#ID_ARTICLE, #ID_RUBRIQUE}

y la función

formulaires_xxx_charger_dist($arg1, $arg2) {
...
}

$arg1 valdrá #ID_ARTICLE, et $arg2 valdrá #ID_RUBRIQUE.

Qué debe hacer la función

La función charger() debe reenviar una tabla de valores por omisión para cada campo de ingreso de un formulario. Esta tabla tiene una doble función:

• declarar la lista de campos ingresados (la lista de los argumentos «name» de los tags html input del formulario)
• dar un valor por omisión a cada campo de ingreso.

Los valores por omisión serán utilizados la primera vez que se muestra el formulario, pero serán luego reemplazados por lo que ingrese el internauta en caso de volver a presentar el formulario luego un error de verificación.

Ejemplo de una función charger()
Veamos un ejemplo

function formulaires_xxx_charger_dist() {
  $valores = array();
  $valores['apellido'] = 'Indica tu apellido';
  $valores['nombre'] = '';
  $valores['email'] = '';
  return $valores;
}

Aquí, la función charger() va a devolver una tabla asociativa con 3 campos ’apellido’, ’nombre’, ’email’ y un valor por omisión para cada uno de ellos.

Incluso si el valor por omisión del campo está vacío, es importante de hacerlo figurar en la tabla que devuelve la función charger(). En efecto, SPIP luego utiliza esta tabla para saber que campos fueron ingresados.

No es necesario proteger el valor de los campos si contienen comillas, por ejemplo: SPIP lo hará automáticamente.

Cada valor de campo será recuperado en el esqueleto de un formulario html con, por ejemplo acá, #ENV{apellido}, #ENV{nombre}, #ENV{email}

Campos particulares

La función charger() puede devolver ciertos valores particulares:

editable
Este valor se utiliza en el esqueleto del formulario para permitir o no el ingreso de datos. Por omisión, luego del procesamiento del formulario, «editable» es falso y el ingreso de datos al formulario no se vuelve a proponer. Sólo un mensaje de éxito se muestra.

Es posible dar un valor a «editable» para manejar las condiciones particulares de activación o no del ingreso de datos en el formulario.

message_ok
El mensaje de éxito, en principio, es devuelto por la función traiter(). No obstante, es posible que sea devuelto por la función charger() en forma derogatoria.

message_erreur
El mensaje de error, en principio, es devuelto por la función traiter(). No obstante, es posible que sea devuelto por la función charger() en forma derogatoria.

action
Este valor indica la URL a la cual se remite (post) el formulario. Por omisión es la URL de la página corriente. Es importante que así sea en el caso general ya que, en caso de error de datos, hay que poder volver a presentar el formulario.

En ciertos casos derogatorios, puede ser útil de modificar esta URL. Esto está reservado a usos muy específicos

_forcer_request
Por omisión, SPIP verifica que el formulario remitido es el correcto, para permitir tener varios formularios del mismo tipo en una página, y sólo procesar el que fue sometido. La verificación está basada en la lista de argumentos pasados a la baliza #FORMULAIRE_XXX.

En ciertos casos, cuando estos argumentos cambian en razón de un ingreso de datos, SPIP puede equivocarse y creer que el ingreso de datoas viene de otro formulario.
Al pasarle true como valor de _forcer_request, le indica que no debe hacer esta verificación y que debe tratar el ingreso de datos en todos los casos.

_action
Si el procesamiento del formulario xxx debe llamar una función del la carpeta actions/ que está protegida por securiser_action(), es posible, indicando el nombre de la acción, que SPI entregue automáticamente el hash de protección correspondiente.

_hidden
El valor de este campo será agregado directamente en el código HTML del formulario generado. Se la utiliza para agregar campos no visibles (input hidden) que deberán ser escritos explícitamente:

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

_pipeline
Este campo permite solicitar que el resultado del cálculo del formulario pase por el pipeline mencionado permitiendo así su extensión por otros plugins.
Puede ser una simple cadena (string), para la definición del nombre del pipeline :

$valores['_pipeline'] = "mipipeline";

o una tabla de dos valores, para precisar los argumentos que se entregan al pipeline :

$valores['_pipeline'] = array("mipipeline", array('arg1' => 'unvalor', ...));

Prefijos u protección de los campos de ingreso de datos
Por omisión, todos los valores de la tabla están protegidos para poder insertar en toda seguridad en un atributo value de un input en el esqueleto del formulario. Cuando el valor es a su vez una tabla, cada uno de sus valores está protegido, y así recursivamente.

No obstante, los campos prefijados por un _ (underscore) no serán protegidos automáticamente por SPIP. Cuando es necesario pasar valores a un esqueleto , pero que no serán utilizados para el ingreso de datos, se aconseja utilizar sistemáticamente este prefijo.

A la inversa, no se fdebe utilizar un prefijo _ (underscore) para un campo de ingreso de datos, ya que se ignora el valor ingresado por el visitante cuando se vuelve a presentar el formulario en caso de error.

Personalización

Una función charger() de un formulario existente puede ser personalizada por dos mecanismos:

Sobrecarga
Como indicado más arriba, es posible redefinir la función charger() por omisión, definiendo una función propia function formulaires_xxx_charger() que será llamada en lugar de la función por oomisión que comprende el sufijo _dist. Esta sobrecarga podrá situarse en el archivo formulaires/xxx/charger.php, o en un archivo options.php que siempre se carga.

Pipeline
El pipeline formulaire_charger permite modificar el resultado de la función charger() por omisión de cualquier formulario CVT.

Es el método que hay que privilegiar en un plugin.

El pipeline recibe en argumento una tabla de la forma:

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

Escribiendo la función pipeline de la manera siguiente:

function miplugin_formulaire_charger($flux){
...
}

su argumento comprenderá los elementos siguientes:

Todos los formularios pasan por el mismo pipeline. Por ende se debe probar el valor de $flux['args']['form'] para modificar sólo el comportamiento del formulario que nos concierne.

Ver también las funciones verifier() y traiter()