Etapa 1: Crear el esqueleto de tu formulario
Dentro del subdirectorio formulaires/ de tu directorio de esqueletos, crea el archivo contact.html que contendrá el html de tu formulario de contacto. Por ejemplo:
<form action='#ENV{action}' method='post'>
#ACTION_FORMULAIRE{#ENV{action}}
<label>Tu email</label>
<input type='text' name='email' value='#ENV{email}' />
<br />
<label>Tu mensaje</label>
<textarea name='message'>#ENV{message}</textarea>
<input type='submit' name='ok' value='Enviar' />
</form>
Como puedes ver, este formulario sólo contiene unos pocos detalles:
- El atributo action de la etiqueta
<form>contiene#ENV{action}que es la url de la página en curso sobre la que el formulario será enviado. -
#ACTION_FORMULAIRE{#ENV{action}}permite a SPIP recolectar los datos enviados desde el formulario y llamar a las funciones « cargar, verificar, tratar ».
- Cada input, select o textarea, contiene el valor
#ENV{xxx}, donde xxx corresponde al atributo name del elemento.
En este punto, ya se puede colocar el formulario dentro de un esqueleto con #FORMULAIRE_CONTACT, o bien directamente en el texto de un artículo con <formulaire|contact>. Podrás disfrutar de poner a prueba y perfeccionar la apariencia y el contenido de tu formulario sin escribir una sola línea de PHP.
Sin embargo, aunque escribas texto en los campos y hagas clic sobre el botón, tu formulairo no hará nada.
Etapa 2: la función de carga
Ahora vamos a decirle SPIP los campos que el usuario o usuaria puede llenar.
Crear un archivo para que contact.php en las dentro del subdirectorio formulaires/ (al lado de su esqueleto contact.html, se entiende), y poner el siguiente código:
<?php
function formulaires_contact_charger_dist(){
$valeurs = array('email'=>'','message'=>'');
return $valeurs;
}
¿Qué hace este código?
Declara la función charger del formulario contact del directorio formulaires denominado consecutivamente formulaires_contact_charger.
El sufijo _dist señala que se trata de la función de carga por defecto de este formulario, pero que puede ser personalizada.
Esta función lista, en el arreglo $valeurs, los campos de entrada del formulario y el valor inicial por defecto para cada uno.
Hasta el momento, la función formulaires_contact_charger_dist retorna la lista de campos.
Puedes probar el comportamiento del formulario si llenas los campos y pulse el botón Enviar. Podrás ver que el formulario no ha perdido los valores introducidos (aunque todavía no hace nada útil).
En este ejemplo, todos los campos están vacíos de forma predeterminada. Podemos mejorar nuestra función de rellenar automáticamente el correo electrónico cuando el visitante se ha identificado.
Eso nos daría el siguiente código siguiente para la función de carga:
function formulaires_contact_charger_dist(){
$valeurs = array('email'=>'','message'=>'');
if ($GLOBALS['visiteur_session']['email'])
$valeurs['email'] = $GLOBALS['visiteur_session']['email'];
return $valeurs;
}
Si pruebas el formulario ahora, mientras estás conectado o conectada, podrás notar:
- que el campo email ya está completado con el email de tu cuenta SPIP.
- que los valores introducidos o modificados se mantienen sin cambios después de la validación
Etapa 3 : Verificar que los datos son correctos
Antes de utilizar los valores introducidos por el usuario debemos comprobar que son correctos.
En nuestro caso, por ejemplo, definimos las siguientes condiciones:
- Los campos email y mensaje son obligatorios
- El la dirección de correo electrónico debe ser válida
Para verificar la validez de los datos vamos a crear la función de
formulaires_contact_verifier_dist (del mismo modo que la función de carga) siempre en el mismo archivo contact.php :
function formulaires_contact_verifier_dist(){
$erreurs = array();
// verificar que los campos obligatorios están llenos :
foreach(array('email','message') as $obligatoire)
if (!_request($obligatoire)) $erreurs[$obligatoire] = 'Este campo es obligatorio';
// verificar que el email ingresado es válido :
include_spip('inc/filtres');
if (_request('email') AND !email_valide(_request('email')))
$erreurs['email'] = 'La dirección de correo ingresada no es válida';
if (count($erreurs))
$erreurs['message_erreur'] = 'Los datos ingresados contienen errores!';
return $erreurs;
}
Nota : El uso de _request() se explica en doc.spip.org
La función de verificación devuelve una lista de campos con errores, con un mensaje de error asociado a cada campo.
En este punto, no podrás ver ninguna diferencia si pruebas el formulario: por el momento, el esqueleto contact.html no muestra los errores. Para cambiarlo, completa lo siguiente:
[<p class='formulaire_erreur'>(#ENV*{message_erreur})</p>]
<form action='#ENV{action}' method='post'>
#ACTION_FORMULAIRE{#ENV{action}}
<label>Tu email</label>
[<span class='erreur'>(#ENV**{erreurs}|table_valeur{email})</span>]
<input type='text' name='email' value='#ENV{email}' />
<br />
<label>Tu mensaje</label>
[<span class='erreur'>(#ENV**{erreurs}|table_valeur{message})</span>]
<textarea name='message'>#ENV{message}</textarea>
<input type='submit' name='ok' value='Enviar' />
</form>
Notar:
- La muestra de un error general devuelto por la función de verificación
[<p class='formulaire_erreur'>(#ENV*{message_erreur})</p>] - Los mensajes de error para cada campo particular :
[<span class='erreur'>(#ENV**{erreurs}|table_valeur{email})</span>]
Ahora puedes probar escribiendo un correo electrónico incorrecto o dejando un campo vacío: ¡tu formulario ya está empezando a interactuar con el usuario!
Etapa 4 : ¡procesar los datos!
Cuando la función de verificación no devuelve ningún error SPIP llama automáticamente a la función del tratamiento correspondiente. Esta función se declara formulaires_contact_traiter_dist (siempre en el archivo contact.php) y haremos que envíe un correo electrónico al webmaster o la webmaster del sitio.
function formulaires_contact_traiter_dist(){
$enviar_mail = charger_fonction('envoyer_mail','inc');
$email_para = $GLOBALS['meta']['email_webmaster'];
$email_de = _request('email');
$asunto = 'Formulario de contacto';
$mensaje = _request('message');
$enviar_mail($email_para,$asunto,$mensaje,$email_de);
return array('message_ok'=>'Hemos recibido su mensaje correctamente. Nos pondremos en contacto en breve.');
}
Debes tener en cuenta que la función de procesamiento no realiza ninguna verificación: todas fueron hechos con antelación (en la función de verificación). Si la función de tratamiento se llama implica que no hubo errores.
La función devuelve un identificador de mensaje de éxito "message_ok, contenida en un array. Como con los mensajes de error, tenemos que completar nuestro formulario para que muestre este mensaje. Como sigue:
[<p class='formulaire_ok'>(#ENV*{message_ok})</p>]
[<p class='formulaire_erreur'>(#ENV*{message_erreur})</p>]
[(#EDITABLE|oui)
<form action='#ENV{action}' method='post'>
#ACTION_FORMULAIRE{#ENV{action}}
<label>Tu email</label>
[<span class='erreur'>(#ENV**{erreurs}|table_valeur{email})</span>]
<input type='text' name='email' value='#ENV{email}' />
<br />
<label>Tu mensaje</label>
[<span class='erreur'>(#ENV**{erreurs}|table_valeur{message})</span>]
<textarea name='message'>#ENV{message}</textarea>
<input type='submit' name='ok' value='Enviar' />
</form>
]
Observar :
- Se muestra el mensaje de éxito al principio
[<p class="formulaire_message">(#ENV*{message_ok})</p>] - La presentación del formulario queda condicionada en función de la baliza #EDITABLE : después del envió, si todo fue bien, en general es más claro para el usuario mostrarle sólo un mensaje de éxito que todo el formulario completo nuevamente. #EDITABLE cumple este propósito.
¡Y listo! Puedes utilizar el formulario de contacto.
El bonus
¿Te gustaría que la interacción entre el formulario y el usuario sea más rápida y no implique volver a cargar la página entera con cada error o durante la validación?
Entonces tu formulario debe implementarse con AJAX. Normalmente esto significa un problema porque suele ser un trabajo largo y laborioso. Pero SPIP lo ha simplificado para los CVT, permitiendo beneficiarse de las herramientas automatizadas, incluyendo la "ajaxización" de los formularios.
Para esto, simplemente hay que poner el formulario en un div con la clase ajax.
<div class='ajax'>
#FORMULAIRE_CONTACT
</div>
¡Y voilá!
Para más
- Este sencillo ejemplo, no es un formulario demasiado agradable. Para obtener un resultado más estético, semántico y accesible, no dude en utilizar las recomendaciones de estructuras de Estructura HTML de formularios en SPIP para todos sus formularios Spip
- Para saber más :
La función charger() de los formularios CVT
La fonction verifier() des formulaires CVT
La fonction traiter() des formulaires CVT