Etapa 1: Crear l’esquelet del formulari
En el subdirectori formulaires/ de la vostra carpeta «esquelets», creeu el fitxer contact.html que contindrà el codi HTML del vostre formulari de contacte. Per exemple:
<form action='#ENV{action}' method='post'>
#ACTION_FORMULAIRE{#ENV{action}}
<label>El vostre correu electrònic</label>
<input type='text' name='email' value='#ENV{email}' />
<br />
<label>El vostre missatge</label>
<textarea name='message'>#ENV{message}</textarea>
<input type='submit' name='ok' value='ok' />
</form>
Tal i com podeu constatar, aquest formulari només conté algunes particularitats:
- l’atribut acció de l’etiqueta
<form>conté#ENV{action}que és el url de la pàgina en curs a la que s’enviarà el formulari -
#ACTION_FORMULAIRE{#ENV{action}}indica a SPIP que ha de tenir en compte les dades enviades per aquest formulari les crides cap a les funcions «carregar, verificar, tractar» - chaque input, textarea o select conté el valor
#ENV{xxx}on xxx correspon a l’atribut del nom corresponent.
En aquest estadi, ja podeu enganxar aquest formulari a un esquelet, amb l’etiqueta #FORMULAIRE_CONTACT o directament en el text d’un article amb el codi <formulaire|contact>. Valorareu la capacitat per provar i afinar el funcionament del vostre formulari sense escriure ni una sola línia de PHP.
No obstant, si introduïu text i cliqueu sobre el botó OK, el vostre formulari no fa res, i vosaltres no trobareu allò que heu introduït.
Etapa 2: la funció carregar
Per tant, ara hem d’indicar a SPIP quins són els camps que l’internauta ha d’omplir.
Creeu un fitxer contact.php a dins del subdirectori formulaires/ (per tant, just al costat del vostre esquelet contact.html), i poseu-hi el codi següent:
<?php
function formulaires_contact_charger_dist(){
$valeurs = array('email'=>'','message'=>'');
return $valeurs;
}
?>
Què fa aquest codi?
Declara la funció carregar del formulari contacte del directori formularis consecutivament anomenat formulaires_contact_charger.
El sufixe _dist assenyala que es tracta de la funció carregar per defecte d’aquest formulari, però que es pot personalitzar eventualment (vegeu pel que fa al tema de les sobrecàrregues http://programmer.spip.org/Surcharg...).
Aquesta funció llista, a dins de la variable $valeurs, els camps d’introducció de dades del vostre formulari i, per cada camp, el valor inicial per defecte.
La funció formulaires_contact_charger_dist reenvia, per tant, aquesta llista de camps.
Proveu altre cop el vostre formulari: si ompliu els camps i valideu amb el botó OK, veureu que aquest cop el formulari no ha perdut els valors que heu introduït (tot i que encara no fa res).
En aquest exemple, per defecte, tots els camps estan buits. Podríem millorar la nostra funció omplint automàticament el correu electrònic quan el visitant s’identifica.
Per la funció carregar, això ens donaria el codi següent:
function formulaires_contact_charger_dist(){
$valeurs = array('email'=>'','message'=>'');
if ($GLOBALS['visiteur_session']['email'])
$valeurs['email'] = $GLOBALS['visiteur_session']['email'];
return $valeurs;
}
Si ara proveu el vostre formulari, quan estigueu identificats, constatareu:
- que el camp correu electrònic ja està omplert amb el correu electrònic del vostre compte d’SPIP
- que els valors introduïts o modificats es conserven tal qual després de la validació
Etapa 3: Verificar que l’entrada de dades és correcte
Abans de tenir en compte els valors introduïts per l’internauta hem de verificar, evidentment, que allò que ens envia és correcte.
Per exemple, hem de definir les següents obligacions:
- els camps correu electrònic i missatge són obligatoris
- el correu electrònic ha de ser vàlid
Per tal de verificar l’entrada de les dades, crearem la funció formulaires_contact_verifier_dist (segons el mateix model que la funció carregar) sempre a dins el mateix fitxer contact.php :
function formulaires_contact_verifier_dist(){
$erreurs = array();
// verificar que els camps obligatoris són correctes:
foreach(array('email','message') as $obligatoire)
if (!_request($obligatoire)) $erreurs[$obligatoire] = 'Aquest camps és obligatori';
// verificar que, si s'ha introduït un correu electrònic, és vàlid:
include_spip('inc/filtres');
if (_request('email') AND !email_valide(_request('email')))
$erreurs['email'] = 'Aquest correu electrònic no és vàlid';
if (count($erreurs))
$erreurs['message_erreur'] = 'La vostra entrada de dades conté errors!';
return $erreurs;
}
Remarca: la utilització de _request() s’explica al lloc programmer.spip.org
La funció verificar retorna una llista de camps amb errors, amb el missatge d’error corresponent a cada camp.
En aquest estadi, no veureu cap diferència si proveu el formulari: efectivament, el vostre formulari contact.html no mostra els errors. L’heu de completar tal i com segueix:
[<p class='formulaire_erreur'>(#ENV*{message_erreur})</p>]
<form action='#ENV{action}' method='post'>
#ACTION_FORMULAIRE{#ENV{action}}
<label>El vostre correu electrònic</label>
[<span class='erreur'>(#ENV**{erreurs}|table_valeur{email})</span>]
<input type='text' name='email' value='#ENV{email}' />
<br />
<label>El vostre missatge</label>
[<span class='erreur'>(#ENV**{erreurs}|table_valeur{message})</span>]
<textarea name='message'>#ENV{message}</textarea>
<input type='submit' name='ok' value='ok' />
</form>
Fixeu-vos bé:
- la visualització d’un missatge d’error general retornat per la funció verificar
[<p class='reponse_formulaire reponse_formulaire_erreur'>(#ENV*{message_erreur})</p>] - els missatges d’error al davant de cada camp:
[<span class='erreur_message'>(#ENV**{erreurs}|table_valeur{email})</span>]
Ara podeu provar el vostre formulari introduint-hi un correu electrònic erroni o deixant el camp buit: el vostre formulari ja comença a interactuar amb l’internauta!
Etapa 4: tractar !
Quan la funció verificar ja no retorna cap error, SPIP crida automàticament la funció tractar corresponent. Declarem aquesta funció formulaires_contact_traiter_dist (sempre a dins del fitxer contact.php) i fem-li enviar un correu electrònic a l’administrador de la Web:
function formulaires_contact_traiter_dist(){
$envoyer_mail = charger_fonction('envoyer_mail','inc');
$email_to = $GLOBALS['meta']['email_webmaster'];
$email_from = _request('email');
$sujet = 'Formulaire de contact';
$message = _request('message');
$envoyer_mail($email_to,$sujet,$message,$email_from);
return array('message_ok'=>'El vostre missatge s'ha rebut correctament. Ben aviat rebreu una resposta!');
}
Fixeu-vos que la funció tractar no fa cap verificació: ja s’han fet totes prèviament (a la funció verificar). La funció tractar només es crida quan no hi ha cap error.
La funció tractar retorna un missatge d’èxit, « message_ok », a dins d’una taula. Com amb els missatges d’error, cal completar el nostre formulari per tal que pugui mostrar aquests missatge tal i com segueix:
[<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>El vostre correu electrònic</label>
[<span class='erreur'>(#ENV**{erreurs}|table_valeur{email})</span>]
<input type='text' name='email' value='#ENV{email}' />
<br />
<label>El vostre missatge</label>
[<span class='erreur'>(#ENV**{erreurs}|table_valeur{message})</span>]
<textarea name='message'>#ENV{message}</textarea>
<input type='submit' name='ok' value='ok' />
</form>
]
Fixeu-vos bé:
- la visualització d’un missatge d’èxit al principi
[<p class="formulaire_message">(#ENV*{message_ok})</p>] - la visualització condicional del formulari d’entrada de dades en funció de #EDITABLE: després de l’entrada, en general resulta més clar per l’internauta de no tornar a mostrar el formulari complert sinó només el missatge d’èxit. #EDITABLE serveix per això.
S’ha acabat! Ja podeu utilitzar el vostre formulari de contacte.
El bonus
Voleu que la interacció entre el vostre formulari i l’internauta sigui més ràpida i no passi per tornar a carregar completament la pàgina a cada error o durant la validació?
És necessari que el vostre formulari estigui implementat en AJAX. Habitualment és aquí on hi ha la dificultat. Aquest tipus d’implementació resulta sovint llarga i laboriosa. Però és molt més simple a SPIP, pel formalisme CVT, que fa que ens beneficiem dels mecanismes automatitzats entre les que hi ha l’ajaxisació dels vostres formularis.
En tindreu prou situant el vostre formulari a dins d’un div dotat de la class ajax:
<div class='ajax'>
#FORMULAIRE_CONTACT
</div>
I això és tot !
Per anar més enllà
- Aquest exemple simple no ens produirà un formulari bonic. Si volem un resultat més estètic, semàntic i accessible, utilitzeu les recomanacions d’estructures de Estructura HTML dels formularis d’SPIP en tots els vostres formularis SPIP
- Saber-ho tot sobre la funció charger(): La funció charger() dels formularis CVT
- Saber-ho tot sobre la funció verifier() : La funció verifier() dels formulaires CVT
- Tot sobre la funció traiter() : La funció traiter() dels formularis CVT