gamuMail

formulaire d'envoi de messages configurables

Il gere nativement :

• Pour
• Cc en meta : gamumail/mail_cc
• Cci en en meta : gamumail/mail_cci
• Sujet
• Texte
• Les documents attachés au modèle (cf ci-dessous)
• une liste de pdf (il faut le plugin spipdf)

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

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 :

<B_doc>
<h2>Fichiers attachés au séjour</h2>
	<div class="editer_groupe">
		<div class="editer editer_[(Tid_doc)]">
			<BOUCLE_doc(DOCUMENTS){id_article=#ENV{options/id_article}}{extension=pdf}>
				<div class="choix">
					<input type="checkbox" class="checkbox" name="Tid_doc[]" value="#ID_DOCUMENT" id="Tid_doc_#ID_DOCUMENT" checked="checked" >
					<label for="Tid_doc_#ID_DOCUMENT">
						<i class="fa fa-file-pdf-o rouge"></i>[ (#TITRE|sinon{#FICHIER|basename})] :
						 <a class="mediabox" href="#URL_DOCUMENT">voir le fichier</a>
					</label>
				</div>
			</BOUCLE_doc>
		</div>
	</div>
</B_doc>

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

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 :

$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 :

[(#AUTORISER{modifier,souscripteur,#ENV{id_auteur}}|sinon_interdire_acces)]

<BOUCLE_dest(AUTEURS){id_auteur=#ENV{dest}}{tout}>
	<div class="inner">
		<div class="ajax mbl">
			<h1>Envoyer un mail à [(#PRENOM|ucfirst) ][(#NOM|ucfirst)]</h1>

			<INCLURE{fond=inclure/envoyer_gamumail, env, id_destinataire=#ID_AUTEUR}>
		</div>
	</div>
</BOUCLE_dest>

Dans le php

1. Appel du formulaire

Args du formulaire :

/**
 * 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 :

<option value="no_gamumail"[ (#ENV{slug}|=={no_gamumail}|oui) selected="selected"]><:souscriptions:pas_de_mail_auto:></option>

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 :

[(#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 :

[(#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 :

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 :

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:

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 :

 * @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 <INCLURE{fond=inclure/fermer_modale,env}> 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 :

$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 :

 * @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' ]

Outrepasser l'erreur de certificat auto-signé lors de devs en https local

=> dans le mes_options.php du site mettre :

define('_DEBUG_AUTORISER', true);

ce qui permet d'activer les options de curl pour ne pas vérifier le certificat dans charger_pdf.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);
}