Cadre d'application FormulaireCourriel

Un article de ScriptdigitalWiki.

Jump to: navigation, search

Sommaire

Introduction

FormulaireCourriel est un cadre d'application extensible, qui permet de créer et de gérer à l'aide de gabarits, des formulaires Web servant à communiquer - via courriel - à des destinataires préalablement enregistrés dans un fichier de configuration.

FormulaireCourriel nécessite l'utilisation du cadre d'application Contrôle Accès, ce dernier lui permettant de déterminer entre autres l'expéditeur qui ne peut être que de trois types : apprenant, formateur en encadrement, formateur en exploration.

On devra utiliser des feuilles de style si l'on veut spécifier un style propre à un cours. Autrement, les gabarits sont les mêmes à l'intérieur d'une langue. Ceux-ci sont articulés sur la logique expéditeur-destinataire. Les gabarits existants sont les suivants (note: "utilisateur" peut être un apprenant ou un formateur):

  • Apprenant - Formateur
  • Formateur - Apprenant
  • Formateur - Chargé de projets
  • Utilisateur - Service à la clientèle
  • Utilisateur - Soutien technique

On peut facilement ajouter à FormulaireCourriel de nouveaux destinataires et de nouveaux formulaires. La façon de procéder est expliquée dans une section subséquente.

Après avoir envoyé le formulaire, FormulaireCourriel fera les actions suivantes:

  • Envoie le courriel
  • Insere dans le journal le message ainsi que de nombreux autres éléments
  • Affiche soit le gabarit de réussite ou d'échec de l'envoi du courriel

Des routines de rappel logées dans le répertoire /ext/formulairecourriel peuvent modifier ces comportements. Les routines de rappels peuvent être appelées avant ou après la soumission du formulaire.

Configuration

Contrôle Accès

Il faut que le cours qui se servira des formulaires soit enregistré auprès de Contrôle Accès.

Destinataires

Les destinataires sont définis dans le fichier de configuration global de ServicesWeb.

// adresses MEMBRE
$FORMULAIRECOURRIEL['MEMBRES']['serviceclientele']['info']['courriel']      = 'info@edusofad.com';
$FORMULAIRECOURRIEL['MEMBRES']['soutientech']['tech']['courriel']           = 'tech@edusofad,com';
$FORMULAIRECOURRIEL['MEMBRES']['chargedeprojets']['labrecque']['courriel']  = 'labrecquejs@sofad.qc.ca';
$FORMULAIRECOURRIEL['MEMBRES']['chargedeprojets']['labrecque']['prenom']    = 'Jean-Simon';
$FORMULAIRECOURRIEL['MEMBRES']['chargedeprojets']['labrecque']['nom']       = 'Labrecque';
$FORMULAIRECOURRIEL['MEMBRES']['chargedeprojets']['decarie']['courriel']    = 'emm@scriptdigital.com';
$FORMULAIRECOURRIEL['MEMBRES']['chargedeprojets']['decarie']['prenom']      = 'Emmanuel';
$FORMULAIRECOURRIEL['MEMBRES']['chargedeprojets']['decarie']['nom']         = 'Décarie';


Chaque destinataire a au moins une propriété qui est le courriel, et peut optionnellement avoir deux autres propriétés, prénom et nom.

Fichier

/servicesweb/configurations/global.inc

Catégories

On peut définir une liste de catégorie particulière pour un destinataire précis. Cette liste alimentera un menu déroulant qui permettra de choisir l'une de ces catégories. Cette catégorie sera enregistrée dans la banque de données, et par le biais d'une macro, pourra apparaître dans le texte envoyé par courriel.

Il faut tout d'abord définir un format pour la balise <option> du menu déroulant.

// format menu deroulant
$FORMULAIRECOURRIEL['CATEGORIES']['format']['<option>'] = '<option value="#VALEUR#">#NOM#</option>';


Ensuite, on créé la liste des catégories ainsi:

// version en - elem gauche insere dans bd , elem droit affiche dans la page web
$FORMULAIRECOURRIEL['MEMBRES']['soutientech']['tech']['categories']['en']   = 
                                        array ( '0'                         => '',
                                                'Affichage/Mise en page'    => 'Display/Layout',
                                                'Audio'                     => 'Audio',
                                                'Connexion'                 => 'Connexion',
                                                'Fichier à télécharger'     => 'Fichier à télécharger',
                                                'Flash'                     => 'Flash',
                                                'Hyperlien'                 => 'Hyperlien',
                                                'Image'                     => 'Image',
                                                'Navigation'                => 'Navigation',
                                                'Programmation'             => 'Programmation',
                                                'Vidéo'                     => 'Video',
                                                'Autre'                     => 'Other');

Fichier

/servicesweb/configurations/global.inc

Types acceptés des fichiers téléchargés vers le serveur

Par précaution, seul un fichier dont le type sera déterminé dans le fichier de configuration sera accepté en téléchargement. D'autre part, il faut aussi spécifier un répertoire libre en écriture/lecture/destruction qui recevra les fichiers temporaires téléchargés vers le serveur et qui sont joints en annexe dans les courriels.

// media type - type de fichiers valides pour telechargement
$FORMULAIRECOURRIEL['MEDIA-TYPE']['valide']  = array (   
                                                                            'doc',
                                                                            'gif',
                                                                            'gif',
                                                                            'html',
                                                                            'jpeg',
                                                                            'jpg',
                                                                            'mov',
                                                                            'mp3',
                                                                            'mp4',
                                                                            'pdf',
                                                                            'rtf',
                                                                            'sit',
                                                                            'swf',
                                                                            'tar',
                                                                            'txt',
                                                                            'xml',
                                                                            'xsl',
                                                                            'zip',
                                                                            );

$repertoireTmp = 'I:\developpement\servicesweb\tmp';

Fichier

/servicesweb/configurations/global.inc

Banque de données

La banque de données enregistre les messages qui sont envoyés, ainsi que plusieurs éléments relatifs à cet évènement. La banque de données enregistrera en outre les erreurs si le courriel n'a pu être envoyé. Cela concerne uniquement les transmissions qui ne sont pas faites entre l'apprenant et le formateur.

Le schéma de la banque de données est le suivant.

CREATE TABLE formulaire_courriel (
  message_id SMALLINT(5) UNSIGNED NOT NULL AUTO_INCREMENT,
  PRIMARY KEY  (message_id),
  message_texte TEXT NOT NULL DEFAULT '',
  message_copie_expediteur TINYINT(3) UNSIGNED NOT NULL DEFAULT '0',
  message_fichier_joint VARCHAR(100) NOT NULL DEFAULT '',
  message_categorie VARCHAR(150) NOT NULL DEFAULT '',
  message_categorie_autre VARCHAR(150) NOT NULL DEFAULT '',
  expediteur_controleacces_id SMALLINT(5) UNSIGNED NULL,
  expediteur_courriel VARCHAR(40) NOT NULL DEFAULT '',
  expediteur_environnement TEXT NOT NULL DEFAULT '',
  expediteur_prenom VARCHAR(40) NOT NULL DEFAULT '',
  expediteur_nom VARCHAR(40) NOT NULL DEFAULT '',
  expediteur_type VARCHAR(40) NOT NULL DEFAULT '',
  destinataire_courriel VARCHAR(40) NOT NULL DEFAULT '',
  destinataire_prenom VARCHAR(40) NOT NULL DEFAULT '',
  destinataire_nom VARCHAR(40) NOT NULL DEFAULT '',
  destinataire_type VARCHAR(40) NOT NULL DEFAULT '',
  courriel_erreur VARCHAR(100) NOT NULL DEFAULT '',
  utilisateur_statut VARCHAR(100) NOT NULL DEFAULT '',
  date timestamp(14) NULL,
  lu DATETIME NULL,
  traite DATETIME NULL
)

Fichier

/lib/formulairecourriel/formulaireCourriel.sql

Comment modifier les gabarits de FormulaireCourriel

Gabarits

Les gabarits sont identifiés par deux éléments, l'expéditeur et le destinataire.

Les gabarits sont entreposés dans des répertoires dont la hiérarchie informe FormulaireCourriel. Cette hiérarchie a le format suivant:

  • Expéditeur
    • Destinataire
      • destinataire-courriel-HTML.inc
      • destinataire-courriel-texte.inc
      • destinataire-form.inc
      • destinataire-msg-nok.inc
      • destinataire-msg-ok.inc

Voici par exemple, la hiérarchie pour Apprenant-Formateur:

  • apprenant-expediteur
    • formateur-destinataire
      • formateur-courriel-HTML.inc
      • formateur-courriel-texte.inc
      • formateur-form.inc
      • formateur-msg-nok.inc
      • formateur-msg-ok.inc

Les gabarits sont composés de 5 matrices qui portent des noms canoniques (nous verrons dans la section Comment ajouter un formulaire l'importance de ces 5 désignations)

  • courriel-HTML.inc
  • courriel-texte.inc
  • form.inc
  • msg-nok.inc
  • msg-ok.inc

Chaque matrice est le support visible pour un évènement de FormulaireCourriel, par exemple, afficher le formulaire (form.inc), ou produire le texte et le HTML pour le message envoyé par courriel (courriel-texte.inc, courriel-HTML.inc), ou encore afficher une réponse positive (msg-ok.inc) ou négative (msg-ok.inc) selon la réussite ou l'échec de l'envoi du courriel.

Chaque matrice contient des {macros} qui permettent entre autres d'afficher certaines propriétés (courriel, nom, prénom) de l'expéditeur et du destinataire.

#################################################################
# formateur-courriel-texte.inc
# $Date$ - $RCSfile$ - $Revision$
#################################################################
#
# NOTES: les lignes commençant par '#' ou ';' seront eliminees du fichier final
; Config_SujetCourriel=[Objet : {MACRO_cours_id} - Message]


À : {MACRO_formateur_prenom} {MACRO_formateur_nom} ({MACRO_formateur_courriel}) 
Objet : {MACRO_cours_id} - Message 
De : {MACRO_apprenant_prenom} {MACRO_apprenant_nom} ({MACRO_apprenant_courriel}) 
Date : {MACRO_date}
 
Message de l'apprenant:

{MACRO_message};

Fichier

/sites/formulairescourriels/gabarits_en
/sites/formulairescourriels/gabarits_fr

Macros pour les gabarits

Voici un tableau définissant les macros utilisées dans les gabarits. Les macros liées à l'apprenant et au formateur ne doivent être utilisées que si l'expéditeur est un apprenant ou un formateur et que si le destinataire est un apprenant ou un formateur.

{FORMULAIRE_ATTRIBUT_ACTION}Destiné au programmeur: maintien les arguments dans l'url pour l'attribut action de la balise <form>
{MACRO_apprenant_courriel}Courriel de l'apprenant
{MACRO_apprenant_nom}Nom de l'apprenant
{MACRO_apprenant_prenom}Prénom de l'apprenant
{MACRO_categorie_autre}La catégorie autre saisie par l'utilisateur
{MACRO_categorie}La catégorie choisie par l'utilisateur
{MACRO_courriel_erreur}Erreur suite à l'échec du courriel
{MACRO_cours_id}Sigle du cours
{MACRO_cours_nom}Nom du cours
{MACRO_date}Date actuelle
{MACRO_destinataire_courriel}Courriel du destinataire
{MACRO_destinataire_nom}Nom du destinataire
{MACRO_destinataire_prenom}Prénom du destinataire
{MACRO_env_HTTP_HOST}Hôte du site
{MACRO_env_HTTP_REFERER}Page vue avant la soumission du formulaire
{MACRO_env_HTTP_USER_AGENT}Le nom du fureteur employé par l'utilisateur
{MACRO_env_LOCAL_ADDR}Adresse IP de l'utilisateur
{MACRO_env_PATH_INFO}Chemin sur le serveur menant à la page vue avant la soumission du formulaire
{MACRO_env_REMOTE_HOST}Adresse IP du serveur
{MACRO_env_SERVER_NAME}Nom du serveur
{MACRO_env_SERVER_PORT}Port
{MACRO_env_SERVER_SOFTWARE}Nom du logiciel du serveur Web
{MACRO_formateur_courriel}Courriel du formateur
{MACRO_formateur_nom}Nom du formateur
{MACRO_formateur_prenom}Prénom du formateur
{MACRO_menuderoulant_categories}Menu déroulant des catégories du formulaire
{MACRO_message}Message soumis dans le formulaire
{MACRO_msg_erreur_retroaction}Message d'erreur suite à la soumission du formulaire
{MACRO_utilisateur_courriel}Courriel de l'utilisateur/expediteur
{MACRO_utilisateur_nom}Nom de l'utilisateur/expéditeur
{MACRO_utilisateur_prenom}Prénom de l'utilisateur/expéditeur
{MACRO_utilisateur_statut}Statut de l'utilisateur/expéditeur: apprenant, ou formateur en encadrement, ou formateur en exploration

Éléments d'interface Web

Il y a six éléments d'interface Web qui peuvent être employés pour construire un formulaire. Ces éléments doivent être à l'intérieur de la balise <form> suivante.

<form name="formulaire" method="post" action="{FORMULAIRE_ATTRIBUT_ACTION}" enctype="multipart/form-data">
    <input name='formulaire-action' type='hidden' value='envoyer' />
    <!--Éléments d'interface Web-->
</form>
 

Il est important de ne pas changer les noms de ces interfaces. Si un élément d'interface est présent, il sera automatiquement traité par le formulaire. Au minimum, le formulaire doit afficher l'élément d'interface du message et celui du bouton de soumission du formulaire.

message

Affiche l'interface Web pour saisir un message.

<textarea name='message' rows='8' cols='40'></textarea>


fichierjoint

Affiche un bouton permettant de télécharger au serveur un fichier.

input name='fichierjoint' type='file' />

copiermessage

Affiche un bouton radio à cocher si l'on veut avoir une copie du message.


<input name='copiermessage' type='checkbox' value='1' />

categorie

Menu déroulant les catégories.

<select name='categorie'>
    {MACRO_menuderoulant_categories}
</select>

categorie_autre

Champ permettant de saisir une catégorie ne figurant pas dans les catégories du menu déroulant.

<input name='categorie_autre' type='text' size='40' maxlength='100' />


bouton_envoyer

Bouton pour soumettre le formulaire.

<input name='bouton_envoyer' type='submit' value='Envoyer' />

Routines de rappel

On peut installer dans le répertoire /ext/formulairecourriel des routines de rappel qui peuvent être appelées avant ou après le formulaire.

Par exemple, dans le cas où l'apprenant est l'expéditeur et le destinataire est le formateur, une routine de rappel est appelée avant la soumission du formulaire pour empêcher qu'un apprenant qui n'est pas appareillé avec un formateur puisse se servir du formulaire courriel. Cette routine de rappel affiche alors un gabarit prévenant l'usager du problème (voir l'exemple suivant: /ext/formulairecourriel/preformulaire/apprenant-formateur.inc).

C'est la hiérarchie du répertoire ainsi que le nom du formulaire qui informe FormulaireCourriel que ce dernier doit appeler une routine de rappel. En voici un exemple dans le cas de routines de rappel qui sont appelées avant l'affichage du formulaire. Ici, la routine apprenant-formateur.inc sera appelée avant l'affichage du formulaire si l'expéditeur est un apprenant et si le destinataire est un formateur. Si on veut une routine de rappel après la soumission du formulaire, il faut reproduire la même chose mais en substituant à /preformulaire le répertoire /postformulaire.

  • /ext
    • /formulairecourriel
      • /preformulaire
        • apprenant-formateur.inc
        • formateur-chargedeprojets.inc

Répertoire

/ext/formulairecourriel/preformulaire
/ext/formulairecourriel/postformulaire

Comment ajouter un formulaire à un cours

Cela se passe en trois étapes.

  • Créer la page affichant le formulaire
  • Construire l'URL de la page affichant le formulaire
  • Configurer les propriétés du destinataire dans le fichier de configuration si le destinataire n'est pas un apprenant/formateur


Page affichant le formulaire

Pour que FormulaireCourriel puisse fonctionner, il faut que les environnements et Contrôle Accès soient déclarés. Un exemple (à ajuster dans d'autres cas pour le chemin relatif vers le fichier de configuration principal global.inc de ServicesWeb) est cette déclaration qu'il faut mettre dans la page dans laquelle sera affiché le formulaire à l'intérieur d'un cours spécifique.

include_once ('../../configurations/global.inc'); // fichier de configuration commun de ServicesWeb
include_once ($ENV_SERVICESWEB['conf_edusofad']); // rendra visible $ENV_SOFAD et $ENV_CONTROLEACCES
include_once ($ENV_SOFAD['controleAcces_contr_inc']); // ControleAcces
include_once ($ENV_SERVICESWEB['formulaireCourriel_contr_inc']); // FormulaireCourriel

Une fois que cela est fait, on pourra se servir de la macro $MACRO['FormulairesCourriels']['gabarit'].

<?php echo $MACRO['FormulairesCourriels']['gabarit'] ?>

C'est cette macro qui affichera les gabarits du formulaire et des réponses positives ou négatives à l'envoi du courriel.

Comment construire l'URL pointant vers le formulaire

On ne peut pas pointer simplement pointer vers la page affichant les formulaires, car c'est la même page (en principe) qui affichera tous les types de formulaires définis par l'expéditeur (apprenant/formateur) et le destinataire (apprenant/formateur/chargé de projets/service à la clientèle/soutien technique). L'URL informe FormulaireCourriel et il est important de comprendre le comment de la chose.

En voici un exemple où l'apprenant est l'expéditeur et le formateur est le destinataire:

formulaire.php?exp=apprenant&dest=formateur


Un autre exemple où c'est soit l'apprenant ou le formateur qui est l'expéditeur et le chargé de projets qui est le destinataire:

formulaire.php?exp=formateur&dest=chargedeprojets&adr=labrecque

Il y a trois éléments dont on peut se servir pour construire l'url.

  • exp=expediteurType -> obligatoire
  • dest=destinataireType-> obligatoire
  • <code>adr=adresseType -> facultatif si le destinataire est un apprenant ou un formateur

Configurer les propriétés du destinataire

Par defaut, on n'a pas besoin de modifier le fichier de configuration de ServicesWeb pour enregistrer comme membre de FormulaireCourriel les expediteurType et destinataireType qui sont des apprenants ou des formateurs.

Par contre, si le destinataire n'est pas un formateur ou un apprenant, il faut l'enregistrer dans le fichier de configuration:

$FORMULAIRECOURRIEL['MEMBRES']['chargedeprojets']['labrecque']['courriel']  = 'labrecquejs@example.org';
$FORMULAIRECOURRIEL['MEMBRES']['chargedeprojets']['labrecque']['prenom']    = 'Jean-Simon';
$FORMULAIRECOURRIEL['MEMBRES']['chargedeprojets']['labrecque']['nom']       = 'Labrecque';

Dans le tableau plus haut, chargedeprojets est le destinataireType, tandis que labrecque est l'adresseType qui permet de retrouver les trois propriétés du destinataire et qui sont traitées (courriel, nom, prénom).

Comment créer un nouveau formulaire

Pour créer un nouveau formulaire, il faut déterminer l'expéditeurType, le destinataireType et l'adresseType.

Par exemple, si on veut que l'expéditeur soit un apprenant, l'expéditeurType sera apprenant, tandis que pour le formateur, le destinataireType sera formateur. Si on est indifférent que l'expéditeur soit un apprenant ou un formateur, on utilisera comme expéditeurType utilisateur.

Une fois que l'expéditeurType est déterminé, il faut créer un nouvel destinataireType. Prenons l'exemple d'un destinataire qui serait responsable de la veille technologique et dont l'expéditeur est un utilisateur. On dira ici que l'expéditeurType est utilisateur et le destinataireType est veilletech. L'orthographe du destinataireType ne doit pas contenir de caractères accentués, ni espace.

Il faudra d'abord créer un dossier par langue dans le répertoire des gabarits. Les noms correspondent à ce qui sera passé comme argument dans l'url pointant vers le formulaire (voir plus haut). Il faut donc que l'orthographe puisse être valide comme argument dans une URL.

/utilisateur-veilletech

Dans ce dossier, il faudra inclure les 5 interfaces canoniques de la manière suivante:

/utilisateur-veilletech
	/veilletech-courriel-HTML.inc
	/veilletech-courriel-texte.inc
	/veilletech-form.inc
	/veilletech-msg-nok.inc
	/veilletech-msg-ok.inc

Après avoir édité les gabarits à sa convenance, il faudra aller dans le fichier de configuration principal de ServicesWeb et ajouter la configuration pour le nouveau destinataire (voir plus haut pour plus de détails).

$FORMULAIRECOURRIEL['MEMBRES']['veilletech']['otis']['courriel']  = 'otisy@sofad.qc.ca';
$FORMULAIRECOURRIEL['MEMBRES']['veilletech']['otis']['prenom']    = 'Yves';
$FORMULAIRECOURRIEL['MEMBRES']['veilletech']['otis']['nom']       = 'Otis';

Ensuite il ne suffit plus de créer la page affichant le formulaire (voir plus haut).

Et pour terminer, il faudra construire une URL pointant vers la page affichant le formulaire (voir plus haut pour plus de détails).

formulaire.php?adr=utilisateur&dest=veilletech&adr=otis

Si on désire avoir des comportements différents de ce qui est offert par défaut par FormulaireCourriel, il suffira d'utiliser les routines de rappel (voir plus haut).