====== Résolution d'une issue 1 : #38 ======
===== Description de l'issue =====
==== Lien ====
https://framagit.org/framasoft/framadate/issues/38

==== Texte ====
**//Collecter les adresses emails des sondés//**\\
//Je trouverai interessant d'avoir la possibilité pour l'administrateur d'un sondage de collecter les adresses mail des sondés (visibles uniquement sur le formulaire admin). Un peu comme le nom/pseudo, mais cachés au sondés, donc. Afin de faciliter la vie de l'administrateur en cloture de sondage : parfois, on envoie un sondage à 200 personnes. Et on ne souhaite recontacter que les 20 qui ont répondu "OK". \\

C'était à la base une demande de Mozilla.//

==== Justification du choix ====
Il s'agit d'abord d'une demande fréquente au sein des utilisateurs de Framadate. Par ailleurs, cette modification ferait de Framadate un concurrent de taille face à Doodle où cette fonctionnalité est payante.\\
J'ai également choisi cette issue car elle me permettait de travailler sur presque tous les niveaux du projet (base de données, classes, fichiers ''.php'', fichiers ''.tpl'' et fichiers ''.js'').

===== Solution apportée : Version 1 =====
==== Itération 1 : Ajout de la collecte du mail dans le formulaire de sondage ====
=== Modification de la BDD ===
  * Ajout d'un fichier de migration dans le répertoire ''framadate/app/classes/Framadate/Migration'' pour ajouter le nouvel attribut ''mail'' à la table ''vote(poll_id, name, choices, uniqId)'' dans la base de données
  * Ajout d'un appel à ce fichier de migration dans ''/framadate/admin/migration.php''

=== Modification de la classe VoteRepository ===
  * MAJ de la méthode ''insert($poll_id, $name, $choices, $token)''
  * MAJ de la méthode ''update($poll_id, $vote_id, $name, $choices)''

=== Modification de la classe PollService ===
  * MAJ de la méthode ''updateVote($poll_id, $vote_id, $name, $choices, $slot_hash)''
  * MAJ de la méthode ''addVote($poll_id, $name, $choices, $slot_hash)''
  * MAJ de la méthode ''splitVote($votes)''

=== Modification des fichiers studs.php et adminstuds.php ===
  * MAJ des appels à ''updateVote'' et ''addVote''

=== Modification des templates vote_table_date.tpl et vote_table_classic.tpl ===
  * Création du nouveau champ

=== Visualisation de l'itération 1 ===
  * Pour un sondage de type //date// (côté //admin// et côté //user//)
{{ :txs:framadate-p18:justineissue1:table_vote_date_admin.png?530 | Table des vote côté admin (date)}} {{ :txs:framadate-p18:justineissue1:table_vote_date_user.png?530 | Table des vote côté user (date)}}
  * Pour un sondage de type //classic// (côté //admin// et côté //user//)
{{ :txs:framadate-p18:justineissue1:table_vote_classic_admin.png?530 |Table des vote côté admin (classic)}} {{ :txs:framadate-p18:justineissue1:table_vote_classic_user.png?530 | Table des vote côté user (classic)}}  

==== Itération 2 : Implémentation d'une fonctionnalité admin permettant la collecte des mails ====
=== Modification des templates ''vote_table_date.tpl'' et ''vote_table_classic.tpl'' ===
  * Ajout d'un bouton //enveloppe// associé à chaque colonne

=== Modification du fichier adminstuds.tpl ===
  * Ajout d'un traitement lorsqu'on clique sur le bouton //enveloppe// d'une colonne : récupération des adresses mails renseignées dans des tableaux de chaînes de caractères
  * Transmission de ces tableaux à ''$smarty'' et appel du nouveau fichier ''display_mails.tpl''

=== Ajout d'un template display_mails.tpl ===
  * Affichage des adresses mails transmises

=== Visualisation de l'itération 2 ===
  * Icône //enveloppe// pour un sondage de type //date// et pour un sondage de type //classic//
{{ :txs:framadate-p18:justineissue1:collect_mail_date.png?530 | Table des vote côté admin (date)}} {{ :txs:framadate-p18:justineissue1:collect_mail_classic.png?530 | Table des vote côté admin (classic)}}
  * Exemple d'affichage de collecte de mails pour un sondage (correspond à l'option //Avatar// du sondage //classic//)
{{ :txs:framadate-p18:justineissue1:collect_mail_classic_ej.png?530 | Exemple d'affichage de collecte de mails}}

===== Solution apportée : Version 2 =====
Afin que la première version soit intégrable dans le code source de Framadate, il est nécessaire de passer la collecte de mail comme une fonctionnalité optionnelle : à la création d'un sondage, l'administrateur choisit (ou non) de collecter les adresses mails des sondés.

=== Modification de la BDD ===
  * Ajout d'un fichier de migration pour ajouter le nouvel attribut ''collect_users_mail'' dans la table ''poll(id, admin_id, title, description, admin_name, admin_mail, end_date, format, editable, receiveNewVotes, receiveNewComments, hidden, password_hash, results_publicly_visible, ValueMax)''
  * Ajout d'un appel à ce fichier de migration dans ''/framadate/admin/migration.php''
=== Modifications des classes Form et PollRepository ===
  * Ajout d'un attribut ''collect_users_mail'' à la classe ''Form''
  * MAJ de la méthode ''insertPoll'' de la classe ''PollRepository''
=== Passage de la collecte de mail en fonctionnalité admin ===
  * Sur la création d'un sondage : ajout d'un paramètre optionnel (modification des fichiers ''create_poll.php'' et ''create_poll.tpl'')
  * Sur l'administration d'un sondage : ajout du paramètre dans les infos (modification du fichier ''poll_info.tpl'')
  * Sur le vote : affichage ou non du champ ''mail'' et des boutons ''enveloppe'' (modification des fichiers ''vote_table_date.tpl'' et ''vote_table_classic.tpl''
=== Passage des champs mail en ''required'' ===
(La saisie devient obligatoire si la collecte de mail est activée.)
=== Ajout d'avertissements lorsque la collecte de mail est active et que les votes sont modifiables par tous (réponse à la problématique en V1) ===
  * Lors de la création du sondage (modification des fichiers ''create_poll.php'', ''create_poll.tpl'' et ''create_poll.js'')
  * Lors de l'ajout d'un nouveau vote (modification des fichiers ''vote_table_date.tpl'' et ''vote_table_classic.tpl'')

=== Visualisation de la version 2 ===
  * Affichage du nouveau paramètre optionnel dans la création d'un sondage
{{ :txs:framadate-p18:justineissue1:creation.png?530 | Nouveau paramètre optionnel dans la création d'un sondage}}
  * Affichage du nouveau paramètre dans les infos d'un sondage
{{ :txs:framadate-p18:justineissue1:info.png?530 | Nouveau paramètre affiché dans les infos d'un sondage}}
  * Avertissement lors de la création d'un sondage
{{ :txs:framadate-p18:justineissue1:avertissement_creation.png?530 | Avertissement lors de la création d'un sondage}}
  * Avertissement lors du vote
{{ :txs:framadate-p18:justineissue1:avertissement_vote.png?530 | Avertissement lors du vote}}


===== Merge request =====
https://framagit.org/framasoft/framadate/merge_requests/266