# gamuMail > formulaire d'envoi de messages configurables ## Il gere nativement : - Pour - Cc en meta : **gamumail/mail_cc** - Cci en en meta : **gamumail/mail_cci** - Cci en globals []: `$GLOBALS['gamuza_mail_cci'] = ['sarl.gamuza@gmail.com'];` - Sujet - Texte - Les documents attachés au modèle (cf ci-dessous) - une liste de pdf (il faut le plugin spipdf) ![interface](doc/interface.png "interface") ## Il gere des modèles de contenu pour : - Sujet - Texte - ID documents joints (spip_documents) --- - Chaque modèle à un identifiant textuel : **slug** qui doit etre unique. Il ne peut etre créé / modifié QUE par les webmestres - Pour gerer ses modèles, il faut se rendre sur la page : `?page=configuration_mails` ![configuration](doc/configuration.png "Exemple de configuration") ## Personnalisation du formulaire d'envoi ### Dans le html On peut ajouter des documents via un fichier du type : **gamumail/SLUG_fichier.html** SLUG doit etre remplacé par le nom du slug du modèle > **/!\ Le name doit etre Tid_doc** > > ex de fichier : ```html

Fichiers attachés au séjour

 ``` 3 branchements possibles : - gamumail/SLUG_debutform.html -> au début du form - gamumail/SLUG_soustexte.html -> sous le contenu du mail, avant les pièces jointes - gamumail/SLUG_fichiers.html -> à la fin du formulaire On peut ajouter un fichier pour l'autocomplete des emails - gamumail/SLUG_autocomplete_emails.html - gamumail/autocomplete_emails.html ```html ``` ### aide à la rédaction du contenu: - le fichier **gamumail/remplacement_slugs.html** s'affiche en bas de la page de configuration des modèles **inclure/gamumail_config.html** et du formulaire d'envoi **formulaires/gamumail.html** : il permet de lister les remplacements effectués pour **tous les modèles** qui sont : - les génériques fournis par Gamumail par la fonction `inc_gamumail_remplacements_dist()` du fichier `inc/gamumail_remplacements.php` - ceux fournis par les plugins via le pipeline **remplacement_slugs** (cf ci-dessous) - pour documenter les remplacements (pied de la page gamumail_config.html), chaque plugin doit renseigner ses remplacements dans l'array global `$GLOBALS['remplacements_gamumail']` Exemple dans un fichier `prefixe_fonctions.php` : ```php $GLOBALS['remplacements_gamumail']['@@num_facture@@'] = 'numéro de la facture'; ``` - une page de test des slugs est fournie à l'URL **...?page=test_slug&slug=mail_libre&dest=27** ### exemple de page d'envoi de mail en choisissant un slug parmi ceux existant : ```html [(#AUTORISER{modifier,souscripteur,#ENV{id_auteur}}|sinon_interdire_acces)]

Envoyer un mail à [(#PRENOM|ucfirst) ][(#NOM|ucfirst)]

``` ### Dans le php #### 1. Appel du formulaire > Args du formulaire : ```php /** * formulaire générique pour envoyer des mails avec pieces attachés * * @param string $slug modele du mail a charger * @param string $destinataires = adresses mails et id_auteurs séparées par , ou en array * si un des destinataire est au format numérique, on considère que c'est un id_auteur et on va choper son mail dans spip_auteurs * @param array $Tclient = un ou plusieurs mails de destinataires sortis d'une table objet spécifique * de la forme []['objet' => 'app_client', 'id_objet' => 3, 'champ' => 'email'] ou ['objet' => 'app_client', 'id_objet' => 3, 'champ' => 'email'] * @param array $Tpdf = un ou plusieurs fichiers PDF générés par spiPDF (le contexte permet la personnalisation du contenu) * []['fichier' => 'pdf_facture', 'nom' => 'facture_123', 'contexte' => ['id_app_facture' => 3]] ou ['fichier' => 'pdf_facture', 'nom' => 'facture_123', 'contexte' => ['id_app_facture' => 3]] * @param string $redirect * @param array $options = un gros fourre-tout sous forme d'un array * utilisé en particulier par les inclure HTML de gamumail/#SLUG_soustexte et gamumail/#SLUG_fichiers * * @return array $valeurs */ function formulaires_gamumail_charger_dist($slug, $auteur = 0, $Tclient = [], $Tpdf = [], $redirect = '', $options = []){ } ``` #### argument $slug "no_gamumail" Si $slug à pour valeur **no_gamumail** alors l'envoi est annulé Exemple d'option à insérer dans un select sélecteur de slug : ```html ``` #### argument Tclient l'Argument $Tclient est utilisé pour récupérer des emails dans un ou X autres Objets SPIP #### argument Tpdf : attacher des PDF avec contenu dynamique - exemple d'appel pour 1 fichier PDF avec son contexte : ```html [(#FORMULAIRE_GAMUMAIL{ #ENV{slug}, #ENV{email}, '', #ARRAY{ fichier,pdf_guide, nom,Fiche_guide, contexte,#ARRAY{ id_article,#ENV{id_article}, type_guide,#ENV{type_guide,guide} } }, #ENV{redirect}, #ARRAY{ id_auteur,#ENV{id_auteur} } })] ``` le fichier PDF sera généré par SPIPDF avec l'URL suivante : `...spip.php?page=spipdf&spipdf=pdf_guide&id_article=1838&type_guide=guide` - exemple d'appel pour 2 fichiers PDF générés par le même squelette (pdf_guide.html) mais avec chacun leur contexte : ```html [(#FORMULAIRE_GAMUMAIL{ #ENV{slug}, #ENV{email}, '', #ARRAY{ 0,#ARRAY{ fichier,pdf_guide, nom,Fiche_guide, contexte,#ARRAY{ id_article,#ENV{id_article}, type_guide,guide, } }, 1,#ARRAY{ fichier,pdf_guide, nom,Fiche_guide_renfort, contexte,#ARRAY{ id_article,#ENV{id_article}, type_guide,guide_renfort, } } }, #ENV{redirect}, #ARRAY{ id_auteur,#ENV{id_auteur} } })] ``` /!\ en cas de plusieurs PDF : - il faut une _clé unique_ pour chaque #ARRAY (0, 1, 2... est une bonne solution) - dans l'#ARRAY contexte il faut que le dernier élément soit suivi d'une virgule ou d'une accolade fermante #### 2. surcharges de chaque étape: charger / vérifier / traiter Pour chaque étape, on peut modifier l'Array de sortie : - charger -> $valeurs - verifier -> $erreurs - traiter -> $corps (array du message envoyé à facteur) Voir **gamumail_fonctions.php** pour les arguments des fonctions de surcharge + exemples Pour cela, il faut creer une fonction du type (qui utilise les memes arg que les fonctions CVT + premier arg l'Array que l'on veut modifier) La surcharge pour tous les slugs (`gamumail_tous_...`) précède celle spécifique par slug : on peut donc utiliser les 2 successivement. Syntaxe : - pour charger pour tous les slugs : **gamumail/tous_charger.php** (fonction `gamumail_tous_charger()`) - pour charger spécifique d'un slug : **gamumail/NOM_SLUG_charger.php** avec une fonction : ```php function gamumail_NOM_SLUG_charger($valeurs, $options = []){ return $valeurs; } ``` - pour verifier pour tous les slugs : **gamumail/tous_verifier.php** (fonction `gamumail_tous_verifier()`) - pour verifier spécifique d'un slug : **gamumail/NOM_SLUG_verifier.php** avec une fonction : ```php function gamumail_NOM_SLUG_verifier($erreurs, $options = []){ return $erreurs; } ``` - pour traiter pour tous les slugs : **gamumail/tous_traiter.php** (fonction `gamumail_tous_traiter()`) - pour traiter spécifique d'un slug : **gamumail/NOM_SLUG_traiter.php** avec une fonction par ex: ```php function gamumail_NOM_SLUG_traiter($corps, $options = []){ if (array_key_exists('id_article', $options)) { $htmlAdd = ''; $texteAdd = ''; $id_article = intval($options['id_article']); $htmlAdd = recuperer_fond('gamumail/traiter_contrat_resa', ['id_article' => $id_article]); if (!empty($htmlAdd)) { include_spip('classes/facteur'); $html = $corps['html']; $html = str_replace('@@pieces_jointes@@', $htmlAdd, $html); $texte = facteur_mail_html2text($html); $corps['html'] = $html; $corps['texte'] = $texte; } } return $corps; } ``` #### 3. Pipeline remplacements_slug pour le traitement du contenu des messages Pour les remplacements des @@ et tout autre traitement du texte des mails on utilisera le pipeline **remplacements_slug** qui utilise les arguments suivants : ```php * @param array $flux données du pipeline : * $flux['data'] = $html * $flux['args']['slug'] = $slug * $flux['args']['destinataires'] = $destinataires * $flux['args']['options'] = $options * @return array $flux données du pipeline function PREFIX_remplacements_slug($flux){ include_spip('gamumail_fonctions'); // remplacements statiques if ($html = $flux['data']) { $html = gamumail_remplacer_modele('url_page_commandes', url_absolue(generer_url_public('historique_commandes')), $html); $html = gamumail_remplacer_modele('url_page_contrats', url_absolue(generer_url_public('mes_contrats')), $html); } // remplacements dynamiques /* * /!\ Attention, $flux['args'] peut etre un array cle -> valeur * sans passer par un sous tab $args comme ici */ if ($args = $flux['args']['args'] and $html = $flux['data'] ) { if (isset($args['url_attestation'])) { $html = gamumail_remplacer_modele('url_attestation', $args['url_attestation'], $html); } $flux['data'] = $html; } return $flux; } ``` #### 4. Pipeline post_gamumail_ok Ce pipeline est appelé si le retour de l'envoi du gamumail est OK. Il permet, par exemple, à Paybyurl d'aller modifier le champ date_paybyurl_envoye pour que la date d'envoi soit mise à jour. #### 5. Ajouter un header / footer dans le content html on peut définir un header / footer pour les messages : - gamumail/html_header.html => header pour tous les mails - gamumail/html_footer.html => footer pour tous les mails - gamumail/SLUG_html_header.html => pour les mails du modele SLUG - gamumail/SLUG_html_footer.html => pour les mails du modele SLUG #### 6. Utiliser l'inclure `` pour fermeture de la modale de gamumail - cet inclure est appelé au début de `formulaire/gamumail.html` : par défaut il est vide - un plugin peut arriver avec son fichier pour le surcharger afin de pouvoir intégrer du JS en fonction du message de retour `message_ok` du traiter de gamumail.php - dans `gamumail.php`, la fonction `gamumail_traiter` ajoute en fin du message de retour OK `message_ok` le suffixe `@@gamumail_ok` - il est donc possible de tester la présence de ce suffixe dans `message_ok` pour afficher du JS qui permet de refermer la modale dans laquelle est chargée gamumail mais aussi de faire la mise à jour de l'affichage d'un bloc ajax dans la page appelante. => voir le code en commentaire dans le fichier `inclure/fermer_modale` ## API d'envoi de mails utilisant les slugs ### fonction envoyer_gamumail() - exemple d'appel : ```php $fonction = charger_fonction('envoyer_gamumail','inc'); $options = [ 'debug' => false, 'options' => ['nb_parts' => intval(_request('nombre'))], 'pdfs' => [ [ 'fichier' => 'pdf_attestation_souscription', 'nom' => 'attestation_souscription_'.$id_souscription, 'contexte' => ['id_souscription' => $id_souscription] ], ], ]; $fonction(lire_config('souscriptions/slug_souscription_validation'), $Tdest, $options); ``` - arguments : ```php * @param string $slug * @param string|array $destinataires = adresses mails et id_auteur séparées par , ou en array * si un des destinataire est au format numérique, on considère que c'est un id_auteur et on va choper son mail dans spip_auteurs * @param array $options : * $options['debug' => true] pour afficher le $corps final sans envoyer le mail * $options['cci' => true] pour passer tous les destinataires en cci si il y en a plus qu'un * $options['args' => ['param_1' => 'valeur_1, 'param_2' => 'valeur_2', ...]] * $options['pdfs' => [...]] array des fichiers PDF générés à attacher dont les éléments peuvent être : * - soit un nom de squelette PDF * - soit un array avec 3 éléments (seul le 1er est obligatoire): * [ 'fichier' => 'squelette_PDF', * 'contexte' => ['parametre_url_1' => 'valeur_1', 'parametre_url_2' => 'valeur_2', ...] * 'nom' => 'nom_fichier_attache' ] ``` ## Slugs et @@ fournis pour surcharges facultatives de SPIP pour permettre l'envoi des mails en Gamumail plutôt que via notification ### slug `valider_inscription` : - message pour la validation de l'adresse mail lors de la création d'un compte avec le form `inscription` - à activer via une surcharge de `action_inscrire_auteur_dist()` : cf plugin **sq_collecte/sq_collecte_fonctions.php** - pour intégrer la définition du mot de passe dès l'inscription (sans le plugin inscription_motdepasse) + d'autres contrôles de l'inscription : - pour la saisie surcharge du HTML du form d'inscription : cf plugin **sq_collecte/formulaires/inscription.html** - pour les contrôles il faut surcharger `formulaires_inscription_verifier_dist()` : cf plugin **sq_collecte/sq_collecte_fonctions.php** ### slug `pass_oubli` - message pour le reset du mot de passe - à activer via une surcharge de `formulaires_oubli_traiter_dist()`: cf plugin **rocb/rocb_options.php** ## Outrepasser l'erreur de certificat auto-signé lors de devs en https local => dans le mes_options.php du site mettre : ```php define('_DEBUG_AUTORISER', true); ``` ce qui permet d'activer les options de curl pour ne pas vérifier le certificat dans _charger_pdf.php_ : ```php // pour une connexion https locale avec certificat auto-signé if (defined('_DEBUG_AUTORISER')) { curl_setopt($CurlConnect, CURLOPT_SSL_VERIFYHOST, false); curl_setopt($CurlConnect, CURLOPT_SSL_VERIFYPEER, false); } ```