# 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)
![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 inclure dans une page :
```html
<INCLURE{fond=inclure/gamumail_config,env}>
```
![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
<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})]</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_fichier.html -> à la fin du formulaire

### aide à la rédaction du contenu:
- le fichier **gamumail/remplacement_slugs.html** (surchargeable donc) 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** 
(= ceux fournis par le pipeline **remplacement_slugs**, cf ci-dessous)
- 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)]

<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 :
>
```php
/**
 * formulaire générique pour envoyer des mails avec pieces attachés
 *
 * @param string $slug modele du mail a charger
 * @param int|string $auteur  id_auteur ou email du destinataire
 * @param array $Tclient []['objet' => 'app_client', 'id_objet' => 3, 'champ' => 'email']
 * ou
 * ['objet' => 'app_client', 'id_objet' => 3, 'champ' => 'email']
 * @param array $Tpdf []['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
 * @return array $valeurs
 */
function formulaires_gamumail_charger_dist($slug, $auteur = 0, $Tclient = [], $Tpdf = [], $redirect = '', $options = []){
}
```
> l'Argument $Tclient est utilisé pour récupérer des emails dans un ou X autres Objets SPIP

#### 2. modification 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):
* pour charger : **gamumail/charger.php** pour tous les formulaires ou
* pour charger : **gamumail/SLUG_charger.php** avec une fonction :
```php
function gamumail_SLUG_charger($valeurs, $options = []){
	return $valeurs;
}
```
* pour verifier : **gamumail/verifier.php** pour tous les formulaires ou
* pour verifier : **gamumail/SLUG_verifier.php** avec une fonction :
```php
function gamumail_SLUG_verifier($erreurs, $options = []){
	return $erreurs;
}
```
* pour traiter : **gamumail/SLUG_traiter.php** avec une fonction ex:
```php
function gamumail_contrat_resa_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
```

#### 4. 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


## API d'envoi de mails utilisant les slugs
### fonction envoyer_gamumail()
- exemple d'appel : 
```php
$fonction = charger_fonction('envoyer_gamumail','inc');
$options = [
	'debug' => false, 
	'args' => ['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' ]
```